Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

cargo guide: guidance around selecting the version of a dependency? #10624

Open
kevinushey opened this issue May 2, 2022 · 6 comments
Open
Labels
A-crate-dependencies Area: [dependencies] of any kind A-documenting-cargo-itself Area: Cargo's documentation C-feature-request Category: proposal for a feature. Before PR, ping rust-lang/cargo if this is not `Feature accepted` Command-add S-triage Status: This issue is waiting on initial triage.

Comments

@kevinushey
Copy link

Problem

In the cargo guide, the page on dependencies (https://doc.rust-lang.org/cargo/guide/dependencies.html) describes how one can add specific versions of a couple dependencies, e.g. by editing Cargo.toml:

[package]
name = "hello_world"
version = "0.1.0"
edition = "2021"

[dependencies]
time = "0.1.12"
regex = "0.1.41"

and then links to external documentation regarding SemVer and how other / newer versions of packages could be requested.

However, the documentation doesn't provide any specific guidance around how one should normally choose the versions of their dependencies. Is there any existing convention in the community? For example:

  • Prefer using the latest major release?
  • Look at the documentation on crates.io, and make a choice there?
  • Use an external tool to add dependencies to the project?

It might also be worth documenting the use of cargo add, once #2179 becomes part of stable.

It would also be nice if the crate versions chosen in this documentation matched a more current version (regex is currently 1.5.5, based on https://crates.io/crates/regex).

Proposed Solution

  • Consider providing some guidance for users on how dependency versioning should be done.
    • In particular, note if there are any consequences for downstream users if you plan to build a rust library?
  • Document and describe the use of cargo add?

Notes

No response

@kevinushey kevinushey added the C-feature-request Category: proposal for a feature. Before PR, ping rust-lang/cargo if this is not `Feature accepted` label May 2, 2022
@kevinushey
Copy link
Author

I also stumbled on a semi-related entry in the FAQ:

https://doc.rust-lang.org/cargo/faq.html#can-libraries-use--as-a-version-for-their-dependencies

which I think implicitly recommends versioning of the form 1.4.* or 1.*.

@epage
Copy link
Contributor

epage commented May 2, 2022

For how precise to be, there was a users thread on that subject.

It might also be worth documenting the use of cargo add, once #2179 becomes part of stable.

In addition to the guide page, we should also consider the reference page. The former can focus more on cargo add but the latter needs to go into all the details and not get distracted too much with cargo add. Both can cross-link to cargo add's documentation page.

We've also talked about getting crates.io to be updated to reference cargo add.

@epage epage added A-documenting-cargo-itself Area: Cargo's documentation A-crate-dependencies Area: [dependencies] of any kind Command-add labels May 2, 2022
@harrybraviner
Copy link

@kevinushey - I agree with you about your interpretation somewhat. That FAQ answer is saying that you may use 1.* or 1.4.* (at least for a package published to crates.io), but it isn't recommending that you do so.

If the package is following semantic versioning, the constraint I would like is "MAJOR number must be exactly X, MINOR number and PATCH must be at least Y.Z". But I don't know if I can enforce that in Cargo?

The other question I don't know the answer to, but it seems relevant, is this: Suppose my package A depends on packaged B and C. And B and C both depend on package D. Is my build of package A faster if B and C depend on the same version of D?

Sorry I'm not adding answers here - I'm just flagging some ways that I, as a relatively inexperienced Cargo user, also get confused.

@Eh2406
Copy link
Contributor

Eh2406 commented May 3, 2022

"MAJOR number must be exactly X, MINOR number and PATCH must be at least Y.Z". But I don't know if I can enforce that in Cargo?

You are looking for the ^ requirement, witch is also the one you get if you do not use a symbol. ^X.Y.Z or X.Y.Z (If X is 0, then it is MINOR number must be exactly Y, PATCH must be at least Z")

Is my build of package A faster if B and C depend on the same version of D?

Yes, Clean builds will generally be faster when things unify. But, developers want the latest changes from there deps and want a way to upgrade. As a compromise, Cargo will try to get the largess version for each dep (even if that means having D 1.0.0 and D 2.0.0 in the tree), but will only select one semver compatible version in each category (so a requirement ^1.0 may resolve to 1.5 even if 1.9 is available so that it can unify with some other requirement >=1.0, <=1.5).

@matschaffer
Copy link

This might deserve it's own issue, but I found my way here wishing that cargo add could resolve the version for me, but leave out the patch version. Maybe something like this?

cargo add (crate) --minor

I love that cargo add can go find the latest version for me, I just don't want it to lock all the way to the patch version.

As a workaround I run add then remove the patch version from my Cargo.toml manually.

@epage
Copy link
Contributor

epage commented Aug 25, 2022

People have requested options for controlling the precision but I've generally pushed back

However, to support people who do customize their precision, cargo upgrade preserves the existing precision.

@epage epage added the S-triage Status: This issue is waiting on initial triage. label Nov 20, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
A-crate-dependencies Area: [dependencies] of any kind A-documenting-cargo-itself Area: Cargo's documentation C-feature-request Category: proposal for a feature. Before PR, ping rust-lang/cargo if this is not `Feature accepted` Command-add S-triage Status: This issue is waiting on initial triage.
Projects
None yet
Development

No branches or pull requests

5 participants