Add chapters on dependency resolution and SemVer compatibility. #8609
Conversation
|
r? @Eh2406 (rust_highfive has picked a reviewer for you, use r? to override) |
rust-highfive
added
the
S-waiting-on-review
src/doc/src/reference/resolver.md
Outdated
| ### `links` | ||
|
|
||
| The [`links` field] is used to ensure only one copy of a native library is | ||
| linked into a binary. It is an error if multiple SemVer-incompatible versions |
There was a problem hiding this comment.
This is all true, but I feel the tone is a little harsh. The resolver will attempt to find a graph where there is only one, and only throw an error if there is no graph that works. Above you used the phrase "will fail because" for the analogous situation with SemVer-compatible versions, where here it is introduced with "is an error".
There was a problem hiding this comment.
I tried to tweak the wording a bit, let me know if that works.
| features. For example, if a package depends on version `^1` of [`regex`] with | ||
| the [`perf` feature], then the oldest version it can select is `1.3.0`, | ||
| because versions prior to that did not contain the `perf` feature. Similarly, | ||
| if a feature is removed from a new release, then packages that require that |
There was a problem hiding this comment.
Is it worth calling out the case of making an optional dependency non-optional, which is an easy way to accidentally remove a feature?
|
@bors r+ |
|
📌 Commit 006023c has been approved by |
bors
added
S-waiting-on-bors
|
☀️ Test successful - checks-actions |
Update cargo 5 commits in ab32ee88dade1b50c77347599e82ca2de3fb8a51..51b66125ba97d2906f461b3f4e0408f206299bb6 2020-08-10 17:44:43 +0000 to 2020-08-19 20:22:52 +0000 - Add chapters on dependency resolution and SemVer compatibility. (rust-lang/cargo#8609) - Renames SourceId::into_url -> SourceId::as_url (rust-lang/cargo#8611) - Fix bug with PathAndArg config values (rust-lang/cargo#8629) - Show full error context on `cargo run` error. (rust-lang/cargo#8627) - Fix typo in SIGQUIT description (rust-lang/cargo#8615)
This adds two documentation chapters, one on the resolver and one on SemVer compatibility. These are intended to help guide users on how to version their package and how to use dependencies.
I did not document
[patch]resolution. Perhaps someday in the future the the "Overriding dependencies" chapter can be expanded to include more details on how patch works, and how to properly use it. I have a bunch of notes on this, but I want to defer it till later.The SemVer compatibility guidelines were guided by RFC 1105, but are edited and expanded based on my own personal observations. I tried to highlight when some rules do not appear to have consensus on behavior. I would be happy for any additions or modifications to the rule list. I have a list of additional things to add, but I wanted to get the ball rolling, and it might take a while finish them.
Each compatibility entry has an example, and there is a small script which tests all the examples to ensure they work like they are supposed to. This script checks against the compiler output, which can be fragile over time. If that becomes too troublesome, we can probably find some more relaxed checks. I think checking the error is important because I've run into cases in the past where using basic "compile_fail" annotations were misleading because the examples were failing for the wrong reason.
Closes #7301