From bdaba901a7c4c5deb838e33058a6827b120d340f Mon Sep 17 00:00:00 2001 From: Casey Rodarmor Date: Sun, 10 Mar 2024 15:57:14 -0700 Subject: [PATCH 1/4] Create 0000-respect-lockfiles.md --- text/0000-respect-lockfiles.md | 91 ++++++++++++++++++++++++++++++++++ 1 file changed, 91 insertions(+) create mode 100644 text/0000-respect-lockfiles.md diff --git a/text/0000-respect-lockfiles.md b/text/0000-respect-lockfiles.md new file mode 100644 index 00000000000..d26e05914d3 --- /dev/null +++ b/text/0000-respect-lockfiles.md @@ -0,0 +1,91 @@ +- Feature Name: `respect-lockfiles` +- Start Date: 2024-03-10 +- RFC PR: [rust-lang/rfcs#0000](https://github.com/rust-lang/rfcs/pull/0000) +- Rust Issue: [rust-lang/rust#0000](https://github.com/rust-lang/rust/issues/0000) + +# Summary +[summary]: #summary + +Make `cargo install` respect lockfiles by default. + +# Motivation +[motivation]: #motivation + +Currently, `cargo install` does not respect `Cargo.lock` files without +`--locked`, using the latest semver-compatible dependencies. + +This causes dependees to break when a dependency releases a new +semver-compatible version with a compilation error or bug. + +By respecting the lockfile when running `cargo install`, these breakages are +avoided. + +Additionally, users often find it surprising that `cargo build` may succeed +when `cargo install` fails, and this avoids that surprise by giving them the +same behavior with respect to lockfiles. + +# Guide-level explanation +[guide-level-explanation]: #guide-level-explanation + +Since it is the default assumption that `cargo build` and `cargo install` have +the same behavior with respect to lockfiles, no documentation is needed beyond +existing documentation for `cargo build` and lockfiles. + +# Reference-level explanation +[reference-level-explanation]: #reference-level-explanation + +When running `cargo install`, lockfiles are respected. + +# Drawbacks +[drawbacks]: #drawbacks + +Currently, when running `cargo install`, the latest semver-compatible versions +of dependencies will be selected. This can be beneficial if these versions have +bugfixes. + +# Rationale and alternatives +[rationale-and-alternatives]: #rationale-and-alternatives + +The current behavior of `cargo install` is often surprising, since the default +assumption is that it behaves the same way as `cargo build`. Additionally, not +respecting lockfiles often causes issues, and those issues are usually +incorrectly reported to the dependee, and not the broken dependency. + +Some indications that the current behavior is problematic: + +- [Searching Google](https://www.google.com/search?q=cargo+install+broken+%22--locked%22) +turns up a large number of issues. + +- [Searching GitHub for `cargo install --locked`](https://github.com/search?q=%22cargo+install+--locked%22&type=code) + turns up a large number of results, suggesting that `cargo install --locked` + is often used, negating much of the possible benefit of respecting lockfiles. + +- [Searching markdown files on GitHub for `cargo install --locked`](https://github.com/search?q=path%3A*.md+%22cargo+install+--locked%22&type=code) + turns up a large number of results, suggesting that crate authors document + `cargo install --locked` as the way to install their crates, negating much of the possible benefit of respecting lockfiles. + +- [The GitHub issue discussing this](https://github.com/rust-lang/cargo/issues/7169) + has a great number of likes, and there are around 100 issues and PRs which link to the issue, + which are primary breakages caused by `cargo install` not respecting lockfiles. + +The benefit of not respecting lockfiles is that new versions of dependencies +may introduce bugfixes which `cargo install` will then pick up. However, new +versions of dependencies may also *introduce* bugs, which are more likely to +cause issues in dependees, since the old versions of the dependency have been +tested in the dependee, and the new versions have not. + +One possible alternative is to add a `--unlocked` flag, and require that one of +`--locked` and `--unlocked` be passed to `cargo install`, avoiding the element +of surprise. This however would be extremely disruptive, as all instances of +`cargo install` invocations not using `--locked` would need to be changed. + +The impact of not doing this is continued issues and breakages stemming from +the surprising behavior of `cargo install`. + +# Prior art +[prior-art]: #prior-art + +I checked, and Node JS respects lockfiles when installing binaries. It would be +helpful if those familiar with others could confirm whether or not other +popular programming language package managers respect lockfiles when installing +binaries. From cf8409db95bc7ff5efcb8d2f4c4c84344781c673 Mon Sep 17 00:00:00 2001 From: Casey Rodarmor Date: Sun, 10 Mar 2024 16:33:54 -0700 Subject: [PATCH 2/4] Add note about reproducability --- text/0000-respect-lockfiles.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/text/0000-respect-lockfiles.md b/text/0000-respect-lockfiles.md index d26e05914d3..16a536b9f6c 100644 --- a/text/0000-respect-lockfiles.md +++ b/text/0000-respect-lockfiles.md @@ -74,6 +74,14 @@ versions of dependencies may also *introduce* bugs, which are more likely to cause issues in dependees, since the old versions of the dependency have been tested in the dependee, and the new versions have not. +Additionally, this makes tracking down issues in a built binary very difficult. +If a user has installed a binary with `cargo install`, and then reports issues +with that binary, even if the version of the binary is known, it is +more-or-less impossible to know which versions of which dependencies were used, +since it depends on *when* `cargo install` was run, and the update history of +all dependencies. This makes `cargo install`ed binaries essential black boxes +with unknown dependency versions. + One possible alternative is to add a `--unlocked` flag, and require that one of `--locked` and `--unlocked` be passed to `cargo install`, avoiding the element of surprise. This however would be extremely disruptive, as all instances of From 10eeb07855a4474caec80d3d4d4937a7d5faf259 Mon Sep 17 00:00:00 2001 From: Casey Rodarmor Date: Sun, 10 Mar 2024 16:35:32 -0700 Subject: [PATCH 3/4] Add another note about reproducability --- text/0000-respect-lockfiles.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/text/0000-respect-lockfiles.md b/text/0000-respect-lockfiles.md index 16a536b9f6c..45a6ee2b6ec 100644 --- a/text/0000-respect-lockfiles.md +++ b/text/0000-respect-lockfiles.md @@ -82,6 +82,12 @@ since it depends on *when* `cargo install` was run, and the update history of all dependencies. This makes `cargo install`ed binaries essential black boxes with unknown dependency versions. +Also, reproducability is valuable even in the absence of issues, as +reproducability allows, for example, maintainers to sign release binaries, and +allow others to confirm that those release binaries were correctly built from +source by comparing the hash of the built binary with the hash of the released +binary. + One possible alternative is to add a `--unlocked` flag, and require that one of `--locked` and `--unlocked` be passed to `cargo install`, avoiding the element of surprise. This however would be extremely disruptive, as all instances of From 2855e36bee6123006320762e524cbaeff4e4683c Mon Sep 17 00:00:00 2001 From: Casey Rodarmor Date: Sun, 17 Mar 2024 12:36:25 -0700 Subject: [PATCH 4/4] Add the ability to use `cargo install --locked` to opt-in to not respecting lockfiles --- text/0000-respect-lockfiles.md | 14 +++++++++++++- 1 file changed, 13 insertions(+), 1 deletion(-) diff --git a/text/0000-respect-lockfiles.md b/text/0000-respect-lockfiles.md index 45a6ee2b6ec..0470cf6628a 100644 --- a/text/0000-respect-lockfiles.md +++ b/text/0000-respect-lockfiles.md @@ -8,6 +8,9 @@ Make `cargo install` respect lockfiles by default. +Allow opting-in to installing with latest semver-compatible dependencies with +`cargo install --unlocked`. + # Motivation [motivation]: #motivation @@ -34,7 +37,13 @@ existing documentation for `cargo build` and lockfiles. # Reference-level explanation [reference-level-explanation]: #reference-level-explanation -When running `cargo install`, lockfiles are respected. +When running `cargo install`, both with a path, i.e., `cargo install --path +PATH`, and with a crate name to be installed from +[crates.io](https://crates.io), i.e., `cargo install CRATE`, lockfiles are +respected. + +To install a crate with the latest semver-compatible version, pass `--unlocked` +to `cargo install`. # Drawbacks [drawbacks]: #drawbacks @@ -93,6 +102,9 @@ One possible alternative is to add a `--unlocked` flag, and require that one of of surprise. This however would be extremely disruptive, as all instances of `cargo install` invocations not using `--locked` would need to be changed. +Another alternative is to add a field to `Cargo.toml`, `locked`, which if +`true`, make `cargo install` respect the lockfile. + The impact of not doing this is continued issues and breakages stemming from the surprising behavior of `cargo install`.