diff --git a/src/cargo/core/features.rs b/src/cargo/core/features.rs index 6a90413391f..d19a8e55c2b 100644 --- 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 index 557a84039d8..63f31be0b61 100644 --- 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 index 1ad216142a9..a8ddfdb94dd 100644 --- 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> { 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 index a57a09dfa61..d3e6fd9aa95 100644 --- 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 index b4b893eba23..979b330a4d4 100644 --- a/src/doc/man/generated/cargo-init.html +++ b/src/doc/man/generated/cargo-init.html @@ -128,11 +128,14 @@

Init Options

--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 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/generated/cargo-install.html b/src/doc/man/generated/cargo-install.html index 5cbd1f384e1..bd5d6fb24ed 100644 --- a/src/doc/man/generated/cargo-install.html +++ b/src/doc/man/generated/cargo-install.html @@ -131,11 +131,9 @@

Install Options

--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 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/generated/cargo-login.html b/src/doc/man/generated/cargo-login.html index 9c2b518328c..b44377b34a4 100644 --- a/src/doc/man/generated/cargo-login.html +++ b/src/doc/man/generated/cargo-login.html @@ -39,11 +39,9 @@

Login Options

--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 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/generated/cargo-new.html b/src/doc/man/generated/cargo-new.html index 33bfef758a8..adf6c46d7a8 100644 --- a/src/doc/man/generated/cargo-new.html +++ b/src/doc/man/generated/cargo-new.html @@ -121,11 +121,14 @@

New Options

--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 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/generated/cargo-owner.html b/src/doc/man/generated/cargo-owner.html index 41624a0f588..21eab2e8d5a 100644 --- a/src/doc/man/generated/cargo-owner.html +++ b/src/doc/man/generated/cargo-owner.html @@ -58,7 +58,16 @@

Owner Options

--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 cargo-login(1)).

+
+

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.

+
--index INDEX
@@ -66,11 +75,9 @@

Owner Options

--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 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/generated/cargo-publish.html b/src/doc/man/generated/cargo-publish.html index c233c0e4ed8..8e631b2489e 100644 --- a/src/doc/man/generated/cargo-publish.html +++ b/src/doc/man/generated/cargo-publish.html @@ -67,7 +67,16 @@

Publish Options

--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 cargo-login(1)).

+
+

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.

+
--no-verify
@@ -83,11 +92,9 @@

Publish Options

--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 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/generated/cargo-search.html b/src/doc/man/generated/cargo-search.html index b21dd04106c..a2121216f2b 100644 --- a/src/doc/man/generated/cargo-search.html +++ b/src/doc/man/generated/cargo-search.html @@ -37,11 +37,9 @@

Search Options

--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 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/generated/cargo-yank.html b/src/doc/man/generated/cargo-yank.html index 4de0f1486e7..4e1d00965e8 100644 --- a/src/doc/man/generated/cargo-yank.html +++ b/src/doc/man/generated/cargo-yank.html @@ -50,7 +50,16 @@

Owner Options

--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 cargo-login(1)).

+
+

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.

+
--index INDEX
@@ -58,11 +67,9 @@

Owner Options

--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 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-new.adoc b/src/doc/man/options-new.adoc index 6ede49e0208..2218599ae2a 100644 --- 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 index 79a035ea94f..a0c4c27c8e8 100644 --- 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 index c303aa77656..5f25ffbf243 100644 --- 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 index 5b5293be877..3a69c0a312d 100644 --- 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 index da6b3c5d649..ee3f8426432 100644 --- 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 diff --git a/src/doc/src/reference/manifest.md b/src/doc/src/reference/manifest.md index 3788037a6de..069fa23e951 100644 --- a/src/doc/src/reference/manifest.md +++ b/src/doc/src/reference/manifest.md @@ -175,6 +175,15 @@ private in a company. publish = false ``` +The value many also be an array of strings which are registry names that are +allowed to be published to. + +```toml +[package] +# ... +publish = ["some-registry-name"] +``` + #### The `workspace` field (optional) The `workspace` field can be used to configure the workspace that this package @@ -832,11 +841,10 @@ baz = { git = 'https://github.com/example/patched-baz', branch = 'my-branch' } ``` The `[patch]` table is made of dependency-like sub-tables. Each key after -`[patch]` is a URL of the source that's being patched, or `crates-io` if -you're modifying the https://crates.io registry. In the example above -`crates-io` could be replaced with a git URL such as -`https://github.com/rust-lang-nursery/log`; the second `[patch]` -section in the example uses this to specify a source called `baz`. +`[patch]` is a URL of the source that is being patched, or the name of a +registry. The name `crates-io` may be used to override the default registry +[crates.io]. The first `[patch]` in the example above demonstrates overriding +[crates.io], and the second `[patch]` demonstrates overriding a git source. Each entry in these tables is a normal dependency specification, the same as found in the `[dependencies]` section of the manifest. The dependencies listed @@ -856,6 +864,7 @@ dependencies][replace] section of the documentation and [RFC 1969] for the technical specification of this feature. [RFC 1969]: https://github.com/rust-lang/rfcs/pull/1969 +[crates.io]: https://crates.io/ [replace]: reference/specifying-dependencies.html#overriding-dependencies ### The `[replace]` Section diff --git a/src/doc/src/reference/registries.md b/src/doc/src/reference/registries.md new file mode 100644 index 00000000000..cc5b040fc4d --- /dev/null +++ b/src/doc/src/reference/registries.md @@ -0,0 +1,590 @@ +## Registries + +Cargo installs crates and fetches dependencies from a "registry". The default +registry is [crates.io]. A registry contains an "index" which contains a +searchable list of available crates. A registry may also provide a web API to +support publishing new crates directly from Cargo. + +> Note: If you are interested in mirroring or vendoring an existing registry, +> take a look at [Source Replacement]. + +### 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` +table has a key for each registry, for example: + +```toml +[registries] +my-registry = { index = "https://my-intranet:8080/git/index" } +``` + +The `index` key should be a URL to a git repository with the registry's index. +A crate can then depend on a crate from another registry by specifying the +`registry` key and a value of the registry's name in that dependency's entry +in `Cargo.toml`: + +```toml +# Sample Cargo.toml +[package] +name = "my-project" +version = "0.1.0" + +[dependencies] +other-crate = { version = "1.0", registry = "my-registry" } +``` + +As with most config values, the index may be specified with an environment +variable instead of a config file. For example, setting the following +environment variable will accomplish the same thing as defining a config file: + +``` +CARGO_REGISTRIES_MY_REGISTRY_INDEX=https://my-intranet:8080/git/index +``` + +> Note: [crates.io] does not accept packages that depend on crates from other +> registries. + +### Publishing to an Alternate Registry + +If the registry supports web API access, then packages can be published +directly to the registry from Cargo. Several of Cargo's commands such as +[`cargo publish`] take a `--registry` command-line flag to indicate which +registry to use. For example, to publish the package in the current directory: + +1. `cargo login --registry=my-registry` + + This only needs to be done once. You must enter the secret API token + retrieved from the registry's website. Alternatively the token may be + passed directly to the `publish` command with the `--token` command-line + flag or an environment variable with the name of the registry such as + `CARGO_REGISTRIES_MY_REGISTRY_TOKEN`. + +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` +key. + +Setting the `package.publish` key in the `Cargo.toml` manifest restricts which +registries the package is allowed to be published to. This is useful to +prevent accidentally publishing a closed-source package to [crates.io]. The +value may be a list of registry names, for example: + +```toml +[package] +# ... +publish = ["my-registry"] +``` + +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 +has a separate table for each registry, for example: + +```toml +[registries.my-registry] +token = "854DvwSlUwEHtIo3kWy6x7UCPKHfzCmy" +``` + +### Running a Registry + +A minimal registry can be implemented by having a git repository that contains +an index, and a server that contains the compressed `.crate` files created by +[`cargo package`]. Users won't be able to use Cargo to publish to it, but this +may be sufficient for closed environments. + +A full-featured registry that supports publishing will additionally need to +have a web API service that conforms to the API used by Cargo. The web API is +documented below. + +At this time, there is no widely used software for running a custom registry. +There is interest in documenting projects that implement registry support, or +existing package caches that add support for Cargo. + +### Index Format + +The following defines the format of the index. New features are occasionally +added, which are only understood starting with the version of Cargo that +introduced them. Older versions of Cargo may not be able to use packages that +make use of new features. However, the format for older packages should not +change, so older versions of Cargo should be able to use them. + +The index is stored in a git repository so that Cargo can efficiently fetch +incremental updates to the index. In the root of the repository is a file +named `config.json` which contains JSON information used by Cargo for +accessing the registry. This is an example of what the [crates.io] config file +looks like: + +```javascript +{ + "dl": "https://crates.io/api/v1/crates", + "api": "https://crates.io" +} +``` + +The keys are: +- `dl`: This is the URL for downloading crates listed in the index. The value + may have the markers `{crate}` and `{version}` which are replaced with the + name and version of the crate to download. If the markers are not present, + then the value `/{crate}/{version}/download` is appended to the end. +- `api`: This is the base URL for the web API. This key is optional, and if it + is not specified, commands such as [`cargo publish`] will not work. The web + API is described below. + +The download endpoint should send the `.crate` file for the requested package. +Cargo supports https, http, and file URLs, HTTP redirects, HTTP1 and HTTP2. +The exact specifics of TLS support depend on the platform that Cargo is +running on, the version of Cargo, and how it was compiled. + +The rest of the index repository contains one file for each package, where the +filename is the name of the package in lowercase. Each version of the package +has a separate line in the file. The files are organized in a tier of +directories: + +- Packages with 1 character names are placed in a directory named `1`. +- Packages with 2 character names are placed in a directory named `2`. +- Packages with 3 character names are placed in the directory + `3/{first-character}` where `{first-character}` is the first character of + the package name. +- All other packages are stored in directories named + `{first-two}/{second-two}` where the top directory is the first two + characters of the package name, and the next subdirectory is the third and + fourth characters of the package name. For example, `cargo` would be stored + in a file named `ca/rg/cargo`. + +> Note: Although the index filenames are in lowercase, the fields that contain +> package names in `Cargo.toml` and the index JSON data are case-sensitive and +> may contain upper and lower case characters. + +Registries may want to consider enforcing limitations on package names added +to their index. Cargo itself allows names with any [alphanumeric], `-`, or `_` +character. For example, [crates.io] imposes relatively strict limitations, +such as requiring it to be a valid Rust identifier, only allowing ASCII +characters, under a specific length, and rejects reserved names such as +Windows special filenames like "nul". + +Each line in a package file contains a JSON object that describes a published +version of the package. The following is a pretty-printed example with comments +explaining the format of the entry. + +```javascript +{ + // The name of the package. + // This must only contain alphanumeric, `-`, or `_` characters. + "name": "foo", + // The version of the package this row is describing. + // This must be a valid version number according to the Semantic + // Versioning 2.0.0 spec at https://semver.org/. + "vers": "0.1.0", + // Array of direct dependencies of the package. + "deps": [ + { + // Name of the dependency. + // If the dependency is renamed from the original package name, + // this is the new name. The original package name is stored in + // the `package` field. + "name": "rand", + // The semver requirement for this dependency. + // This must be a valid version requirement defined at + // https://github.com/steveklabnik/semver#requirements. + "req": "^0.6", + // Array of features (as strings) enabled for this dependency. + "features": ["i128_support"], + // Boolean of whether or not this is an optional dependency. + "optional": false, + // Boolean of whether or not default features are enabled. + "default_features": true, + // The target platform for the dependency. + // null if not a target dependency. + // Otherwise, a string such as "cfg(windows)". + "target": null, + // The dependency kind. + // "dev", "build", or "normal". + // Note: this is a required field, but a small number of entries + // exist in the crates.io index with either a missing or null + // `kind` field due to implementation bugs. + "kind": "normal", + // The URL of the index of the registry where this dependency is + // from as a string. If not specified or null, it is assumed the + // dependency is in the current registry. + "registry": null, + // If the dependency is renamed, this is a string of the actual + // package name. If not specified or null, this dependency is not + // renamed. + "package": null, + } + ], + // A SHA256 checksum of the `.crate` file. + "cksum": "d867001db0e2b6e0496f9fac96930e2d42233ecd3ca0413e0753d4c7695d289c", + // Set of features defined for the package. + // Each feature maps to an array of features or dependencies it enables. + "features": { + "extras": ["rand/simd_support"] + }, + // Boolean of whether or not this version has been yanked. + "yanked": false, + // The `links` string value from the package's manifest, or null if not + // specified. This field is optional and defaults to null. + "links": null +} +``` + +The JSON objects should not be modified after they are added except for the +`yanked` field whose value may change at any time. + +### Web API + +A registry may host a web API at the location defined in `config.json` to +support any of the actions listed below. + +Cargo includes the `Authorization` header for requests that require +authentication. The header value is the API token. The server should respond +with a 403 response code if the token is not valid. Users are expected to +visit the registry's website to obtain a token, and Cargo can store the token +using the [`cargo login`] command, or by passing the token on the +command-line. + +Responses use a 200 response code for both success and errors. Cargo looks at +the JSON response to determine if there was success or failure. Failure +responses have a JSON object with the following structure: + +```javascript +{ + // Array of errors to display to the user. + "errors": [ + { + // The error message as a string. + "detail": "error message text" + } + ] +} +``` + +Servers may also respond with a 404 response code to indicate the requested +resource is not found (for example, an unknown crate name). However, using a +200 response with an `errors` object allows a registry to provide a more +detailed error message if desired. + +For backwards compatibility, servers should ignore any unexpected query +parameters or JSON fields. If a JSON field is missing, it should be assumed to +be null. The endpoints are versioned with the `v1` component of the path, and +Cargo is responsible for handling backwards compatibility fallbacks should any +be required in the future. + +Cargo sets the following headers for all requests: + +- `Content-Type`: `application/json` +- `Accept`: `application/json` +- `User-Agent`: The Cargo version such as `cargo 1.32.0 (8610973aa + 2019-01-02)`. This may be modified by the user in a configuration value. + Added in 1.29. + +#### Publish + +- Endpoint: `/api/v1/crates/new` +- Method: PUT +- Authorization: Included + +The publish endpoint is used to publish a new version of a crate. The server +should validate the crate, make it available for download, and add it to the +index. + +The body of the data sent by Cargo is: + +- 32-bit unsigned little-endian integer of the length of JSON data. +- Metadata of the package as a JSON object. +- 32-bit unsigned little-endian integer of the length of the `.crate` file. +- The `.crate` file. + +The following is a commented example of the JSON object. Some notes of some +restrictions imposed by [crates.io] are included only to illustrate some +suggestions on types of validation that may be done, and should not be +considered as an exhaustive list of restrictions [crates.io] imposes. + +```javascript +{ + // The name of the package. + "name": "foo", + // The version of the package being published. + "vers": "0.1.0", + // Array of direct dependencies of the package. + "deps": [ + { + // Name of the dependency. + // If the dependency is renamed from the original package name, + // this is the original name. The new package name is stored in + // the `explicit_name_in_toml` field. + "name": "rand", + // The semver requirement for this dependency. + "version_req": "^0.6", + // Array of features (as strings) enabled for this dependency. + "features": ["i128_support"], + // Boolean of whether or not this is an optional dependency. + "optional": false, + // Boolean of whether or not default features are enabled. + "default_features": true, + // The target platform for the dependency. + // null if not a target dependency. + // Otherwise, a string such as "cfg(windows)". + "target": null, + // The dependency kind. + // "dev", "build", or "normal". + "kind": "normal", + // The URL of the index of the registry where this dependency is + // from as a string. If not specified or null, it is assumed the + // dependency is in the current registry. + "registry": null, + // If the dependency is renamed, this is a string of the new + // package name. If not specified or null, this dependency is not + // renamed. + "explicit_name_in_toml": null, + } + ], + // Set of features defined for the package. + // Each feature maps to an array of features or dependencies it enables. + // Cargo does not impose limitations on feature names, but crates.io + // requires alphanumeric ASCII, `_` or `-` characters. + "features": { + "extras": ["rand/simd_support"] + }, + // List of strings of the authors. + // May be empty. crates.io requires at least one entry. + "authors": ["Alice "], + // Description field from the manifest. + // May be null. crates.io requires at least some content. + "description": null, + // String of the URL to the website for this package's documentation. + // May be null. + "documentation": null, + // String of the URL to the website for this package's home page. + // May be null. + "homepage": null, + // String of the content of the README file. + // May be null. + "readme": null, + // String of a relative path to a README file in the crate. + // May be null. + "readme_file": null, + // Array of strings of keywords for the package. + "keywords": [], + // Array of strings of categories for the package. + "categories": [], + // String of the license for the package. + // May be null. crates.io requires either `license` or `license_file` to be set. + "license": null, + // String of a relative path to a license file in the crate. + // May be null. + "license_file": null, + // String of the URL to the website for the source repository of this package. + // May be null. + "repository": null, + // Optional object of "status" badges. Each value is an object of + // arbitrary string to string mappings. + // crates.io has special interpretation of the format of the badges. + "badges": { + "travis-ci": { + "branch": "master", + "repository": "rust-lang/cargo" + } + }, + // The `links` string value from the package's manifest, or null if not + // specified. This field is optional and defaults to null. + "links": null, +} +``` + +A successful response includes the JSON object: + +```javascript +{ + // Optional object of warnings to display to the user. + "warnings": { + // Array of strings of categories that are invalid and ignored. + "invalid_categories": [], + // Array of strings of badge names that are invalid and ignored. + "invalid_badges": [], + // Array of strings of arbitrary warnings to display to the user. + "other": [] + } +} +``` + +#### Yank + +- Endpoint: `/api/v1/crates/{crate_name}/{version}/yank` +- Method: DELETE +- Authorization: Included + +The yank endpoint will set the `yank` field of the given version of a crate to +`true` in the index. + +A successful response includes the JSON object: + +```javascript +{ + // Indicates the delete succeeded, always true. + "ok": true, +} +``` + +#### Unyank + +- Endpoint: `/api/v1/crates/{crate_name}/{version}/unyank` +- Method: PUT +- Authorization: Included + +The unyank endpoint will set the `yank` field of the given version of a crate +to `false` in the index. + +A successful response includes the JSON object: + +```javascript +{ + // Indicates the delete succeeded, always true. + "ok": true, +} +``` + +#### Owners + +Cargo does not have an inherent notion of users and owners, but it does +provide the `owner` command to assist managing who has authorization to +control a crate. It is up to the registry to decide exactly how users and +owners are handled. See the [publishing documentation] for a description of +how [crates.io] handles owners via GitHub users and teams. + +##### Owners: List + +- Endpoint: `/api/v1/crates/{crate_name}/owners` +- Method: GET +- Authorization: Included + +The owners endpoint returns a list of owners of the crate. + +A successful response includes the JSON object: + +```javascript +{ + // Array of owners of the crate. + "users": [ + { + // Unique unsigned 32-bit integer of the owner. + "id": 70, + // The unique username of the owner. + "login": "github:rust-lang:core", + // Name of the owner. + // This is optional and may be null. + "name": "Core", + } + ] +} +``` + +##### Owners: Add + +- Endpoint: `/api/v1/crates/{crate_name}/owners` +- Method: PUT +- Authorization: Included + +A PUT request will send a request to the registry to add a new owner to a +crate. It is up to the registry how to handle the request. For example, +[crates.io] sends an invite to the user that they must accept before being +added. + +The request should include the following JSON object: + +```javascript +{ + // Array of `login` strings of owners to add. + "users": ["login_name"] +} +``` + +A successful response includes the JSON object: + +```javascript +{ + // Indicates the add succeeded, always true. + "ok": true, + // A string to be displayed to the user. + "msg": "user ehuss has been invited to be an owner of crate cargo" +} +``` + +##### Owners: Remove + +- Endpoint: `/api/v1/crates/{crate_name}/owners` +- Method: DELETE +- Authorization: Included + +A DELETE request will remove an owner from a crate. The request should include +the following JSON object: + +```javascript +{ + // Array of `login` strings of owners to remove. + "users": ["login_name"] +} +``` + +A successful response includes the JSON object: + +```javascript +{ + // Indicates the remove succeeded, always true. + "ok": true +} +``` + +#### Search + +- Endpoint: `/api/v1/crates` +- Method: GET +- Query Parameters: + - `q`: The search query string. + - `per_page`: Number of results, default 10, max 100. + +The search request will perform a search for crates, using criteria defined on +the server. + +A successful response includes the JSON object: + +```javascript +{ + // Array of results. + "crates": [ + { + // Name of the crate. + "name": "rand", + // The highest version available. + "max_version": "0.6.1", + // Textual description of the crate. + "description": "Random number generators and other randomness functionality.\n", + } + ], + "meta": { + // Total number of results available on the server. + "total": 119 + } +} +``` + +#### Login + +- Endpoint: `/me` + +The "login" endpoint is not an actual API request. It exists solely for the +[`cargo login`] command to display a URL to instruct a user to visit in a web +browser to log in and retrieve an API token. + +[Source Replacement]: reference/source-replacement.html +[`cargo login`]: commands/cargo-login.html +[`cargo package`]: commands/cargo-package.html +[`cargo publish`]: commands/cargo-publish.html +[alphanumeric]: https://doc.rust-lang.org/std/primitive.char.html#method.is_alphanumeric +[config]: reference/config.html +[crates.io]: https://crates.io/ +[publishing documentation]: reference/publishing.html#cargo-owner diff --git a/src/doc/src/reference/specifying-dependencies.md b/src/doc/src/reference/specifying-dependencies.md index 512862e5e9b..daa6533df6e 100644 --- a/src/doc/src/reference/specifying-dependencies.md +++ b/src/doc/src/reference/specifying-dependencies.md @@ -1,11 +1,12 @@ ## Specifying Dependencies -Your crates can depend on other libraries from [crates.io], `git` repositories, or -subdirectories on your local file system. You can also temporarily override the -location of a dependency— for example, to be able to test out a bug fix in the -dependency that you are working on locally. You can have different -dependencies for different platforms, and dependencies that are only used during -development. Let's take a look at how to do each of these. +Your crates can depend on other libraries from [crates.io] or other +registries, `git` repositories, or subdirectories on your local file system. +You can also temporarily override the location of a dependency — for example, +to be able to test out a bug fix in the dependency that you are working on +locally. You can have different dependencies for different platforms, and +dependencies that are only used during development. Let's take a look at how +to do each of these. ### Specifying dependencies from crates.io @@ -101,6 +102,20 @@ Here are some examples of inequality requirements: Multiple version requirements can also be 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 +documentation] for more information. In the dependency, set the `registry` key +to the name of the registry to use. + +```toml +[dependencies] +some-crate = { version = "1.0", registry = "my-registry" } +``` + +[registries documentation]: reference/registries.html + ### Specifying dependencies from `git` repositories To depend on a library located in a `git` repository, the minimum information diff --git a/src/doc/src/reference/unstable.md b/src/doc/src/reference/unstable.md index 9a46176cd82..4e3327b029a 100644 --- a/src/doc/src/reference/unstable.md +++ b/src/doc/src/reference/unstable.md @@ -10,59 +10,6 @@ command-line flags. Options requiring this will be called out below. Some unstable features will require you to specify the `cargo-features` key in `Cargo.toml`. -### Alternate Registries -* RFC: [#2141](https://github.com/rust-lang/rfcs/blob/master/text/2141-alternative-registries.md) -* Tracking Issue: [rust-lang/rust#44931](https://github.com/rust-lang/rust/issues/44931) - -Alternate registries allow you to use registries other than crates.io. - -The name of a registry is defined in `.cargo/config` under the `registries` -table: - -```toml -[registries] -my-registry = { index = "https://my-intranet:8080/git/index" } -``` - -Authentication information for alternate registries can be added to -`.cargo/credentials`: - -```toml -[registries.my-registry] -token = "api-token" -``` - -Inside `Cargo.toml` you can specify which registry a dependency comes from -using the `registry` key. First you need to include the appropriate -`cargo-features` at the top of the file: - -```toml -cargo-features = ["alternative-registries"] - -[package] -... - -[dependencies] -other-create = { version = "1.0", registry = "my-registry"} -``` - -A `--registry` flag has been added to commands that interact with registries -such as `publish`, `login`, etc. Example: - -``` -cargo +nightly publish -Z unstable-options --registry my-registry -``` - -The `publish` field in `Cargo.toml` has been extended to accept a list of -registries that will restrict publishing only to those registries. - -```toml -[package] -... -publish = ["my-registry"] -``` - - ### publish-lockfile * Original Issue: [#2263](https://github.com/rust-lang/cargo/issues/2263) * PR: [#5093](https://github.com/rust-lang/cargo/pull/5093) diff --git a/src/etc/man/cargo-init.1 b/src/etc/man/cargo-init.1 index 2d4b87f3fc9..1a55f5c57dc 100644 --- a/src/etc/man/cargo-init.1 +++ b/src/etc/man/cargo-init.1 @@ -2,12 +2,12 @@ .\" Title: cargo-init .\" Author: [see the "AUTHOR(S)" section] .\" Generator: Asciidoctor 1.5.8 -.\" Date: 2018-12-20 +.\" Date: 2019-01-23 .\" Manual: \ \& .\" Source: \ \& .\" Language: English .\" -.TH "CARGO\-INIT" "1" "2018-12-20" "\ \&" "\ \&" +.TH "CARGO\-INIT" "1" "2019-01-23" "\ \&" "\ \&" .ie \n(.g .ds Aq \(aq .el .ds Aq ' .ss \n[.ss] 0 @@ -246,11 +246,15 @@ hg, pijul, or fossil) or do not initialize any version control at all .sp \fB\-\-registry\fP \fIREGISTRY\fP .RS 4 -Alternative registry to use. This sets the \fBpublish\fP field which will -restrict publishing only to the given registry name. -.sp -This option is unstable and available only on the nightly channel and requires -the \fB\-Z unstable\-options\fP flag to enable. +This sets the \fBpublish\fP field in \fBCargo.toml\fP to the given registry name +which will restrict publishing only to that registry. +.sp +Registry names are defined in \c +.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "Cargo config files" "." +If not specified, the default registry defined by the \fBregistry.default\fP +config key is used. If the default registry is not set and \fB\-\-registry\fP is not +used, the \fBpublish\fP field will not be set which means that publishing will not +be restricted. .RE .SS "Display Options" .sp diff --git a/src/etc/man/cargo-install.1 b/src/etc/man/cargo-install.1 index 23234569b02..e23c41eaa11 100644 --- a/src/etc/man/cargo-install.1 +++ b/src/etc/man/cargo-install.1 @@ -2,12 +2,12 @@ .\" Title: cargo-install .\" Author: [see the "AUTHOR(S)" section] .\" Generator: Asciidoctor 1.5.8 -.\" Date: 2018-12-23 +.\" Date: 2019-01-23 .\" Manual: \ \& .\" Source: \ \& .\" Language: English .\" -.TH "CARGO\-INSTALL" "1" "2018-12-23" "\ \&" "\ \&" +.TH "CARGO\-INSTALL" "1" "2019-01-23" "\ \&" "\ \&" .ie \n(.g .ds Aq \(aq .el .ds Aq ' .ss \n[.ss] 0 @@ -191,10 +191,10 @@ Directory to install packages into. .sp \fB\-\-registry\fP \fIREGISTRY\fP .RS 4 -Alternative registry to use. -.sp -This option is unstable and available only on the nightly channel and requires -the \fB\-Z unstable\-options\fP flag to enable. +Name of the registry to use. Registry names are defined in \c +.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "Cargo config files" "." +If not specified, the default registry is used, which is defined by the +\fBregistry.default\fP config key which defaults to \fBcrates\-io\fP. .RE .SS "Feature Selection" .sp diff --git a/src/etc/man/cargo-login.1 b/src/etc/man/cargo-login.1 index 83d7f8f2b15..2f9ec810bf0 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 1.5.8 -.\" Date: 2018-12-23 +.\" Date: 2019-01-23 .\" Manual: \ \& .\" Source: \ \& .\" Language: English .\" -.TH "CARGO\-LOGIN" "1" "2018-12-23" "\ \&" "\ \&" +.TH "CARGO\-LOGIN" "1" "2019-01-23" "\ \&" "\ \&" .ie \n(.g .ds Aq \(aq .el .ds Aq ' .ss \n[.ss] 0 @@ -50,10 +50,10 @@ Take care to keep the token secret, it should not be shared with anyone else. .sp \fB\-\-registry\fP \fIREGISTRY\fP .RS 4 -Alternative registry to use. -.sp -This option is unstable and available only on the nightly channel and requires -the \fB\-Z unstable\-options\fP flag to enable. +Name of the registry to use. Registry names are defined in \c +.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "Cargo config files" "." +If not specified, the default registry is used, which is defined by the +\fBregistry.default\fP config key which defaults to \fBcrates\-io\fP. .RE .SS "Display Options" .sp diff --git a/src/etc/man/cargo-new.1 b/src/etc/man/cargo-new.1 index 06dc2b1ece2..894b5ab6e2f 100644 --- a/src/etc/man/cargo-new.1 +++ b/src/etc/man/cargo-new.1 @@ -2,12 +2,12 @@ .\" Title: cargo-new .\" Author: [see the "AUTHOR(S)" section] .\" Generator: Asciidoctor 1.5.8 -.\" Date: 2018-12-20 +.\" Date: 2019-01-23 .\" Manual: \ \& .\" Source: \ \& .\" Language: English .\" -.TH "CARGO\-NEW" "1" "2018-12-20" "\ \&" "\ \&" +.TH "CARGO\-NEW" "1" "2019-01-23" "\ \&" "\ \&" .ie \n(.g .ds Aq \(aq .el .ds Aq ' .ss \n[.ss] 0 @@ -241,11 +241,15 @@ hg, pijul, or fossil) or do not initialize any version control at all .sp \fB\-\-registry\fP \fIREGISTRY\fP .RS 4 -Alternative registry to use. This sets the \fBpublish\fP field which will -restrict publishing only to the given registry name. -.sp -This option is unstable and available only on the nightly channel and requires -the \fB\-Z unstable\-options\fP flag to enable. +This sets the \fBpublish\fP field in \fBCargo.toml\fP to the given registry name +which will restrict publishing only to that registry. +.sp +Registry names are defined in \c +.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "Cargo config files" "." +If not specified, the default registry defined by the \fBregistry.default\fP +config key is used. If the default registry is not set and \fB\-\-registry\fP is not +used, the \fBpublish\fP field will not be set which means that publishing will not +be restricted. .RE .SS "Display Options" .sp diff --git a/src/etc/man/cargo-owner.1 b/src/etc/man/cargo-owner.1 index 666e746dff7..8e798a3b2bf 100644 --- a/src/etc/man/cargo-owner.1 +++ b/src/etc/man/cargo-owner.1 @@ -2,12 +2,12 @@ .\" Title: cargo-owner .\" Author: [see the "AUTHOR(S)" section] .\" Generator: Asciidoctor 1.5.8 -.\" Date: 2018-12-20 +.\" Date: 2019-02-05 .\" Manual: \ \& .\" Source: \ \& .\" Language: English .\" -.TH "CARGO\-OWNER" "1" "2018-12-20" "\ \&" "\ \&" +.TH "CARGO\-OWNER" "1" "2019-02-05" "\ \&" "\ \&" .ie \n(.g .ds Aq \(aq .el .ds Aq ' .ss \n[.ss] 0 @@ -72,7 +72,16 @@ List owners of a crate. .sp \fB\-\-token\fP \fITOKEN\fP .RS 4 -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 \fBcargo\-login\fP(1)). +.sp +.URL "https://doc.rust\-lang.org/cargo/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 \fBCARGO_REGISTRY_TOKEN\fP environment +variable. Tokens for other registries may be specified with environment +variables of the form \fBCARGO_REGISTRIES_NAME_TOKEN\fP where \fBNAME\fP is the name +of the registry in all capital letters. .RE .sp \fB\-\-index\fP \fIINDEX\fP @@ -82,10 +91,10 @@ The URL of the registry index to use. .sp \fB\-\-registry\fP \fIREGISTRY\fP .RS 4 -Alternative registry to use. -.sp -This option is unstable and available only on the nightly channel and requires -the \fB\-Z unstable\-options\fP flag to enable. +Name of the registry to use. Registry names are defined in \c +.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "Cargo config files" "." +If not specified, the default registry is used, which is defined by the +\fBregistry.default\fP config key which defaults to \fBcrates\-io\fP. .RE .SS "Display Options" .sp diff --git a/src/etc/man/cargo-publish.1 b/src/etc/man/cargo-publish.1 index b3521b1fef2..70e4f506f4e 100644 --- a/src/etc/man/cargo-publish.1 +++ b/src/etc/man/cargo-publish.1 @@ -2,12 +2,12 @@ .\" Title: cargo-publish .\" Author: [see the "AUTHOR(S)" section] .\" Generator: Asciidoctor 1.5.8 -.\" Date: 2019-01-14 +.\" Date: 2019-02-05 .\" Manual: \ \& .\" Source: \ \& .\" Language: English .\" -.TH "CARGO\-PUBLISH" "1" "2019-01-14" "\ \&" "\ \&" +.TH "CARGO\-PUBLISH" "1" "2019-02-05" "\ \&" "\ \&" .ie \n(.g .ds Aq \(aq .el .ds Aq ' .ss \n[.ss] 0 @@ -115,7 +115,16 @@ Perform all checks without uploading. .sp \fB\-\-token\fP \fITOKEN\fP .RS 4 -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 \fBcargo\-login\fP(1)). +.sp +.URL "https://doc.rust\-lang.org/cargo/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 \fBCARGO_REGISTRY_TOKEN\fP environment +variable. Tokens for other registries may be specified with environment +variables of the form \fBCARGO_REGISTRIES_NAME_TOKEN\fP where \fBNAME\fP is the name +of the registry in all capital letters. .RE .sp \fB\-\-no\-verify\fP @@ -135,10 +144,10 @@ The URL of the registry index to use. .sp \fB\-\-registry\fP \fIREGISTRY\fP .RS 4 -Alternative registry to use. -.sp -This option is unstable and available only on the nightly channel and requires -the \fB\-Z unstable\-options\fP flag to enable. +Name of the registry to use. Registry names are defined in \c +.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "Cargo config files" "." +If not specified, the default registry is used, which is defined by the +\fBregistry.default\fP config key which defaults to \fBcrates\-io\fP. .RE .SS "Compilation Options" .sp diff --git a/src/etc/man/cargo-search.1 b/src/etc/man/cargo-search.1 index 272f71c4878..a789ac6c09a 100644 --- a/src/etc/man/cargo-search.1 +++ b/src/etc/man/cargo-search.1 @@ -2,12 +2,12 @@ .\" Title: cargo-search .\" Author: [see the "AUTHOR(S)" section] .\" Generator: Asciidoctor 1.5.8 -.\" Date: 2018-12-20 +.\" Date: 2019-01-23 .\" Manual: \ \& .\" Source: \ \& .\" Language: English .\" -.TH "CARGO\-SEARCH" "1" "2018-12-20" "\ \&" "\ \&" +.TH "CARGO\-SEARCH" "1" "2019-01-23" "\ \&" "\ \&" .ie \n(.g .ds Aq \(aq .el .ds Aq ' .ss \n[.ss] 0 @@ -54,10 +54,10 @@ The URL of the registry index to use. .sp \fB\-\-registry\fP \fIREGISTRY\fP .RS 4 -Alternative registry to use. -.sp -This option is unstable and available only on the nightly channel and requires -the \fB\-Z unstable\-options\fP flag to enable. +Name of the registry to use. Registry names are defined in \c +.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "Cargo config files" "." +If not specified, the default registry is used, which is defined by the +\fBregistry.default\fP config key which defaults to \fBcrates\-io\fP. .RE .SS "Display Options" .sp diff --git a/src/etc/man/cargo-yank.1 b/src/etc/man/cargo-yank.1 index c5ad056edc8..c3a637c7ae4 100644 --- a/src/etc/man/cargo-yank.1 +++ b/src/etc/man/cargo-yank.1 @@ -2,12 +2,12 @@ .\" Title: cargo-yank .\" Author: [see the "AUTHOR(S)" section] .\" Generator: Asciidoctor 1.5.8 -.\" Date: 2018-12-20 +.\" Date: 2019-01-23 .\" Manual: \ \& .\" Source: \ \& .\" Language: English .\" -.TH "CARGO\-YANK" "1" "2018-12-20" "\ \&" "\ \&" +.TH "CARGO\-YANK" "1" "2019-01-23" "\ \&" "\ \&" .ie \n(.g .ds Aq \(aq .el .ds Aq ' .ss \n[.ss] 0 @@ -62,7 +62,16 @@ Undo a yank, putting a version back into the index. .sp \fB\-\-token\fP \fITOKEN\fP .RS 4 -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 \fBcargo\-login\fP(1)). +.sp +.URL "https://doc.rust\-lang.org/cargo/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 \fBCARGO_REGISTRY_TOKEN\fP environment +variable. Tokens for other registries may be specified with environment +variables of the form \fBCARGO_REGISTRIES_NAME_TOKEN\fP where \fBNAME\fP is the name +of the registry in all capital letters. .RE .sp \fB\-\-index\fP \fIINDEX\fP @@ -72,10 +81,10 @@ The URL of the registry index to use. .sp \fB\-\-registry\fP \fIREGISTRY\fP .RS 4 -Alternative registry to use. -.sp -This option is unstable and available only on the nightly channel and requires -the \fB\-Z unstable\-options\fP flag to enable. +Name of the registry to use. Registry names are defined in \c +.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "Cargo config files" "." +If not specified, the default registry is used, which is defined by the +\fBregistry.default\fP config key which defaults to \fBcrates\-io\fP. .RE .SS "Display Options" .sp diff --git a/tests/testsuite/alt_registry.rs b/tests/testsuite/alt_registry.rs index 09098eb0b7f..3e58a92e6ce 100644 --- a/tests/testsuite/alt_registry.rs +++ b/tests/testsuite/alt_registry.rs @@ -5,42 +5,12 @@ use cargo::util::ToUrl; use std::fs::{self, File}; use std::io::Write; -#[test] -fn is_feature_gated() { - let p = project() - .file( - "Cargo.toml", - r#" - [project] - name = "foo" - version = "0.0.1" - authors = [] - - [dependencies.bar] - version = "0.0.1" - registry = "alternative" - "#, - ) - .file("src/main.rs", "fn main() {}") - .build(); - - Package::new("bar", "0.0.1").alternative(true).publish(); - - p.cargo("build") - .masquerade_as_nightly_cargo() - .with_status(101) - .with_stderr_contains(" feature `alternative-registries` is required") - .run(); -} - #[test] fn depend_on_alt_registry() { let p = project() .file( "Cargo.toml", r#" - cargo-features = ["alternative-registries"] - [project] name = "foo" version = "0.0.1" @@ -57,7 +27,6 @@ fn depend_on_alt_registry() { Package::new("bar", "0.0.1").alternative(true).publish(); p.cargo("build") - .masquerade_as_nightly_cargo() .with_stderr(&format!( "\ [UPDATING] `{reg}` index @@ -71,11 +40,10 @@ fn depend_on_alt_registry() { )) .run(); - p.cargo("clean").masquerade_as_nightly_cargo().run(); + p.cargo("clean").run(); // Don't download a second time p.cargo("build") - .masquerade_as_nightly_cargo() .with_stderr( "\ [COMPILING] bar v0.0.1 (registry `[ROOT][..]`) @@ -92,8 +60,6 @@ fn depend_on_alt_registry_depends_on_same_registry_no_index() { .file( "Cargo.toml", r#" - cargo-features = ["alternative-registries"] - [project] name = "foo" version = "0.0.1" @@ -114,7 +80,6 @@ fn depend_on_alt_registry_depends_on_same_registry_no_index() { .publish(); p.cargo("build") - .masquerade_as_nightly_cargo() .with_stderr(&format!( "\ [UPDATING] `{reg}` index @@ -137,8 +102,6 @@ fn depend_on_alt_registry_depends_on_same_registry() { .file( "Cargo.toml", r#" - cargo-features = ["alternative-registries"] - [project] name = "foo" version = "0.0.1" @@ -159,7 +122,6 @@ fn depend_on_alt_registry_depends_on_same_registry() { .publish(); p.cargo("build") - .masquerade_as_nightly_cargo() .with_stderr(&format!( "\ [UPDATING] `{reg}` index @@ -182,8 +144,6 @@ fn depend_on_alt_registry_depends_on_crates_io() { .file( "Cargo.toml", r#" - cargo-features = ["alternative-registries"] - [project] name = "foo" version = "0.0.1" @@ -204,7 +164,6 @@ fn depend_on_alt_registry_depends_on_crates_io() { .publish(); p.cargo("build") - .masquerade_as_nightly_cargo() .with_stderr_unordered(&format!( "\ [UPDATING] `{alt_reg}` index @@ -231,8 +190,6 @@ fn registry_and_path_dep_works() { .file( "Cargo.toml", r#" - cargo-features = ["alternative-registries"] - [project] name = "foo" version = "0.0.1" @@ -249,7 +206,6 @@ fn registry_and_path_dep_works() { .build(); p.cargo("build") - .masquerade_as_nightly_cargo() .with_stderr( "\ [COMPILING] bar v0.0.1 ([CWD]/bar) @@ -268,8 +224,6 @@ fn registry_incompatible_with_git() { .file( "Cargo.toml", r#" - cargo-features = ["alternative-registries"] - [project] name = "foo" version = "0.0.1" @@ -283,8 +237,13 @@ fn registry_incompatible_with_git() { .file("src/main.rs", "fn main() {}") .build(); - p.cargo("build").masquerade_as_nightly_cargo().with_status(101) - .with_stderr_contains(" dependency (bar) specification is ambiguous. Only one of `git` or `registry` is allowed.").run(); + p.cargo("build") + .with_status(101) + .with_stderr_contains( + " dependency (bar) specification is ambiguous. \ + Only one of `git` or `registry` is allowed.", + ) + .run(); } #[test] @@ -295,7 +254,6 @@ fn cannot_publish_to_crates_io_with_registry_dependency() { .file( "Cargo.toml", r#" - cargo-features = ["alternative-registries"] [project] name = "foo" version = "0.0.1" @@ -331,15 +289,13 @@ fn cannot_publish_to_crates_io_with_registry_dependency() { ) .build(); - p.cargo("publish --registry fakeio -Z unstable-options") - .masquerade_as_nightly_cargo() + p.cargo("publish --registry fakeio") .with_status(101) .with_stderr_contains("[ERROR] crates cannot be published to crates.io[..]") .run(); p.cargo("publish --index") .arg(fakeio_url.to_string()) - .masquerade_as_nightly_cargo() .with_status(101) .with_stderr_contains("[ERROR] crates cannot be published to crates.io[..]") .run(); @@ -351,8 +307,6 @@ fn publish_with_registry_dependency() { .file( "Cargo.toml", r#" - cargo-features = ["alternative-registries"] - [project] name = "foo" version = "0.0.1" @@ -369,13 +323,9 @@ fn publish_with_registry_dependency() { Package::new("bar", "0.0.1").alternative(true).publish(); // Login so that we have the token available - p.cargo("login --registry alternative TOKEN -Zunstable-options") - .masquerade_as_nightly_cargo() - .run(); + p.cargo("login --registry alternative TOKEN").run(); - p.cargo("publish --registry alternative -Zunstable-options") - .masquerade_as_nightly_cargo() - .run(); + p.cargo("publish --registry alternative").run(); validate_alt_upload( r#"{ @@ -418,8 +368,6 @@ fn alt_registry_and_crates_io_deps() { .file( "Cargo.toml", r#" - cargo-features = ["alternative-registries"] - [project] name = "foo" version = "0.0.1" @@ -442,7 +390,6 @@ fn alt_registry_and_crates_io_deps() { .publish(); p.cargo("build") - .masquerade_as_nightly_cargo() .with_stderr_contains(format!( "[UPDATING] `{}` index", registry::alt_registry_path().to_str().unwrap() @@ -470,8 +417,7 @@ fn block_publish_due_to_no_token() { fs::remove_file(paths::home().join(".cargo/credentials")).unwrap(); // Now perform the actual publish - p.cargo("publish --registry alternative -Zunstable-options") - .masquerade_as_nightly_cargo() + p.cargo("publish --registry alternative") .with_status(101) .with_stderr_contains("error: no upload token found, please run `cargo login`") .run(); @@ -479,33 +425,16 @@ fn block_publish_due_to_no_token() { #[test] fn publish_to_alt_registry() { - let p = project() - .file( - "Cargo.toml", - r#" - cargo-features = ["alternative-registries"] - - [project] - name = "foo" - version = "0.0.1" - authors = [] - "#, - ) - .file("src/main.rs", "fn main() {}") - .build(); + let p = project().file("src/main.rs", "fn main() {}").build(); // Setup the registry by publishing a package Package::new("bar", "0.0.1").alternative(true).publish(); // Login so that we have the token available - p.cargo("login --registry alternative TOKEN -Zunstable-options") - .masquerade_as_nightly_cargo() - .run(); + p.cargo("login --registry alternative TOKEN").run(); // Now perform the actual publish - p.cargo("publish --registry alternative -Zunstable-options") - .masquerade_as_nightly_cargo() - .run(); + p.cargo("publish --registry alternative").run(); validate_alt_upload( r#"{ @@ -538,8 +467,6 @@ fn publish_with_crates_io_dep() { .file( "Cargo.toml", r#" - cargo-features = ["alternative-registries"] - [project] name = "foo" version = "0.0.1" @@ -557,13 +484,9 @@ fn publish_with_crates_io_dep() { Package::new("bar", "0.0.1").publish(); // Login so that we have the token available - p.cargo("login --registry alternative TOKEN -Zunstable-options") - .masquerade_as_nightly_cargo() - .run(); + p.cargo("login --registry alternative TOKEN").run(); - p.cargo("publish --registry alternative -Zunstable-options") - .masquerade_as_nightly_cargo() - .run(); + p.cargo("publish --registry alternative").run(); validate_alt_upload( r#"{ @@ -617,23 +540,9 @@ fn passwords_in_url_forbidden() { ) .unwrap(); - let p = project() - .file( - "Cargo.toml", - r#" - cargo-features = ["alternative-registries"] - - [project] - name = "foo" - version = "0.0.1" - authors = [] - "#, - ) - .file("src/main.rs", "fn main() {}") - .build(); + let p = project().file("src/main.rs", "fn main() {}").build(); - p.cargo("publish --registry alternative -Zunstable-options") - .masquerade_as_nightly_cargo() + p.cargo("publish --registry alternative") .with_status(101) .with_stderr_contains("error: Registry URLs may not contain passwords") .run(); @@ -646,8 +555,6 @@ fn patch_alt_reg() { .file( "Cargo.toml", r#" - cargo-features = ["alternative-registries"] - [package] name = "foo" version = "0.0.1" @@ -671,7 +578,6 @@ fn patch_alt_reg() { .build(); p.cargo("build") - .masquerade_as_nightly_cargo() .with_stderr( "\ [UPDATING] `[ROOT][..]` index @@ -689,8 +595,6 @@ fn bad_registry_name() { .file( "Cargo.toml", r#" - cargo-features = ["alternative-registries"] - [project] name = "foo" version = "0.0.1" @@ -705,7 +609,6 @@ fn bad_registry_name() { .build(); p.cargo("build") - .masquerade_as_nightly_cargo() .with_status(101) .with_stderr( "\ @@ -720,10 +623,8 @@ Caused by: "init", "install", "login", "owner", "publish", "search", "yank", ] { p.cargo(cmd) - .arg("-Zunstable-options") .arg("--registry") .arg("bad name") - .masquerade_as_nightly_cargo() .with_status(101) .with_stderr("[ERROR] Invalid character ` ` in registry name: `bad name`") .run(); @@ -749,7 +650,6 @@ fn no_api() { .file( "Cargo.toml", r#" - cargo-features = ["alternative-registries"] [package] name = "foo" version = "0.0.1" @@ -763,7 +663,6 @@ fn no_api() { .build(); p.cargo("build") - .masquerade_as_nightly_cargo() .with_stderr(&format!( "\ [UPDATING] `{reg}` index @@ -783,38 +682,32 @@ fn no_api() { registry::alt_registry_path().display() ); - p.cargo("login --registry alternative TOKEN -Zunstable-options") - .masquerade_as_nightly_cargo() + p.cargo("login --registry alternative TOKEN") .with_status(101) .with_stderr_contains(&err) .run(); - p.cargo("publish --registry alternative -Zunstable-options") - .masquerade_as_nightly_cargo() + p.cargo("publish --registry alternative") .with_status(101) .with_stderr_contains(&err) .run(); - p.cargo("search --registry alternative -Zunstable-options") - .masquerade_as_nightly_cargo() + p.cargo("search --registry alternative") .with_status(101) .with_stderr_contains(&err) .run(); - p.cargo("owner --registry alternative -Zunstable-options --list") - .masquerade_as_nightly_cargo() + p.cargo("owner --registry alternative --list") .with_status(101) .with_stderr_contains(&err) .run(); - p.cargo("yank --registry alternative -Zunstable-options --vers=0.0.1 bar") - .masquerade_as_nightly_cargo() + p.cargo("yank --registry alternative --vers=0.0.1 bar") .with_status(101) .with_stderr_contains(&err) .run(); - p.cargo("yank --registry alternative -Zunstable-options --vers=0.0.1 bar") - .masquerade_as_nightly_cargo() + p.cargo("yank --registry alternative --vers=0.0.1 bar") .with_stderr_contains(&err) .with_status(101) .run(); @@ -827,7 +720,6 @@ fn alt_reg_metadata() { .file( "Cargo.toml", r#" - cargo-features = ["alternative-registries"] [package] name = "foo" version = "0.0.1" @@ -857,7 +749,6 @@ fn alt_reg_metadata() { // altdep -> bar: null (because it is in crates.io) // iodep -> altdep2: alternative-registry p.cargo("metadata --format-version=1 --no-deps") - .masquerade_as_nightly_cargo() .with_json( r#" { @@ -922,7 +813,6 @@ fn alt_reg_metadata() { // --no-deps uses a different code path, make sure both work. p.cargo("metadata --format-version=1") - .masquerade_as_nightly_cargo() .with_json( r#" { @@ -1104,8 +994,6 @@ fn unknown_registry() { .file( "Cargo.toml", r#" - cargo-features = ["alternative-registries"] - [project] name = "foo" version = "0.0.1" @@ -1132,13 +1020,12 @@ fn unknown_registry() { config.insert(start + start_index, '#'); fs::write(&cfg_path, config).unwrap(); - p.cargo("build").masquerade_as_nightly_cargo().run(); + p.cargo("build").run(); // Important parts: // foo -> bar registry = null // bar -> baz registry = alternate p.cargo("metadata --format-version=1") - .masquerade_as_nightly_cargo() .with_json( r#" { diff --git a/tests/testsuite/publish.rs b/tests/testsuite/publish.rs index 11e9d23ba49..2976e1a196e 100644 --- a/tests/testsuite/publish.rs +++ b/tests/testsuite/publish.rs @@ -616,47 +616,6 @@ See [..] assert!(!registry::api_path().join("api/v1/crates/new").exists()); } -#[test] -fn block_publish_feature_not_enabled() { - registry::init(); - - let p = project() - .file( - "Cargo.toml", - r#" - [project] - name = "foo" - version = "0.0.1" - authors = [] - license = "MIT" - description = "foo" - publish = [ - "test" - ] - "#, - ) - .file("src/main.rs", "fn main() {}") - .build(); - - p.cargo("publish --registry alternative -Zunstable-options") - .masquerade_as_nightly_cargo() - .with_status(101) - .with_stderr( - "\ -error: failed to parse manifest at `[..]` - -Caused by: - the `publish` manifest key is unstable for anything other than a value of true or false - -Caused by: - feature `alternative-registries` is required - -consider adding `cargo-features = [\"alternative-registries\"]` to the manifest -", - ) - .run(); -} - #[test] fn registry_not_in_publish_list() { registry::init(); @@ -665,8 +624,6 @@ fn registry_not_in_publish_list() { .file( "Cargo.toml", r#" - cargo-features = ["alternative-registries"] - [project] name = "foo" version = "0.0.1" @@ -682,10 +639,8 @@ fn registry_not_in_publish_list() { .build(); p.cargo("publish") - .masquerade_as_nightly_cargo() .arg("--registry") .arg("alternative") - .arg("-Zunstable-options") .with_status(101) .with_stderr( "\ @@ -704,8 +659,6 @@ fn publish_empty_list() { .file( "Cargo.toml", r#" - cargo-features = ["alternative-registries"] - [project] name = "foo" version = "0.0.1" @@ -718,8 +671,7 @@ fn publish_empty_list() { .file("src/main.rs", "fn main() {}") .build(); - p.cargo("publish --registry alternative -Zunstable-options") - .masquerade_as_nightly_cargo() + p.cargo("publish --registry alternative") .with_status(101) .with_stderr( "\ @@ -740,8 +692,6 @@ fn publish_allowed_registry() { .file( "Cargo.toml", r#" - cargo-features = ["alternative-registries"] - [project] name = "foo" version = "0.0.1" @@ -757,9 +707,7 @@ fn publish_allowed_registry() { .file("src/main.rs", "fn main() {}") .build(); - p.cargo("publish --registry alternative -Zunstable-options") - .masquerade_as_nightly_cargo() - .run(); + p.cargo("publish --registry alternative").run(); publish::validate_alt_upload( CLEAN_FOO_JSON, @@ -781,8 +729,6 @@ fn block_publish_no_registry() { .file( "Cargo.toml", r#" - cargo-features = ["alternative-registries"] - [project] name = "foo" version = "0.0.1" @@ -795,8 +741,7 @@ fn block_publish_no_registry() { .file("src/main.rs", "fn main() {}") .build(); - p.cargo("publish --registry alternative -Zunstable-options") - .masquerade_as_nightly_cargo() + p.cargo("publish --registry alternative") .with_status(101) .with_stderr( "\ diff --git a/tests/testsuite/support/registry.rs b/tests/testsuite/support/registry.rs index eaf944d2724..26fb50df67f 100644 --- a/tests/testsuite/support/registry.rs +++ b/tests/testsuite/support/registry.rs @@ -249,7 +249,7 @@ impl Package { /// /// The name of the alternative registry is called "alternative". /// - /// See `unstable.html#alternate-registries` for more details on + /// See `src/doc/src/reference/registries.md` for more details on /// alternative registries. See `alt_registry.rs` for the tests that use /// this. pub fn alternative(&mut self, alternative: bool) -> &mut Package {