From 7dc55067569e99bf8fe4a23f38e1ec511f71e27d Mon Sep 17 00:00:00 2001 From: Arlo Siemsen Date: Thu, 13 Oct 2022 16:00:23 -0500 Subject: [PATCH] Stabilize sparse-registry --- src/cargo/core/features.rs | 14 +- src/cargo/sources/registry/http_remote.rs | 3 - src/doc/src/reference/config.md | 14 + src/doc/src/reference/registries.md | 21 +- src/doc/src/reference/registry-index.md | 62 ++- src/doc/src/reference/unstable.md | 32 +- tests/testsuite/alt_registry.rs | 12 +- tests/testsuite/publish.rs | 28 +- tests/testsuite/registry.rs | 496 ++++++++++------------ tests/testsuite/registry_auth.rs | 9 +- 10 files changed, 347 insertions(+), 344 deletions(-) diff --git a/src/cargo/core/features.rs b/src/cargo/core/features.rs index 21608b9ab35..2c6e503d5b5 100644 --- a/src/cargo/core/features.rs +++ b/src/cargo/core/features.rs @@ -681,7 +681,7 @@ unstable_cli_options!( no_index_update: bool = ("Do not update the registry index even if the cache is outdated"), panic_abort_tests: bool = ("Enable support to run tests with -Cpanic=abort"), host_config: bool = ("Enable the [host] section in the .cargo/config.toml file"), - sparse_registry: bool = ("Support plain-HTTP-based crate registries"), + sparse_registry: bool = ("Use the sparse protocol when accessing crates.io"), registry_auth: bool = ("Authentication for alternative registries, and generate registry authentication tokens using asymmetric cryptography"), target_applies_to_host: bool = ("Enable the `target-applies-to-host` key in the .cargo/config.toml file"), rustdoc_map: bool = ("Allow passing external documentation mappings to rustdoc"), @@ -751,6 +751,11 @@ const STABILISED_MULTITARGET: &str = "Multiple `--target` options are now always const STABILIZED_TERMINAL_WIDTH: &str = "The -Zterminal-width option is now always enabled for terminal output."; +const STABILISED_SPARSE_REGISTRY: &str = "This flag currently still sets the default protocol\ + to `sparse` when accessing crates.io. However, this will be removed in the future. \n\ + The stable equivalent is to set the config value `registries.crates-io.protocol = 'sparse'`\n\ + or environment variable `CARGO_REGISTRIES_CRATES_IO_PROTOCOL=sparse`"; + fn deserialize_build_std<'de, D>(deserializer: D) -> Result>, D::Error> where D: serde::Deserializer<'de>, @@ -948,7 +953,12 @@ impl CliUnstable { "multitarget" => stabilized_warn(k, "1.64", STABILISED_MULTITARGET), "rustdoc-map" => self.rustdoc_map = parse_empty(k, v)?, "terminal-width" => stabilized_warn(k, "1.68", STABILIZED_TERMINAL_WIDTH), - "sparse-registry" => self.sparse_registry = parse_empty(k, v)?, + "sparse-registry" => { + // Once sparse-registry becomes the default for crates.io, `sparse_registry` should + // be removed entirely from `CliUnstable`. + stabilized_warn(k, "1.68", STABILISED_SPARSE_REGISTRY); + self.sparse_registry = parse_empty(k, v)?; + } "registry-auth" => self.registry_auth = parse_empty(k, v)?, "namespaced-features" => stabilized_warn(k, "1.60", STABILISED_NAMESPACED_FEATURES), "weak-dep-features" => stabilized_warn(k, "1.60", STABILIZED_WEAK_DEP_FEATURES), diff --git a/src/cargo/sources/registry/http_remote.rs b/src/cargo/sources/registry/http_remote.rs index bb136e52709..a890b78a03e 100644 --- a/src/cargo/sources/registry/http_remote.rs +++ b/src/cargo/sources/registry/http_remote.rs @@ -157,9 +157,6 @@ impl<'cfg> HttpRegistry<'cfg> { config: &'cfg Config, name: &str, ) -> CargoResult> { - if !config.cli_unstable().sparse_registry { - anyhow::bail!("usage of sparse registries requires `-Z sparse-registry`"); - } let url = source_id.url().as_str(); // Ensure the url ends with a slash so we can concatenate paths. if !url.ends_with('/') { diff --git a/src/doc/src/reference/config.md b/src/doc/src/reference/config.md index 1e506487975..ba87bd6a9ee 100644 --- a/src/doc/src/reference/config.md +++ b/src/doc/src/reference/config.md @@ -892,6 +892,20 @@ commands like [`cargo publish`] that require authentication. Can be overridden with the `--token` command-line option. +##### `registries.crates-io.protocol` +* Type: string +* Default: `git` +* Environment: `CARGO_REGISTRIES_CRATES_IO_PROTOCOL` + +Specifies the protocol used to access crates.io. Allowed values are `git` or `sparse`. + +`git` causes Cargo to clone the entire index of all packages ever published to [crates.io] from . +This can have performance implications due to the size of the index. +`sparse` is a newer protocol which uses HTTPS to download only what is necessary from . +This can result in a significant performance improvement for resolving new dependencies in most situations. + +More information about registry protocols may be found in the [Registries chapter](registries.md). + #### `[registry]` The `[registry]` table controls the default registry used when one is not diff --git a/src/doc/src/reference/registries.md b/src/doc/src/reference/registries.md index efc27730960..7714a36cdbc 100644 --- a/src/doc/src/reference/registries.md +++ b/src/doc/src/reference/registries.md @@ -22,7 +22,9 @@ table has a key for each registry, for example: 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. +The `index` key should be a URL to a git repository with the registry's index or a +Cargo sparse registry URL with the `sparse+` prefix. + 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`: @@ -98,6 +100,21 @@ has a separate table for each registry, for example: token = "854DvwSlUwEHtIo3kWy6x7UCPKHfzCmy" ``` +### Registry Protocols +Cargo supports two remote registry protocols: `git` and `sparse`. If the registry +index URL starts with `sparse+`, Cargo uses the sparse protocol. Otherwise +Cargo uses the `git` protocol. + +The `git` protocol stores index metadata in a git repository and requires Cargo to clone +the entire repo. + +The `sparse` protocol fetches individual metadata files using plain HTTP requests. +Since Cargo only downloads the metadata for relevant crates, the `sparse` protocol can +save significant time and bandwidth. + +The [crates.io] registry supports both protocols. The protocol for crates.io is +controlled via the [`registries.crates-io.protocol`] config key. + [Source Replacement]: source-replacement.md [Running a Registry]: running-a-registry.md [`cargo publish`]: ../commands/cargo-publish.md @@ -105,6 +122,8 @@ token = "854DvwSlUwEHtIo3kWy6x7UCPKHfzCmy" [`cargo login`]: ../commands/cargo-login.md [config]: config.md [crates.io]: https://crates.io/ +[`registries.crates-io.protocol`]: config.md#registriescrates-ioprotocol +