From 01e1ff0484b62db28f0a7e231a3a7ad5f7439bca Mon Sep 17 00:00:00 2001 From: Kyle J Strand Date: Wed, 14 Jun 2023 11:14:34 -0700 Subject: [PATCH 1/2] Squash: * Explain how `version` works for `git` dependencies * Link to multiple-locations, since this is already explained there * more extensive rewrite --- .../src/reference/specifying-dependencies.md | 44 ++++++++++++++----- 1 file changed, 32 insertions(+), 12 deletions(-) diff --git a/src/doc/src/reference/specifying-dependencies.md b/src/doc/src/reference/specifying-dependencies.md index f044af95b46..45328b75701 100644 --- a/src/doc/src/reference/specifying-dependencies.md +++ b/src/doc/src/reference/specifying-dependencies.md @@ -53,12 +53,14 @@ and `x > 0`. It is possible to further tweak the logic for selecting compatible versions using special operators, though it shouldn't be necessary most of the time. -### Caret requirements +### Version requirement syntax + +#### Caret requirements **Caret requirements** are an alternative syntax for the default strategy, `^1.2.3` is exactly equivalent to `1.2.3`. -### Tilde requirements +#### Tilde requirements **Tilde requirements** specify a minimal version with some ability to update. If you specify a major, minor, and patch version or only a major and minor @@ -73,7 +75,7 @@ version, then minor- and patch-level changes are allowed. ~1 := >=1.0.0, <2.0.0 ``` -### Wildcard requirements +#### Wildcard requirements **Wildcard requirements** allow for any version where the wildcard is positioned. @@ -88,7 +90,7 @@ positioned. > **Note**: [crates.io] does not allow bare `*` versions. -### Comparison requirements +#### Comparison requirements **Comparison requirements** allow manually specifying a version range or an exact version to depend on. @@ -102,7 +104,7 @@ Here are some examples of comparison requirements: = 1.2.3 ``` -### Multiple requirements +#### Multiple version requirements As shown in the examples above, multiple version requirements can be separated with a comma, e.g., `>= 1.2, < 1.5`. @@ -157,7 +159,7 @@ some-crate = { version = "1.0", registry = "my-registry" } ``` > **Note**: [crates.io] does not allow packages to be published with -> dependencies on other registries. +> dependencies on code published outside of [crates.io]. [registries documentation]: registries.md @@ -195,6 +197,15 @@ varies by where the repo is hosted; GitHub in particular exposes a reference to the most recent commit of every pull request as shown, but other git hosts often provide something equivalent, possibly under a different naming scheme. +> **Note**: Neither the `git` key nor the `path` key changes the meaning of the +> `version` key: the `version` key always implies that the package is available +> in a registry. `version`, `git`, and `path` keys are considered [separate +> locations](#multiple-locations) for resolving the dependency. +> +> When the dependency is retrieved from `git`, the `version` key will _not_ +> affect which commit is used, but the version information in the dependency's +> `Cargo.toml` file will still be validated against the `version` requirement. + Once a `git` dependency has been added, Cargo will lock that dependency to the latest commit at the time. New commits will not be pulled down automatically once the lock is in place. However, they can be pulled down manually with @@ -202,9 +213,11 @@ once the lock is in place. However, they can be pulled down manually with See [Git Authentication] for help with git authentication for private repos. -> **Note**: [crates.io] does not allow packages to be published with `git` -> dependencies (`git` [dev-dependencies] are ignored). See the [Multiple -> locations](#multiple-locations) section for a fallback alternative. +> **Note**: [crates.io] does not allow packages to be published with +> dependencies on code published outside of [crates.io] itself +> ([dev-dependencies] are ignored). See the [Multiple +> locations](#multiple-locations) section for a fallback alternative for `git` +> and `path` dependencies. [Git Authentication]: ../appendix/git-authentication.md @@ -245,9 +258,16 @@ and specify its version in the dependencies line as well: hello_utils = { path = "hello_utils", version = "0.1.0" } ``` -> **Note**: [crates.io] does not allow packages to be published with `path` -> dependencies (`path` [dev-dependencies] are ignored). See the [Multiple -> locations](#multiple-locations) section for a fallback alternative. +> **Note**: Neither the `git` key nor the `path` key changes the meaning of the +> `version` key: the `version` key always implies that the package is available +> in a registry. `version`, `git`, and `path` keys are considered [separate +> locations](#multiple-locations) for resolving the dependency. + +> **Note**: [crates.io] does not allow packages to be published with +> dependencies on code published outside of [crates.io] itself +> ([dev-dependencies] are ignored). See the [Multiple +> locations](#multiple-locations) section for a fallback alternative for `git` +> and `path` dependencies. ### Multiple locations From 7a7bddb5ad3e25dbb49b58c2239ea8d51a77f037 Mon Sep 17 00:00:00 2001 From: Kyle J Strand Date: Sun, 27 Aug 2023 20:03:33 -0600 Subject: [PATCH 2/2] move notes together --- src/doc/src/reference/specifying-dependencies.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/src/doc/src/reference/specifying-dependencies.md b/src/doc/src/reference/specifying-dependencies.md index 45328b75701..56a33eb2cc6 100644 --- a/src/doc/src/reference/specifying-dependencies.md +++ b/src/doc/src/reference/specifying-dependencies.md @@ -197,6 +197,13 @@ varies by where the repo is hosted; GitHub in particular exposes a reference to the most recent commit of every pull request as shown, but other git hosts often provide something equivalent, possibly under a different naming scheme. +Once a `git` dependency has been added, Cargo will lock that dependency to the +latest commit at the time. New commits will not be pulled down automatically +once the lock is in place. However, they can be pulled down manually with +`cargo update`. + +See [Git Authentication] for help with git authentication for private repos. + > **Note**: Neither the `git` key nor the `path` key changes the meaning of the > `version` key: the `version` key always implies that the package is available > in a registry. `version`, `git`, and `path` keys are considered [separate @@ -206,13 +213,6 @@ provide something equivalent, possibly under a different naming scheme. > affect which commit is used, but the version information in the dependency's > `Cargo.toml` file will still be validated against the `version` requirement. -Once a `git` dependency has been added, Cargo will lock that dependency to the -latest commit at the time. New commits will not be pulled down automatically -once the lock is in place. However, they can be pulled down manually with -`cargo update`. - -See [Git Authentication] for help with git authentication for private repos. - > **Note**: [crates.io] does not allow packages to be published with > dependencies on code published outside of [crates.io] itself > ([dev-dependencies] are ignored). See the [Multiple