From 25409e56bb4942b6c34fe50ddd94bb2075822176 Mon Sep 17 00:00:00 2001 From: huangjiahua Date: Thu, 16 Apr 2020 23:18:34 +0800 Subject: [PATCH] Update documentation to mention "config.toml" and "credentials.toml" instead of "config" and "credentials" Cargo now support loading 'config.toml' and 'credentials.toml' in place of the same files without extension, which used to be the default. Files with extensions are easier for people to edit due to syntax highlighting, etc. --- src/doc/man/cargo-login.adoc | 2 +- src/doc/man/cargo-vendor.adoc | 4 ++-- src/doc/man/cargo.adoc | 8 +++---- src/doc/man/generated/cargo-login.html | 2 +- src/doc/man/generated/cargo-vendor.html | 4 ++-- src/doc/man/generated/cargo.html | 8 +++---- src/doc/src/guide/cargo-home.md | 4 ++-- src/doc/src/reference/config.md | 22 +++++++++---------- .../src/reference/environment-variables.md | 2 +- .../src/reference/overriding-dependencies.md | 4 ++-- src/doc/src/reference/publishing.md | 2 +- src/doc/src/reference/registries.md | 6 ++--- src/doc/src/reference/source-replacement.md | 4 ++-- .../src/reference/specifying-dependencies.md | 2 +- src/doc/src/reference/unstable.md | 6 ++--- src/etc/man/cargo-login.1 | 6 ++--- src/etc/man/cargo-vendor.1 | 8 +++---- src/etc/man/cargo.1 | 12 +++++----- 18 files changed, 53 insertions(+), 53 deletions(-) diff --git a/src/doc/man/cargo-login.adoc b/src/doc/man/cargo-login.adoc index 17d0e66ad41..2d3a8e7527b 100644 --- a/src/doc/man/cargo-login.adoc +++ b/src/doc/man/cargo-login.adoc @@ -14,7 +14,7 @@ cargo-login - Save an API token from the registry locally This command will save the API token to disk so that commands that require authentication, such as man:cargo-publish[1], will be automatically -authenticated. The token is saved in `$CARGO_HOME/credentials`. `CARGO_HOME` +authenticated. The token is saved in `$CARGO_HOME/credentials.toml`. `CARGO_HOME` defaults to `.cargo` in your home directory. If the _TOKEN_ argument is not specified, it will be read from stdin. diff --git a/src/doc/man/cargo-vendor.adoc b/src/doc/man/cargo-vendor.adoc index ae7401f6028..d1d3fc3bb87 100644 --- a/src/doc/man/cargo-vendor.adoc +++ b/src/doc/man/cargo-vendor.adoc @@ -19,7 +19,7 @@ dependencies specified. Additional manifests beyond the default one can be specified with the `-s` option. The `cargo vendor` command will also print out the configuration necessary -to use the vendored sources, which you will need to add to `.cargo/config`. +to use the vendored sources, which you will need to add to `.cargo/config.toml`. == OPTIONS @@ -35,7 +35,7 @@ to use the vendored sources, which you will need to add to `.cargo/config`. existing contents of the vendor directory *--respect-source-config*:: - Instead of ignoring `[source]` configuration by default in `.cargo/config` + Instead of ignoring `[source]` configuration by default in `.cargo/config.toml` read it and use it when downloading crates from crates.io, for example *--versioned-dirs*:: diff --git a/src/doc/man/cargo.adoc b/src/doc/man/cargo.adoc index 90e5e3485ca..59c7b1fccc9 100644 --- a/src/doc/man/cargo.adoc +++ b/src/doc/man/cargo.adoc @@ -169,16 +169,16 @@ include::section-exit-status.adoc[] Binaries installed by man:cargo-install[1] will be located here. If using rustup, executables distributed with Rust are also located here. -`$CARGO_HOME/config`:: +`$CARGO_HOME/config.toml`:: The global configuration file. See linkcargo:reference/config.html[the reference] for more information about configuration files. -`.cargo/config`:: - Cargo automatically searches for a file named `.cargo/config` in the +`.cargo/config.toml`:: + Cargo automatically searches for a file named `.cargo/config.toml` in the current directory, and all parent directories. These configuration files will be merged with the global configuration file. -`$CARGO_HOME/credentials`:: +`$CARGO_HOME/credentials.toml`:: Private authentication information for logging in to a registry. `$CARGO_HOME/registry/`:: diff --git a/src/doc/man/generated/cargo-login.html b/src/doc/man/generated/cargo-login.html index d913311730e..6c8f9b9c7ca 100644 --- a/src/doc/man/generated/cargo-login.html +++ b/src/doc/man/generated/cargo-login.html @@ -16,7 +16,7 @@

DESCRIPTION

This command will save the API token to disk so that commands that require authentication, such as cargo-publish(1), will be automatically -authenticated. The token is saved in $CARGO_HOME/credentials. CARGO_HOME +authenticated. The token is saved in $CARGO_HOME/credentials.toml. CARGO_HOME defaults to .cargo in your home directory.

diff --git a/src/doc/man/generated/cargo-vendor.html b/src/doc/man/generated/cargo-vendor.html index 4535302d819..8bb29636480 100644 --- a/src/doc/man/generated/cargo-vendor.html +++ b/src/doc/man/generated/cargo-vendor.html @@ -22,7 +22,7 @@

DESCRIPTION

The cargo vendor command will also print out the configuration necessary -to use the vendored sources, which you will need to add to .cargo/config.

+to use the vendored sources, which you will need to add to .cargo/config.toml.

@@ -46,7 +46,7 @@

Vendor Options

--respect-source-config
-

Instead of ignoring [source] configuration by default in .cargo/config +

Instead of ignoring [source] configuration by default in .cargo/config.toml read it and use it when downloading crates from crates.io, for example

--versioned-dirs
diff --git a/src/doc/man/generated/cargo.html b/src/doc/man/generated/cargo.html index 52b4abe01ec..fc74ab7bfe0 100644 --- a/src/doc/man/generated/cargo.html +++ b/src/doc/man/generated/cargo.html @@ -354,18 +354,18 @@

FILES

Binaries installed by cargo-install(1) will be located here. If using rustup, executables distributed with Rust are also located here.

-
$CARGO_HOME/config
+
$CARGO_HOME/config.toml

The global configuration file. See the reference for more information about configuration files.

-
.cargo/config
+
.cargo/config.toml
-

Cargo automatically searches for a file named .cargo/config in the +

Cargo automatically searches for a file named .cargo/config.toml in the current directory, and all parent directories. These configuration files will be merged with the global configuration file.

-
$CARGO_HOME/credentials
+
$CARGO_HOME/credentials.toml

Private authentication information for logging in to a registry.

diff --git a/src/doc/src/guide/cargo-home.md b/src/doc/src/guide/cargo-home.md index fa2e2f98523..a178b184694 100644 --- a/src/doc/src/guide/cargo-home.md +++ b/src/doc/src/guide/cargo-home.md @@ -12,10 +12,10 @@ The Cargo home consists of following components: ## Files: -* `config` +* `config.toml` Cargo's global configuration file, see the [config entry in the reference][config]. -* `credentials` +* `credentials.toml` Private login credentials from [`cargo login`] in order to log in to a registry. * `.crates.toml` diff --git a/src/doc/src/reference/config.md b/src/doc/src/reference/config.md index e60b2ad050d..eb87ab05681 100644 --- a/src/doc/src/reference/config.md +++ b/src/doc/src/reference/config.md @@ -12,14 +12,14 @@ all parent directories. If, for example, Cargo were invoked in `/projects/foo/bar/baz`, then the following configuration files would be probed for and unified in this order: -* `/projects/foo/bar/baz/.cargo/config` -* `/projects/foo/bar/.cargo/config` -* `/projects/foo/.cargo/config` -* `/projects/.cargo/config` -* `/.cargo/config` -* `$CARGO_HOME/config` which defaults to: - * Windows: `%USERPROFILE%\.cargo\config` - * Unix: `$HOME/.cargo/config` +* `/projects/foo/bar/baz/.cargo/config.toml` +* `/projects/foo/bar/.cargo/config.toml` +* `/projects/foo/.cargo/config.toml` +* `/projects/.cargo/config.toml` +* `/.cargo/config.toml` +* `$CARGO_HOME/config.toml` which defaults to: + * Windows: `%USERPROFILE%\.cargo\config.toml` + * Unix: `$HOME/.cargo/config.toml` With this structure, you can specify configuration per-package, and even possibly check it into version control. You can also specify personal defaults @@ -179,15 +179,15 @@ relative to the current working directory. runner = "foo" # Searches `PATH` for `foo`. [source.vendored-sources] -# Directory is relative to the parent where `.cargo/config` is located. -# For example, `/my/project/.cargo/config` would result in `/my/project/vendor`. +# Directory is relative to the parent where `.cargo/config.toml` is located. +# For example, `/my/project/.cargo/config.toml` would result in `/my/project/vendor`. directory = "vendor" ``` ### Credentials Configuration values with sensitive information are stored in the -`$CARGO_HOME/credentials` file. This file is automatically created and updated +`$CARGO_HOME/credentials.toml` file. This file is automatically created and updated by [`cargo login`]. It follows the same format as Cargo config files. ```toml diff --git a/src/doc/src/reference/environment-variables.md b/src/doc/src/reference/environment-variables.md index 00af923a9e3..bb03e5ef454 100644 --- a/src/doc/src/reference/environment-variables.md +++ b/src/doc/src/reference/environment-variables.md @@ -294,7 +294,7 @@ let out_dir = env::var("OUT_DIR").unwrap(); use it as well. * `RUSTC_LINKER` — The path to the linker binary that Cargo has resolved to use for the current target, if specified. The linker can be - changed by editing `.cargo/config`; see the documentation + changed by editing `.cargo/config.toml`; see the documentation about [cargo configuration][cargo-config] for more information. diff --git a/src/doc/src/reference/overriding-dependencies.md b/src/doc/src/reference/overriding-dependencies.md index fc5308d07a3..6cad545b79b 100644 --- a/src/doc/src/reference/overriding-dependencies.md +++ b/src/doc/src/reference/overriding-dependencies.md @@ -318,8 +318,8 @@ to modify `Cargo.toml` like with the `[patch]` section above. For this use case Cargo offers a much more limited version of overrides called **path overrides**. -Path overrides are specified through [`.cargo/config`](config.md) instead of -`Cargo.toml`. Inside of `.cargo/config` you'll specify a key called `paths`: +Path overrides are specified through [`.cargo/config.toml`](config.md) instead of +`Cargo.toml`. Inside of `.cargo/config.toml` you'll specify a key called `paths`: ```toml paths = ["/path/to/uuid"] diff --git a/src/doc/src/reference/publishing.md b/src/doc/src/reference/publishing.md index 88e6f888fde..3007a278dbc 100644 --- a/src/doc/src/reference/publishing.md +++ b/src/doc/src/reference/publishing.md @@ -21,7 +21,7 @@ $ cargo login abcdefghijklmnopqrstuvwxyz012345 ``` This command will inform Cargo of your API token and store it locally in your -`~/.cargo/credentials`. Note that this token is a **secret** and should not be +`~/.cargo/credentials.toml`. Note that this token is a **secret** and should not be shared with anyone else. If it leaks for any reason, you should regenerate it immediately. diff --git a/src/doc/src/reference/registries.md b/src/doc/src/reference/registries.md index e404327860a..33d4955bbe0 100644 --- a/src/doc/src/reference/registries.md +++ b/src/doc/src/reference/registries.md @@ -11,7 +11,7 @@ support publishing new crates directly from Cargo. ### Using an Alternate Registry To use a registry other than [crates.io], the name and index URL of the -registry must be added to a [`.cargo/config` file][config]. The `registries` +registry must be added to a [`.cargo/config.toml` file][config]. The `registries` table has a key for each registry, for example: ```toml @@ -63,7 +63,7 @@ registry to use. For example, to publish the package in the current directory: 2. `cargo publish --registry=my-registry` Instead of always passing the `--registry` command-line option, the default -registry may be set in [`.cargo/config`][config] with the `registry.default` +registry may be set in [`.cargo/config.toml`][config] with the `registry.default` key. Setting the `package.publish` key in the `Cargo.toml` manifest restricts which @@ -81,7 +81,7 @@ The `publish` value may also be `false` to restrict all publishing, which is the same as an empty list. The authentication information saved by [`cargo login`] is stored in the -`credentials` file in the Cargo home directory (default `$HOME/.cargo`). It +`credentials.toml` file in the Cargo home directory (default `$HOME/.cargo`). It has a separate table for each registry, for example: ```toml diff --git a/src/doc/src/reference/source-replacement.md b/src/doc/src/reference/source-replacement.md index 7e59ff96735..80f363899c9 100644 --- a/src/doc/src/reference/source-replacement.md +++ b/src/doc/src/reference/source-replacement.md @@ -31,7 +31,7 @@ chapter][registries]. ### Configuration -Configuration of replacement sources is done through [`.cargo/config`][config] +Configuration of replacement sources is done through [`.cargo/config.toml`][config] and the full set of available keys are: ```toml @@ -42,7 +42,7 @@ and the full set of available keys are: # Under the `source` table are a number of other tables whose keys are a # name for the relevant source. For example this section defines a new # source, called `my-vendor-source`, which comes from a directory -# located at `vendor` relative to the directory containing this `.cargo/config` +# located at `vendor` relative to the directory containing this `.cargo/config.toml` # file [source.my-vendor-source] directory = "vendor" diff --git a/src/doc/src/reference/specifying-dependencies.md b/src/doc/src/reference/specifying-dependencies.md index 18d6380c8da..a55467bc29f 100644 --- a/src/doc/src/reference/specifying-dependencies.md +++ b/src/doc/src/reference/specifying-dependencies.md @@ -107,7 +107,7 @@ separated with a comma, e.g., `>= 1.2, < 1.5`. ### Specifying dependencies from other registries To specify a dependency from a registry other than [crates.io], first the -registry must be configured in a `.cargo/config` file. See the [registries +registry must be configured in a `.cargo/config.toml` file. See the [registries documentation] for more information. In the dependency, set the `registry` key to the name of the registry to use. diff --git a/src/doc/src/reference/unstable.md b/src/doc/src/reference/unstable.md index fe00ed57e3e..4866e56992d 100644 --- a/src/doc/src/reference/unstable.md +++ b/src/doc/src/reference/unstable.md @@ -26,7 +26,7 @@ index each time. The `-Z mtime-on-use` flag is an experiment to have Cargo update the mtime of used files to make it easier for tools like cargo-sweep to detect which files are stale. For many workflows this needs to be set on *all* invocations of cargo. -To make this more practical setting the `unstable.mtime_on_use` flag in `.cargo/config` +To make this more practical setting the `unstable.mtime_on_use` flag in `.cargo/config.toml` or the corresponding ENV variable will apply the `-Z mtime-on-use` to all invocations of nightly cargo. (the config flag is ignored by stable) @@ -76,7 +76,7 @@ directory. Example: cargo +nightly build --out-dir=out -Z unstable-options ``` -This can also be specified in `.cargo/config` files. +This can also be specified in `.cargo/config.toml` files. ```toml [build] @@ -93,7 +93,7 @@ from the host cargo will simply skip testing doctests. If this flag is present, cargo will continue as normal, passing the tests to doctest, while also passing it a `--target` option, as well as enabling `-Zunstable-features --enable-per-target-ignores` and passing along -information from `.cargo/config`. See the rustc issue for more information. +information from `.cargo/config.toml`. See the rustc issue for more information. ``` cargo test --target foo -Zdoctest-xcompile diff --git a/src/etc/man/cargo-login.1 b/src/etc/man/cargo-login.1 index f3dee23adff..9b3a9f9adba 100644 --- a/src/etc/man/cargo-login.1 +++ b/src/etc/man/cargo-login.1 @@ -2,12 +2,12 @@ .\" Title: cargo-login .\" Author: [see the "AUTHOR(S)" section] .\" Generator: Asciidoctor 2.0.10 -.\" Date: 2019-06-03 +.\" Date: 2020-04-16 .\" Manual: \ \& .\" Source: \ \& .\" Language: English .\" -.TH "CARGO\-LOGIN" "1" "2019-06-03" "\ \&" "\ \&" +.TH "CARGO\-LOGIN" "1" "2020-04-16" "\ \&" "\ \&" .ie \n(.g .ds Aq \(aq .el .ds Aq ' .ss \n[.ss] 0 @@ -36,7 +36,7 @@ cargo\-login \- Save an API token from the registry locally .sp This command will save the API token to disk so that commands that require authentication, such as \fBcargo\-publish\fP(1), will be automatically -authenticated. The token is saved in \fB$CARGO_HOME/credentials\fP. \fBCARGO_HOME\fP +authenticated. The token is saved in \fB$CARGO_HOME/credentials.toml\fP. \fBCARGO_HOME\fP defaults to \fB.cargo\fP in your home directory. .sp If the \fITOKEN\fP argument is not specified, it will be read from stdin. diff --git a/src/etc/man/cargo-vendor.1 b/src/etc/man/cargo-vendor.1 index a73392091f8..87a9b6df1ab 100644 --- a/src/etc/man/cargo-vendor.1 +++ b/src/etc/man/cargo-vendor.1 @@ -2,12 +2,12 @@ .\" Title: cargo-vendor .\" Author: [see the "AUTHOR(S)" section] .\" Generator: Asciidoctor 2.0.10 -.\" Date: 2020-03-30 +.\" Date: 2020-04-16 .\" Manual: \ \& .\" Source: \ \& .\" Language: English .\" -.TH "CARGO\-VENDOR" "1" "2020-03-30" "\ \&" "\ \&" +.TH "CARGO\-VENDOR" "1" "2020-04-16" "\ \&" "\ \&" .ie \n(.g .ds Aq \(aq .el .ds Aq ' .ss \n[.ss] 0 @@ -41,7 +41,7 @@ dependencies specified. Additional manifests beyond the default one can be specified with the \fB\-s\fP option. .sp The \fBcargo vendor\fP command will also print out the configuration necessary -to use the vendored sources, which you will need to add to \fB.cargo/config\fP. +to use the vendored sources, which you will need to add to \fB.cargo/config.toml\fP. .SH "OPTIONS" .SS "Vendor Options" .sp @@ -59,7 +59,7 @@ existing contents of the vendor directory .sp \fB\-\-respect\-source\-config\fP .RS 4 -Instead of ignoring \fB[source]\fP configuration by default in \fB.cargo/config\fP +Instead of ignoring \fB[source]\fP configuration by default in \fB.cargo/config.toml\fP read it and use it when downloading crates from crates.io, for example .RE .sp diff --git a/src/etc/man/cargo.1 b/src/etc/man/cargo.1 index 854bb641558..7b69056ed0a 100644 --- a/src/etc/man/cargo.1 +++ b/src/etc/man/cargo.1 @@ -2,12 +2,12 @@ .\" Title: cargo .\" Author: [see the "AUTHOR(S)" section] .\" Generator: Asciidoctor 2.0.10 -.\" Date: 2020-03-30 +.\" Date: 2020-04-16 .\" Manual: \ \& .\" Source: \ \& .\" Language: English .\" -.TH "CARGO" "1" "2020-03-30" "\ \&" "\ \&" +.TH "CARGO" "1" "2020-04-16" "\ \&" "\ \&" .ie \n(.g .ds Aq \(aq .el .ds Aq ' .ss \n[.ss] 0 @@ -357,21 +357,21 @@ Binaries installed by \fBcargo\-install\fP(1) will be located here. If using rustup, executables distributed with Rust are also located here. .RE .sp -\fB$CARGO_HOME/config\fP +\fB$CARGO_HOME/config.toml\fP .RS 4 The global configuration file. See \c .URL "https://doc.rust\-lang.org/cargo/reference/config.html" "the reference" for more information about configuration files. .RE .sp -\fB.cargo/config\fP +\fB.cargo/config.toml\fP .RS 4 -Cargo automatically searches for a file named \fB.cargo/config\fP in the +Cargo automatically searches for a file named \fB.cargo/config.toml\fP in the current directory, and all parent directories. These configuration files will be merged with the global configuration file. .RE .sp -\fB$CARGO_HOME/credentials\fP +\fB$CARGO_HOME/credentials.toml\fP .RS 4 Private authentication information for logging in to a registry. .RE