Skip to content

Commit 0d49d57

Browse files
borsbors
committed
Auto merge of #5318 - ehuss:unstable-docs, r=matklad
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).
2 parents 8aa2794 + 3fb97d6 commit 0d49d57

File tree

4 files changed

+202
-0
lines changed

4 files changed

+202
-0
lines changed

‎src/cargo/core/features.rs

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -35,6 +35,12 @@
3535
//! then you use `chain_err` to tack on more context for why the feature was
3636
//! required when the feature isn't activated.
3737
//!
38+
//! 4. Update the unstable documentation at
39+
//! `src/doc/src/reference/unstable.md` to include a short description of
40+
//! how to use your new feature. When the feature is stabilized, be sure
41+
//! that the Cargo Guide or Reference is updated to fully document the
42+
//! feature and remove the entry from the Unstable section.
43+
//!
3844
//! And hopefully that's it! Bear with us though that this is, at the time of
3945
//! this writing, a very new feature in Cargo. If the process differs from this
4046
//! we'll be sure to update this documentation!

‎src/doc/src/SUMMARY.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -27,5 +27,6 @@
2727
* [Package ID Specifications](reference/pkgid-spec.md)
2828
* [Source Replacement](reference/source-replacement.md)
2929
* [External Tools](reference/external-tools.md)
30+
* [Unstable Features](reference/unstable.md)
3031

3132
* [FAQ](faq.md)

‎src/doc/src/reference/index.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,3 +11,4 @@ The reference covers the details of various areas of Cargo.
1111
* [Package ID Specifications](reference/pkgid-spec.html)
1212
* [Source Replacement](reference/source-replacement.html)
1313
* [External Tools](reference/external-tools.html)
14+
* [Unstable Features](reference/unstable.html)

‎src/doc/src/reference/unstable.md

Lines changed: 194 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,194 @@
1+
## Unstable Features
2+
3+
Experimental Cargo features are only available on the nightly channel. You
4+
typically use one of the `-Z` flags to enable them. Run `cargo -Z help` to
5+
see a list of flags available.
6+
7+
`-Z unstable-options` is a generic flag for enabling other unstable
8+
command-line flags. Options requiring this will be called out below.
9+
10+
Some unstable features will require you to specify the `cargo-features` key in
11+
`Cargo.toml`.
12+
13+
### Alternate Registries
14+
* RFC: [#2141](https://github.com/rust-lang/rfcs/blob/master/text/2141-alternative-registries.md)
15+
* Tracking Issue: [rust-lang/rust#44931](https://github.com/rust-lang/rust/issues/44931)
16+
17+
Alternate registries allow you to use registries other than crates.io.
18+
19+
The name of a registry is defined in `.cargo/config` under the `registries`
20+
table:
21+
22+
```toml
23+
[registries]
24+
my-registry = { index = "https://my-intranet:8080/index" }
25+
```
26+
27+
Authentication information for alternate registries can be added to
28+
`.cargo/credentials`:
29+
30+
```toml
31+
[my-registry]
32+
token = "api-token"
33+
```
34+
35+
Inside `Cargo.toml` you can specify which registry a dependency comes from
36+
using the `registry` key. First you need to include the appropriate
37+
`cargo-features` at the top of the file:
38+
39+
```toml
40+
cargo-features = ["alternative-registries"]
41+
42+
[package]
43+
...
44+
45+
[dependencies]
46+
other-create = { version = "1.0", registry = "my-registry"}
47+
```
48+
49+
A `--registry` flag has been added to commands that interact with registries
50+
such as `publish`, `login`, etc. Example:
51+
52+
```
53+
cargo +nightly publish -Z unstable-options --registry my-registry
54+
```
55+
56+
The `publish` field in `Cargo.toml` has been extended to accept a list of
57+
registries that will restrict publishing only to those registries.
58+
59+
```toml
60+
[package]
61+
...
62+
publish = ["my-registry"]
63+
```
64+
65+
66+
### rename-dependency
67+
* Original Issue: [#1311](https://github.com/rust-lang/cargo/issues/1311)
68+
* PR: [#4953](https://github.com/rust-lang/cargo/pull/4953)
69+
70+
The rename-dependency feature allows you to import a dependency
71+
with a different name from the source. This can be useful in a few scenarios:
72+
73+
* Depending on crates with the same name from different registries.
74+
* Depending on multiple versions of a crate.
75+
* Avoid needing `extern crate foo as bar` in Rust source.
76+
77+
Just include the `package` key to specify the actual name of the dependency.
78+
You must include `cargo-features` at the top of your `Cargo.toml`.
79+
80+
```toml
81+
cargo-features = ["rename-dependency"]
82+
83+
[package]
84+
name = "mypackage"
85+
version = "0.0.1"
86+
87+
[dependencies]
88+
foo = "0.1"
89+
bar = { version = "0.1", registry = "custom", package = "foo" }
90+
baz = { git = "https://github.com/example/project", package = "foo" }
91+
```
92+
93+
In this example, three crates are now available in your Rust code:
94+
95+
```rust
96+
extern crate foo; // crates.io
97+
extern crate bar; // registry `custom`
98+
extern crate baz; // git repository
99+
```
100+
101+
102+
### publish-lockfile
103+
* Original Issue: [#2263](https://github.com/rust-lang/cargo/issues/2263)
104+
* PR: [#5093](https://github.com/rust-lang/cargo/pull/5093)
105+
106+
When creating a `.crate` file for distribution, Cargo has historically
107+
not included the `Cargo.lock` file. This can cause problems with
108+
using `cargo install` with a binary. You can specify that your package
109+
should include the `Cargo.lock` file when using `cargo package` or `cargo publish`
110+
by specifying the `publish-lockfile` key in `Cargo.toml`. This also requires the
111+
appropriate `cargo-features`:
112+
113+
```toml
114+
cargo-features = ["publish-lockfile"]
115+
116+
[project]
117+
...
118+
publish-lockfile = true
119+
```
120+
121+
122+
### Offline Mode
123+
* Original Issue: [#4686](https://github.com/rust-lang/cargo/issues/4686)
124+
125+
The `-Z offline` flag prevents Cargo from attempting to access the network for
126+
any reason. Typically Cargo will stop with an error if it wants to access the
127+
network and it is not available.
128+
129+
Beware that this may result in different dependency resolution than online
130+
mode. Cargo will restrict itself to crates that are available locally, even
131+
if there might be a newer version as indicated in the local copy of the index.
132+
133+
### no-index-update
134+
* Original Issue: [#3479](https://github.com/rust-lang/cargo/issues/3479)
135+
136+
The `-Z no-index-update` flag ensures that Cargo does not attempt to update
137+
the registry index. This is intended for tools such as Crater that issue many
138+
Cargo commands, and you want to avoid the network latency for updating the
139+
index each time.
140+
141+
### avoid-dev-deps
142+
* Original Issue: [#4988](https://github.com/rust-lang/cargo/issues/4988)
143+
* Stabilization Issue: [#5133](https://github.com/rust-lang/cargo/issues/5133)
144+
145+
When running commands such as `cargo install` or `cargo build`, Cargo
146+
currently requires dev-dependencies to be downloaded, even if they are not
147+
used. The `-Z avoid-dev-deps` flag allows Cargo to avoid downloading
148+
dev-dependencies if they are not needed. The `Cargo.lock` file will not be
149+
generated if dev-dependencies are skipped.
150+
151+
### minimal-versions
152+
* Original Issue: [#4100](https://github.com/rust-lang/cargo/issues/4100)
153+
154+
When a `Cargo.lock` file is generated, the `-Z minimal-versions` flag will
155+
resolve the dependencies to the minimum semver version that will satisfy the
156+
requirements (instead of the greatest version).
157+
158+
The intended use-case of this flag is to check, during continuous integration,
159+
that the versions specified in Cargo.toml are a correct reflection of the
160+
minimum versions that you are actually using. That is, if Cargo.toml says
161+
`foo = "1.0.0"` that you don't accidentally depend on features added only in
162+
`foo 1.5.0`.
163+
164+
### out-dir
165+
* Original Issue: [#4875](https://github.com/rust-lang/cargo/issues/4875)
166+
167+
This feature allows you to specify the directory where artifacts will be
168+
copied to after they are built. Typically artifacts are only written to the
169+
`target/release` or `target/debug` directories. However, determining the
170+
exact filename can be tricky since you need to parse JSON output. The
171+
`--out-dir` flag makes it easier to predictably access the artifacts. Note
172+
that the artifacts are copied, so the originals are still in the `target`
173+
directory. Example:
174+
175+
```
176+
cargo +nightly build --out-dir=out -Z unstable-options
177+
```
178+
179+
180+
### Edition
181+
* Tracking Issue: [rust-lang/rust#44581](https://github.com/rust-lang/rust/issues/44581)
182+
* RFC: [#2052](https://github.com/rust-lang/rfcs/blob/master/text/2052-epochs.md)
183+
184+
You can opt in to a specific Rust Edition for your package with the `rust` key
185+
in `Cargo.toml`. If you don't specify the edition, it will default to 2015.
186+
You need to include the appropriate `cargo-features`:
187+
188+
```toml
189+
cargo-features = ["edition"]
190+
191+
[package]
192+
...
193+
rust = "2018"
194+
```

0 commit comments

Comments
 (0)