Auto merge of #6654 - ehuss:alt-stabilize, r=alexcrichton

Stabilize Alternative Registries This includes a few minor changes besides stabilizing: - `cargo search` won't display `crates.io` search URL for extra results for non-crates.io registries. - Document using environment variables for API tokens. - Explicit section in `config.md` for documenting the credentials file. Closes rust-lang/rust#44931 Closes rust-lang/crates-io-cargo-teams#21 Closes #6589 Closes #4688
rust-lang · Feb 12, 2019 · 2e4cfc2 · 2e4cfc2
2 parents 8fbabe3 + 902885c
commit 2e4cfc2
Show file tree

Hide file tree

Showing 32 changed files with 878 additions and 394 deletions.
diff --git a/src/cargo/core/features.rs b/src/cargo/core/features.rs
@@ -173,7 +173,7 @@ features! {
         [unstable] test_dummy_unstable: bool,
 
         // Downloading packages from alternative registry indexes.
-        [unstable] alternative_registries: bool,
+        [stable] alternative_registries: bool,
 
         // Using editions
         [stable] edition: bool,

diff --git a/src/cargo/ops/registry.rs b/src/cargo/ops/registry.rs
@@ -717,7 +717,7 @@ pub fn search(
         prefix
     }
 
-    let (mut registry, _) = registry(config, None, index, reg, false)?;
+    let (mut registry, source_id) = registry(config, None, index, reg, false)?;
     let (crates, total_crates) = registry
         .search(query, limit)
         .chain_err(|| "failed to retrieve search results from the registry")?;
@@ -758,11 +758,15 @@ pub fn search(
             total_crates - limit
         );
     } else if total_crates > limit && limit >= search_max_limit {
-        println!(
-            "... and {} crates more (go to http://crates.io/search?q={} to see more)",
-            total_crates - limit,
-            percent_encode(query.as_bytes(), QUERY_ENCODE_SET)
-        );
+        let extra = if source_id.is_default_registry() {
+            format!(
+                " (go to http://crates.io/search?q={} to see more)",
+                percent_encode(query.as_bytes(), QUERY_ENCODE_SET)
+            )
+        } else {
+            String::new()
+        };
+        println!("... and {} crates more{}", total_crates - limit, extra);
     }
 
     Ok(())

diff --git a/src/cargo/util/command_prelude.rs b/src/cargo/util/command_prelude.rs
@@ -174,7 +174,7 @@ pub trait AppExt: Sized {
     }
 
     fn arg_index(self) -> Self {
-        self._arg(opt("index", "Registry index to upload the package to").value_name("INDEX"))
+        self._arg(opt("index", "Registry index URL to upload the package to").value_name("INDEX"))
             ._arg(
                 opt("host", "DEPRECATED, renamed to '--index'")
                     .value_name("HOST")
@@ -387,12 +387,6 @@ pub trait ArgMatchesExt {
     fn registry(&self, config: &Config) -> CargoResult<Option<String>> {
         match self._value_of("registry") {
             Some(registry) => {
-                if !config.cli_unstable().unstable_options {
-                    return Err(failure::format_err!(
-                        "registry option is an unstable feature and \
-                         requires -Zunstable-options to use."
-                    ));
-                }
                 validate_package_name(registry, "registry name", "")?;
 
                 if registry == CRATES_IO_REGISTRY {

diff --git a/src/cargo/util/toml/mod.rs b/src/cargo/util/toml/mod.rs
@@ -995,14 +995,7 @@ impl TomlManifest {
         };
         let profiles = Profiles::new(me.profile.as_ref(), config, &features, &mut warnings)?;
         let publish = match project.publish {
-            Some(VecStringOrBool::VecString(ref vecstring)) => {
-                features
-                    .require(Feature::alternative_registries())
-                    .chain_err(|| {
-                        "the `publish` manifest key is unstable for anything other than a value of true or false"
-                    })?;
-                Some(vecstring.clone())
-            }
+            Some(VecStringOrBool::VecString(ref vecstring)) => Some(vecstring.clone()),
             Some(VecStringOrBool::Bool(false)) => Some(vec![]),
             None | Some(VecStringOrBool::Bool(true)) => None,
         };
@@ -1410,12 +1403,10 @@ impl DetailedTomlDependency {
             .set_optional(self.optional.unwrap_or(false))
             .set_platform(cx.platform.clone());
         if let Some(registry) = &self.registry {
-            cx.features.require(Feature::alternative_registries())?;
             let registry_id = SourceId::alt_registry(cx.config, registry)?;
             dep.set_registry_id(registry_id);
         }
         if let Some(registry_index) = &self.registry_index {
-            cx.features.require(Feature::alternative_registries())?;
             let url = registry_index.to_url()?;
             let registry_id = SourceId::for_registry(&url)?;
             dep.set_registry_id(registry_id);

diff --git a/src/doc/man/generated/cargo-init.html b/src/doc/man/generated/cargo-init.html
@@ -128,11 +128,14 @@ <h3 id="cargo_init_init_options">Init Options</h3>
 </dd>
 <dt class="hdlist1"><strong>--registry</strong> <em>REGISTRY</em></dt>
 <dd>
-<p>Alternative registry to use. This sets the <code>publish</code> field which will
-restrict publishing only to the given registry name.</p>
+<p>This sets the <code>publish</code> field in <code>Cargo.toml</code> to the given registry name
+which will restrict publishing only to that registry.</p>
 <div class="paragraph">
-<p>This option is unstable and available only on the nightly channel and requires
-the <code>-Z unstable-options</code> flag to enable.</p>
+<p>Registry names are defined in <a href="reference/config.html">Cargo config files</a>.
+If not specified, the default registry defined by the <code>registry.default</code>
+config key is used. If the default registry is not set and <code>--registry</code> is not
+used, the <code>publish</code> field will not be set which means that publishing will not
+be restricted.</p>
 </div>
 </dd>
 </dl>

diff --git a/src/doc/man/generated/cargo-install.html b/src/doc/man/generated/cargo-install.html
@@ -131,11 +131,9 @@ <h3 id="cargo_install_install_options">Install Options</h3>
 </dd>
 <dt class="hdlist1"><strong>--registry</strong> <em>REGISTRY</em></dt>
 <dd>
-<p>Alternative registry to use.</p>
-<div class="paragraph">
-<p>This option is unstable and available only on the nightly channel and requires
-the <code>-Z unstable-options</code> flag to enable.</p>
-</div>
+<p>Name of the registry to use. Registry names are defined in <a href="reference/config.html">Cargo config files</a>.
+If not specified, the default registry is used, which is defined by the
+<code>registry.default</code> config key which defaults to <code>crates-io</code>.</p>
 </dd>
 </dl>
 </div>

diff --git a/src/doc/man/generated/cargo-login.html b/src/doc/man/generated/cargo-login.html
@@ -39,11 +39,9 @@ <h3 id="cargo_login_login_options">Login Options</h3>
 <dl>
 <dt class="hdlist1"><strong>--registry</strong> <em>REGISTRY</em></dt>
 <dd>
-<p>Alternative registry to use.</p>
-<div class="paragraph">
-<p>This option is unstable and available only on the nightly channel and requires
-the <code>-Z unstable-options</code> flag to enable.</p>
-</div>
+<p>Name of the registry to use. Registry names are defined in <a href="reference/config.html">Cargo config files</a>.
+If not specified, the default registry is used, which is defined by the
+<code>registry.default</code> config key which defaults to <code>crates-io</code>.</p>
 </dd>
 </dl>
 </div>

diff --git a/src/doc/man/generated/cargo-new.html b/src/doc/man/generated/cargo-new.html
@@ -121,11 +121,14 @@ <h3 id="cargo_new_new_options">New Options</h3>
 </dd>
 <dt class="hdlist1"><strong>--registry</strong> <em>REGISTRY</em></dt>
 <dd>
-<p>Alternative registry to use. This sets the <code>publish</code> field which will
-restrict publishing only to the given registry name.</p>
+<p>This sets the <code>publish</code> field in <code>Cargo.toml</code> to the given registry name
+which will restrict publishing only to that registry.</p>
 <div class="paragraph">
-<p>This option is unstable and available only on the nightly channel and requires
-the <code>-Z unstable-options</code> flag to enable.</p>
+<p>Registry names are defined in <a href="reference/config.html">Cargo config files</a>.
+If not specified, the default registry defined by the <code>registry.default</code>
+config key is used. If the default registry is not set and <code>--registry</code> is not
+used, the <code>publish</code> field will not be set which means that publishing will not
+be restricted.</p>
 </div>
 </dd>
 </dl>

diff --git a/src/doc/man/generated/cargo-owner.html b/src/doc/man/generated/cargo-owner.html
@@ -58,19 +58,26 @@ <h3 id="cargo_owner_owner_options">Owner Options</h3>
 </dd>
 <dt class="hdlist1"><strong>--token</strong> <em>TOKEN</em></dt>
 <dd>
-<p>API token to use when authenticating.</p>
+<p>API token to use when authenticating. This overrides the token stored in
+the credentials file (which is created by <a href="commands/cargo-login.html">cargo-login(1)</a>).</p>
+<div class="paragraph">
+<p><a href="reference/config.html">Cargo config</a> environment variables can be
+used to override the tokens stored in the credentials file. The token for
+crates.io may be specified with the <code>CARGO_REGISTRY_TOKEN</code> environment
+variable. Tokens for other registries may be specified with environment
+variables of the form <code>CARGO_REGISTRIES_NAME_TOKEN</code> where <code>NAME</code> is the name
+of the registry in all capital letters.</p>
+</div>
 </dd>
 <dt class="hdlist1"><strong>--index</strong> <em>INDEX</em></dt>
 <dd>
 <p>The URL of the registry index to use.</p>
 </dd>
 <dt class="hdlist1"><strong>--registry</strong> <em>REGISTRY</em></dt>
 <dd>
-<p>Alternative registry to use.</p>
-<div class="paragraph">
-<p>This option is unstable and available only on the nightly channel and requires
-the <code>-Z unstable-options</code> flag to enable.</p>
-</div>
+<p>Name of the registry to use. Registry names are defined in <a href="reference/config.html">Cargo config files</a>.
+If not specified, the default registry is used, which is defined by the
+<code>registry.default</code> config key which defaults to <code>crates-io</code>.</p>
 </dd>
 </dl>
 </div>

diff --git a/src/doc/man/generated/cargo-publish.html b/src/doc/man/generated/cargo-publish.html
@@ -67,7 +67,16 @@ <h3 id="cargo_publish_publish_options">Publish Options</h3>
 </dd>
 <dt class="hdlist1"><strong>--token</strong> <em>TOKEN</em></dt>
 <dd>
-<p>API token to use when authenticating.</p>
+<p>API token to use when authenticating. This overrides the token stored in
+the credentials file (which is created by <a href="commands/cargo-login.html">cargo-login(1)</a>).</p>
+<div class="paragraph">
+<p><a href="reference/config.html">Cargo config</a> environment variables can be
+used to override the tokens stored in the credentials file. The token for
+crates.io may be specified with the <code>CARGO_REGISTRY_TOKEN</code> environment
+variable. Tokens for other registries may be specified with environment
+variables of the form <code>CARGO_REGISTRIES_NAME_TOKEN</code> where <code>NAME</code> is the name
+of the registry in all capital letters.</p>
+</div>
 </dd>
 <dt class="hdlist1"><strong>--no-verify</strong></dt>
 <dd>
@@ -83,11 +92,9 @@ <h3 id="cargo_publish_publish_options">Publish Options</h3>
 </dd>
 <dt class="hdlist1"><strong>--registry</strong> <em>REGISTRY</em></dt>
 <dd>
-<p>Alternative registry to use.</p>
-<div class="paragraph">
-<p>This option is unstable and available only on the nightly channel and requires
-the <code>-Z unstable-options</code> flag to enable.</p>
-</div>
+<p>Name of the registry to use. Registry names are defined in <a href="reference/config.html">Cargo config files</a>.
+If not specified, the default registry is used, which is defined by the
+<code>registry.default</code> config key which defaults to <code>crates-io</code>.</p>
 </dd>
 </dl>
 </div>

diff --git a/src/doc/man/generated/cargo-search.html b/src/doc/man/generated/cargo-search.html
@@ -37,11 +37,9 @@ <h3 id="cargo_search_search_options">Search Options</h3>
 </dd>
 <dt class="hdlist1"><strong>--registry</strong> <em>REGISTRY</em></dt>
 <dd>
-<p>Alternative registry to use.</p>
-<div class="paragraph">
-<p>This option is unstable and available only on the nightly channel and requires
-the <code>-Z unstable-options</code> flag to enable.</p>
-</div>
+<p>Name of the registry to use. Registry names are defined in <a href="reference/config.html">Cargo config files</a>.
+If not specified, the default registry is used, which is defined by the
+<code>registry.default</code> config key which defaults to <code>crates-io</code>.</p>
 </dd>
 </dl>
 </div>

diff --git a/src/doc/man/generated/cargo-yank.html b/src/doc/man/generated/cargo-yank.html
@@ -50,19 +50,26 @@ <h3 id="cargo_yank_owner_options">Owner Options</h3>
 </dd>
 <dt class="hdlist1"><strong>--token</strong> <em>TOKEN</em></dt>
 <dd>
-<p>API token to use when authenticating.</p>
+<p>API token to use when authenticating. This overrides the token stored in
+the credentials file (which is created by <a href="commands/cargo-login.html">cargo-login(1)</a>).</p>
+<div class="paragraph">
+<p><a href="reference/config.html">Cargo config</a> environment variables can be
+used to override the tokens stored in the credentials file. The token for
+crates.io may be specified with the <code>CARGO_REGISTRY_TOKEN</code> environment
+variable. Tokens for other registries may be specified with environment
+variables of the form <code>CARGO_REGISTRIES_NAME_TOKEN</code> where <code>NAME</code> is the name
+of the registry in all capital letters.</p>
+</div>
 </dd>
 <dt class="hdlist1"><strong>--index</strong> <em>INDEX</em></dt>
 <dd>
 <p>The URL of the registry index to use.</p>
 </dd>
 <dt class="hdlist1"><strong>--registry</strong> <em>REGISTRY</em></dt>
 <dd>
-<p>Alternative registry to use.</p>
-<div class="paragraph">
-<p>This option is unstable and available only on the nightly channel and requires
-the <code>-Z unstable-options</code> flag to enable.</p>
-</div>
+<p>Name of the registry to use. Registry names are defined in <a href="reference/config.html">Cargo config files</a>.
+If not specified, the default registry is used, which is defined by the
+<code>registry.default</code> config key which defaults to <code>crates-io</code>.</p>
 </dd>
 </dl>
 </div>

diff --git a/src/doc/man/options-new.adoc b/src/doc/man/options-new.adoc
@@ -19,8 +19,11 @@
     `cargo-new.vcs`, or `none` if already inside a VCS repository.
 
 *--registry* _REGISTRY_::
-    Alternative registry to use. This sets the `publish` field which will
-    restrict publishing only to the given registry name.
+    This sets the `publish` field in `Cargo.toml` to the given registry name
+    which will restrict publishing only to that registry.
 +
-This option is unstable and available only on the nightly channel and requires
-the `-Z unstable-options` flag to enable.
+Registry names are defined in linkcargo:reference/config.html[Cargo config files].
+If not specified, the default registry defined by the `registry.default`
+config key is used. If the default registry is not set and `--registry` is not
+used, the `publish` field will not be set which means that publishing will not
+be restricted.
diff --git a/src/doc/man/options-registry.adoc b/src/doc/man/options-registry.adoc
@@ -1,5 +1,4 @@
 *--registry* _REGISTRY_::
-    Alternative registry to use.
-+
-This option is unstable and available only on the nightly channel and requires
-the `-Z unstable-options` flag to enable.
+    Name of the registry to use. Registry names are defined in linkcargo:reference/config.html[Cargo config files].
+    If not specified, the default registry is used, which is defined by the
+    `registry.default` config key which defaults to `crates-io`.
diff --git a/src/doc/man/options-token.adoc b/src/doc/man/options-token.adoc
@@ -1,2 +1,10 @@
 *--token* _TOKEN_::
-    API token to use when authenticating.
+    API token to use when authenticating. This overrides the token stored in
+    the credentials file (which is created by man:cargo-login[1]).
++
+linkcargo:reference/config.html[Cargo config] environment variables can be
+used to override the tokens stored in the credentials file. The token for
+crates.io may be specified with the `CARGO_REGISTRY_TOKEN` environment
+variable. Tokens for other registries may be specified with environment
+variables of the form `CARGO_REGISTRIES_NAME_TOKEN` where `NAME` is the name
+of the registry in all capital letters.
diff --git a/src/doc/src/SUMMARY.md b/src/doc/src/SUMMARY.md
@@ -27,6 +27,7 @@
     * [Package ID Specifications](reference/pkgid-spec.md)
     * [Source Replacement](reference/source-replacement.md)
     * [External Tools](reference/external-tools.md)
+    * [Registries](reference/registries.md)
     * [Unstable Features](reference/unstable.md)
 
 * [Cargo Commands](commands/index.md)

diff --git a/src/doc/src/reference/config.md b/src/doc/src/reference/config.md
@@ -6,7 +6,6 @@ manifest, see the [manifest format](reference/manifest.html).
 
 ### Hierarchical structure
 
-
 Cargo allows local configuration for a particular package as well as global
 configuration, like git. Cargo extends this to a hierarchical strategy.
 If, for example, Cargo were invoked in `/projects/foo/bar/baz`, then the
@@ -17,7 +16,7 @@ following configuration files would be probed for and unified in this order:
 * `/projects/foo/.cargo/config`
 * `/projects/.cargo/config`
 * `/.cargo/config`
-* `$HOME/.cargo/config`
+* `$CARGO_HOME/config` (`$CARGO_HOME` defaults to `$HOME/.cargo`)
 
 With this structure, you can specify configuration per-package, and even
 possibly check it into version control. You can also specify personal defaults
@@ -91,9 +90,16 @@ runner = ".."
 
 # Configuration keys related to the registry
 [registry]
-index = "..."   # URL of the registry index (defaults to the central repository)
-token = "..."   # Access token (found on the central repo’s website)
-default = "..." # Default alternative registry to use (can be overriden with --registry)
+index = "..."   # URL of the registry index (defaults to the index of crates.io)
+default = "..." # Name of the default registry to use (can be overridden with
+                # --registry)
+
+# Configuration keys for registries other than crates.io.
+# `$name` should be the name of the registry, which will be used for
+# dependencies in `Cargo.toml` files and the `--registry` command-line flag.
+# Registry names should only contain alphanumeric characters, `-`, or `_`.
+[registries.$name]
+index = "..."   # URL of the registry index
 
 [http]
 proxy = "host:port" # HTTP proxy to use for HTTP requests (defaults to none)
@@ -160,5 +166,34 @@ tables, cannot be configured through environment variables.
 In addition to the system above, Cargo recognizes a few other specific
 [environment variables][env].
 
+### Credentials
+
+Configuration values with sensitive information are stored in the
+`$CARGO_HOME/credentials` file. This file is automatically created and updated
+by [`cargo login`]. It follows the same format as Cargo config files.
+
+```toml
+[registry]
+token = "..."   # Access token for crates.io
+
+# `$name` should be a registry name (see above for more information about
+# configuring registries).
+[registries.$name]
+token = "..."   # Access token for the named registry
+```
+
+Tokens are used by some Cargo commands such as [`cargo publish`] for
+authenticating with remote registries. Care should be taken to protect the
+tokens and to keep them secret.
+
+As with most other config values, tokens may be specified with environment
+variables. The token for crates.io may be specified with the
+`CARGO_REGISTRY_TOKEN` environment variable. Tokens for other registries may
+be specified with environment variables of the form
+`CARGO_REGISTRIES_NAME_TOKEN` where `NAME` is the name of the registry in all
+capital letters.
+
+[`cargo login`]: commands/cargo-login.html
+[`cargo publish`]: commands/cargo-publish.html
 [env]: reference/environment-variables.html
 [source]: reference/source-replacement.html