Skip to content

Commit 447ccb4

Browse files
committed
Auto merge of #11763 - jofas:fix-for-11660, r=weihanglo
Added documentation for the configuration discovery of `cargo install` to the man pages Fixes #11660.
2 parents 964b730 + e011901 commit 447ccb4

File tree

4 files changed

+41
-1
lines changed

4 files changed

+41
-1
lines changed

src/doc/man/cargo-install.md

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -55,6 +55,8 @@ specified by setting the `CARGO_TARGET_DIR` environment variable to a relative
5555
path. In particular, this can be useful for caching build artifacts on
5656
continuous integration systems.
5757

58+
### Dealing with the Lockfile
59+
5860
By default, the `Cargo.lock` file that is included with the package will be
5961
ignored. This means that Cargo will recompute which versions of dependencies
6062
to use, possibly using newer versions that have been released since the
@@ -69,6 +71,16 @@ not start publishing `Cargo.lock` files until version 1.37, which means
6971
packages published with prior versions will not have a `Cargo.lock` file
7072
available.
7173

74+
### Configuration Discovery
75+
76+
This command operates on system or user level, not project level.
77+
This means that the local [configuration discovery] is ignored.
78+
Instead, the configuration discovery begins at `$CARGO_HOME/config.toml`.
79+
If the package is installed with `--path $PATH`, the local configuration
80+
will be used, beginning discovery at `$PATH/.cargo/config.toml`.
81+
82+
[configuration discovery]: ../reference/config.html#hierarchical-structure
83+
7284
## OPTIONS
7385

7486
### Install Options

src/doc/man/generated_txt/cargo-install.txt

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -65,6 +65,7 @@ DESCRIPTION
6565
variable to a relative path. In particular, this can be useful for
6666
caching build artifacts on continuous integration systems.
6767

68+
Dealing with the Lockfile
6869
By default, the Cargo.lock file that is included with the package will
6970
be ignored. This means that Cargo will recompute which versions of
7071
dependencies to use, possibly using newer versions that have been
@@ -79,6 +80,15 @@ DESCRIPTION
7980
Cargo.lock files until version 1.37, which means packages published with
8081
prior versions will not have a Cargo.lock file available.
8182

83+
Configuration Discovery
84+
This command operates on system or user level, not project level. This
85+
means that the local configuration discovery
86+
<https://doc.rust-lang.org/cargo/reference/config.html#hierarchical-structure>
87+
is ignored. Instead, the configuration discovery begins at
88+
$CARGO_HOME/config.toml. If the package is installed with --path $PATH,
89+
the local configuration will be used, beginning discovery at
90+
$PATH/.cargo/config.toml.
91+
8292
OPTIONS
8393
Install Options
8494
--vers version, --version version

src/doc/src/commands/cargo-install.md

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -62,6 +62,8 @@ specified by setting the `CARGO_TARGET_DIR` environment variable to a relative
6262
path. In particular, this can be useful for caching build artifacts on
6363
continuous integration systems.
6464

65+
### Dealing with the Lockfile
66+
6567
By default, the `Cargo.lock` file that is included with the package will be
6668
ignored. This means that Cargo will recompute which versions of dependencies
6769
to use, possibly using newer versions that have been released since the
@@ -76,6 +78,16 @@ not start publishing `Cargo.lock` files until version 1.37, which means
7678
packages published with prior versions will not have a `Cargo.lock` file
7779
available.
7880

81+
### Configuration Discovery
82+
83+
This command operates on system or user level, not project level.
84+
This means that the local [configuration discovery] is ignored.
85+
Instead, the configuration discovery begins at `$CARGO_HOME/config.toml`.
86+
If the package is installed with `--path $PATH`, the local configuration
87+
will be used, beginning discovery at `$PATH/.cargo/config.toml`.
88+
89+
[configuration discovery]: ../reference/config.html#hierarchical-structure
90+
7991
## OPTIONS
8092

8193
### Install Options

src/etc/man/cargo-install.1

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -87,7 +87,7 @@ in a temporary target directory. To avoid this, the target directory can be
8787
specified by setting the \fBCARGO_TARGET_DIR\fR environment variable to a relative
8888
path. In particular, this can be useful for caching build artifacts on
8989
continuous integration systems.
90-
.sp
90+
.SS "Dealing with the Lockfile"
9191
By default, the \fBCargo.lock\fR file that is included with the package will be
9292
ignored. This means that Cargo will recompute which versions of dependencies
9393
to use, possibly using newer versions that have been released since the
@@ -101,6 +101,12 @@ will not receive any fixes or updates to any dependency. Note that Cargo did
101101
not start publishing \fBCargo.lock\fR files until version 1.37, which means
102102
packages published with prior versions will not have a \fBCargo.lock\fR file
103103
available.
104+
.SS "Configuration Discovery"
105+
This command operates on system or user level, not project level.
106+
This means that the local \fIconfiguration discovery\fR <https://doc.rust\-lang.org/cargo/reference/config.html#hierarchical\-structure> is ignored.
107+
Instead, the configuration discovery begins at \fB$CARGO_HOME/config.toml\fR\&.
108+
If the package is installed with \fB\-\-path $PATH\fR, the local configuration
109+
will be used, beginning discovery at \fB$PATH/.cargo/config.toml\fR\&.
104110
.SH "OPTIONS"
105111
.SS "Install Options"
106112
.sp

0 commit comments

Comments
 (0)