@rfcbot fcp merge

This issue is to track the proposal to stabilize alternative registries.

RFC: 2141
Tracking Issue: rust-lang/rust#44931
Stabilization Target: 1.34 — Release date Apr 11 2019

What is being stabilized

Alternate registries allows Cargo to use registries other than crates.io. The following is an overview of the surface changes:

• Alternate registries are defined in .cargo/config under the registries table, example:

  [registries]
  my-registry = { index = "https://my-intranet:8080/git/index" }

• Dependencies in Cargo.toml can reference other registries with the registry key, example:

  [dependencies]
  other-crate = { version = "1.0", registry = "my-registry"}

• Commands may take the --registry flag to specify the server to interact with. This includes install, login, owner, publish, search, and yank. new and init also take the same flag to initialize the publish field. Example:

  cargo publish --registry my-registry

  • The default for --registry may be specified in .cargo/config with the registry.default key (except new and init, see cargo publish should be opt-in #6153). Example:

  [registry]
  default = "my-registry"

• Manifests may restrict which registry they may interact with the publish key, example:

  [package]
  publish = ["my-registry"]

• Authentication information saved by cargo login is stored in .cargo/credentials under the registries table:

  [registries.my-registry]
  token = "854DvwSlUwEHtIo3kWy6x7UCPKHfzCmy"

• Ancillary feature support:

  • cargo metadata exposes the registry field for dependency declarations. source and PackageID fields also point to the registry.
  • [patch] tables can be a registry name or index URL.
  • Registries may opt-out of Web API support, in which case commands like publish display an appropriate error message.

• Misc post-RFC decisions:

  • Registries as URLs in Cargo.toml are currently not allowed.
  • Registry names are restricted to the same format as package names (alphanumeric characters, dash, and underscore only).
  • Registry URLs in [registries] may contain usernames, but not passwords.
  • The crates.io codebase won't currently cater towards being used for alternative registries. Cargo refuses to publish alternative dependencies to crates.io, and crates.io double-checks to prevent it.
  • generate-index-metadata will currently not be implemented directly in Cargo. cargo-index is a demonstration of how it can be implemented using cargo metadata.
  • cargo-reg is a third-party util to assist adding registries to .cargo/config.

• Documentation: I have written a new chapter for the Cargo Reference that goes into depth about registries. This includes how to use them, how to run one, the index format, and the minimum required Web API. I will be posting this soon.