From 740525f2c4fc1106120692cde51c7d29c79ca6f0 Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Sat, 7 Apr 2018 14:11:07 -0700 Subject: [PATCH] Add unstable documentation. I kept most of these relatively brief with the intent that more complete documentation would be added when a feature is stabilized. I did my best to be accurate, but I am unfamiliar with most of these features, so please let me know if anything should change. @matklad: I didn't fully understand the use case for `minimal-versions`, so I didn't say much about it. In particular, I didn't understand why one wouldn't just use `~` or `=` semver requirements if you wanted to be careful about not pulling in a newer version. When someone says "1.0", aren't they explicitly saying they want a newer version (up to 2.0) if it's available? The example in the RFC of switching a dependency to "=1.0" sounds like a breaking change (essentially downgrading a dependency). --- src/cargo/core/features.rs | 6 + src/doc/src/SUMMARY.md | 1 + src/doc/src/reference/index.md | 1 + src/doc/src/reference/unstable.md | 188 ++++++++++++++++++++++++++++++ 4 files changed, 196 insertions(+) create mode 100644 src/doc/src/reference/unstable.md diff --git a/src/cargo/core/features.rs b/src/cargo/core/features.rs index 09eff8545..c9658a8aa 100644 --- a/src/cargo/core/features.rs +++ b/src/cargo/core/features.rs @@ -35,6 +35,12 @@ //! then you use `chain_err` to tack on more context for why the feature was //! required when the feature isn't activated. //! +//! 4. Update the unstable documentation at +//! `src/doc/src/reference/unstable.md` to include a short description of +//! how to use your new feature. When the feature is stabilized, be sure +//! that the Cargo Guide or Reference is updated to fully document the +//! feature and remove the entry from the Unstable section. +//! //! And hopefully that's it! Bear with us though that this is, at the time of //! this writing, a very new feature in Cargo. If the process differs from this //! we'll be sure to update this documentation! diff --git a/src/doc/src/SUMMARY.md b/src/doc/src/SUMMARY.md index f75ac510e..5330684da 100644 --- a/src/doc/src/SUMMARY.md +++ b/src/doc/src/SUMMARY.md @@ -27,5 +27,6 @@ * [Package ID Specifications](reference/pkgid-spec.md) * [Source Replacement](reference/source-replacement.md) * [External Tools](reference/external-tools.md) + * [Unstable Features](reference/unstable.md) * [FAQ](faq.md) diff --git a/src/doc/src/reference/index.md b/src/doc/src/reference/index.md index 634dd34f8..c4c46b75c 100644 --- a/src/doc/src/reference/index.md +++ b/src/doc/src/reference/index.md @@ -11,3 +11,4 @@ The reference covers the details of various areas of Cargo. * [Package ID Specifications](reference/pkgid-spec.html) * [Source Replacement](reference/source-replacement.html) * [External Tools](reference/external-tools.html) +* [Unstable Features](reference/unstable.html) diff --git a/src/doc/src/reference/unstable.md b/src/doc/src/reference/unstable.md new file mode 100644 index 000000000..a598032eb --- /dev/null +++ b/src/doc/src/reference/unstable.md @@ -0,0 +1,188 @@ +## Unstable Features + +Experimental Cargo features are only available on the nightly channel. You +typically use one of the `-Z` flags to enable them. Run `cargo -Z help` to +see a list of flags available. + +`-Z unstable-options` is a generic flag for enabling other unstable +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/index" } +``` + +Authentication information for alternate registries can be added to +`.cargo/credentials`: + +```toml +[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"] +``` + + +### rename-dependency +* Original Issue: [#1311](https://github.com/rust-lang/cargo/issues/1311) +* PR: [#4953](https://github.com/rust-lang/cargo/pull/4953) + +The rename-dependency feature allows you to import a dependency +with a different name from the source. This can be useful in a few scenarios: + +* Depending on crates with the same name from different registries. +* Depending on multiple versions of a crate. +* Avoid needing `extern crate foo as bar` in Rust source. + +Just include the `package` key to specify the actual name of the dependency. +You must include `cargo-features` at the top of your `Cargo.toml`. + +```toml +cargo-features = ["rename-dependency"] + +[package] +name = "mypackage" +version = "0.0.1" + +[dependencies] +foo = "0.1" +bar = { version = "0.1", registry = "custom", package = "foo" } +baz = { git = "https://github.com/example/project", package = "foo" } +``` + +In this example, three crates are now available in your Rust code: + +```rust +extern crate foo; // crates.io +extern crate bar; // registry `custom` +extern crate baz; // git repository +``` + + +### publish-lockfile +* Original Issue: [#2263](https://github.com/rust-lang/cargo/issues/2263) +* PR: [#5093](https://github.com/rust-lang/cargo/pull/5093) + +When creating a `.crate` file for distribution, Cargo has historically +not included the `Cargo.lock` file. This can cause problems with +using `cargo install` with a binary. You can specify that your package +should include the `Cargo.lock` file when using `cargo package` or `cargo publish` +by specifying the `publish-lockfile` key in `Cargo.toml`. This also requires the +appropriate `cargo-features`: + +```toml +cargo-features = ["publish-lockfile"] + +[project] +... +publish-lockfile = true +``` + + +### Offline Mode +* Original Issue: [#4686](https://github.com/rust-lang/cargo/issues/4686) + +The `-Z offline` flag prevents Cargo from attempting to access the network for +any reason. Typically Cargo will stop with an error if it wants to access the +network and it is not available. + +Beware that this may result in different dependency resolution than online +mode. Cargo will restrict itself to crates that are available locally, even +if there might be a newer version as indicated in the local copy of the index. + +### no-index-update +* Original Issue: [#3479](https://github.com/rust-lang/cargo/issues/3479) + +The `-Z no-index-update` flag ensures that Cargo does not attempt to update +the registry index. This is intended for tools such as Crater that issue many +Cargo commands, and you want to avoid the network latency for updating the +index each time. + +### avoid-dev-deps +* Original Issue: [#4988](https://github.com/rust-lang/cargo/issues/4988) +* Stabilization Issue: [#5133](https://github.com/rust-lang/cargo/issues/5133) + +When running commands such as `cargo install` or `cargo build`, Cargo +currently requires dev-dependencies to be downloaded, even if they are not +used. The `-Z avoid-dev-deps` flag allows Cargo to avoid downloading +dev-dependencies if they are not needed. The `Cargo.lock` file will not be +generated if dev-dependencies are skipped. + +### minimal-versions +* Original Issue: [#4100](https://github.com/rust-lang/cargo/issues/4100) + +When a `Cargo.lock` file is generated, the `-Z minimal-versions` flag will +resolve the dependencies to the minimum semver version that will satisfy the +requirements (instead of the greatest version). + +### out-dir +* Original Issue: [#4875](https://github.com/rust-lang/cargo/issues/4875) + +This feature allows you to specify the directory where artifacts will be +copied to after they are built. Typically artifacts are only written to the +`target/release` or `target/debug` directories. However, determining the +exact filename can be tricky since you need to parse JSON output. The +`--out-dir` flag makes it easier to predictably access the artifacts. Note +that the artifacts are copied, so the originals are still in the `target` +directory. Example: + +``` +cargo +nightly build --out-dir=out -Z out-dir +``` + + +### Edition +* Tracking Issue: [rust-lang/rust#44581](https://github.com/rust-lang/rust/issues/44581) +* RFC: [#2052](https://github.com/rust-lang/rfcs/blob/master/text/2052-epochs.md) + +You can opt in to a specific Rust Edition for your package with the `rust` key +in `Cargo.toml`. If you don't specify the edition, it will default to 2015. +You need to include the appropriate `cargo-features`: + +```toml +cargo-features = ["edition"] + +[package] +... +rust = "2018" +``` -- 2.39.5