Skip to content

Commit

Permalink
Auto merge of #6654 - ehuss:alt-stabilize, r=alexcrichton
Browse files Browse the repository at this point in the history
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
  • Loading branch information
bors committed Feb 12, 2019
2 parents 8fbabe3 + 902885c commit 2e4cfc2
Show file tree
Hide file tree
Showing 32 changed files with 878 additions and 394 deletions.
2 changes: 1 addition & 1 deletion src/cargo/core/features.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Expand Down
16 changes: 10 additions & 6 deletions src/cargo/ops/registry.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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")?;
Expand Down Expand Up @@ -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(())
Expand Down
8 changes: 1 addition & 7 deletions src/cargo/util/command_prelude.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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")
Expand Down Expand Up @@ -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 {
Expand Down
11 changes: 1 addition & 10 deletions src/cargo/util/toml/mod.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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,
};
Expand Down Expand Up @@ -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);
Expand Down
11 changes: 7 additions & 4 deletions src/doc/man/generated/cargo-init.html
Original file line number Diff line number Diff line change
Expand Up @@ -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>
Expand Down
8 changes: 3 additions & 5 deletions src/doc/man/generated/cargo-install.html
Original file line number Diff line number Diff line change
Expand Up @@ -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>
Expand Down
8 changes: 3 additions & 5 deletions src/doc/man/generated/cargo-login.html
Original file line number Diff line number Diff line change
Expand Up @@ -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>
Expand Down
11 changes: 7 additions & 4 deletions src/doc/man/generated/cargo-new.html
Original file line number Diff line number Diff line change
Expand Up @@ -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>
Expand Down
19 changes: 13 additions & 6 deletions src/doc/man/generated/cargo-owner.html
Original file line number Diff line number Diff line change
Expand Up @@ -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>
Expand Down
19 changes: 13 additions & 6 deletions src/doc/man/generated/cargo-publish.html
Original file line number Diff line number Diff line change
Expand Up @@ -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>
Expand All @@ -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>
Expand Down
8 changes: 3 additions & 5 deletions src/doc/man/generated/cargo-search.html
Original file line number Diff line number Diff line change
Expand Up @@ -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>
Expand Down
19 changes: 13 additions & 6 deletions src/doc/man/generated/cargo-yank.html
Original file line number Diff line number Diff line change
Expand Up @@ -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>
Expand Down
11 changes: 7 additions & 4 deletions src/doc/man/options-new.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -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.
7 changes: 3 additions & 4 deletions src/doc/man/options-registry.adoc
Original file line number Diff line number Diff line change
@@ -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`.
10 changes: 9 additions & 1 deletion src/doc/man/options-token.adoc
Original file line number Diff line number Diff line change
@@ -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.
1 change: 1 addition & 0 deletions src/doc/src/SUMMARY.md
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down
45 changes: 40 additions & 5 deletions src/doc/src/reference/config.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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
Expand Down Expand Up @@ -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)
Expand Down Expand Up @@ -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
Loading

0 comments on commit 2e4cfc2

Please sign in to comment.