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).

diff --git a/src/cargo/core/features.rs b/src/cargo/core/features.rs
index 09eff85455c4c6389a3269a888dc3736f5d29ed3..c9658a8aaedf2d5e8e8923b4d38278dedc72e807 100644 (file)
--- 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 f75ac510e32c87f7709cbc9dbc674525bee1f880..5330684daaa809b0599d6b343589d1e372d6495e 100644 (file)
--- 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 634dd34f8cef19b64767b7da2694fb81ca0fa7af..c4c46b75c31d83cb7e6735ad8bcec592cc0a9227 100644 (file)
--- 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 (file)
index 0000000..a598032
--- /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"
+```