Skip to content

Commit edffc4a

Browse files
borsbors
committed
Auto merge of #10578 - epage:add-docs, r=ehuss
Document cargo-add ### What does this PR try to resolve? cargo-add's PR was minimal to ensure we had settled on the CLI before adding references to the CLI and have cascading churn. This the command documentation and adds references to that command. ### How should we test and review this PR? I'm unsure what testing is not automated for the documentation (like link checking). ### Additional information To keep the PRs focused, I am submitting completions separate from documentation updates so one does not get blocked on the other and its easier to see all relevant parts and sign off on them.
2 parents 46c7a2b + f0ede38 commit edffc4a

File tree

7 files changed

+817
-0
lines changed

7 files changed

+817
-0
lines changed

‎src/bin/cargo/cli.rs

+1
Original file line numberDiff line numberDiff line change
@@ -438,6 +438,7 @@ Some common cargo commands are (see all commands with --list):
438438
doc, d Build this package's and its dependencies' documentation
439439
new Create a new cargo package
440440
init Create a new cargo package in an existing directory
441+
add Add dependencies to a manifest file
441442
run, r Run a binary or example of the local package
442443
test, t Run the tests
443444
bench Run the benchmarks

‎src/doc/man/cargo-add.md

+157
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,157 @@
1+
# cargo-add(1)
2+
{{*set actionverb="Add"}}
3+
{{*set nouns="adds"}}
4+
5+
## NAME
6+
7+
cargo-add - Add dependencies to a Cargo.toml manifest file
8+
9+
## SYNOPSIS
10+
11+
`cargo add` [_options_] _crate_...\
12+
`cargo add` [_options_] `--path` _path_\
13+
`cargo add` [_options_] `--git` _url_ [_crate_...]\
14+
15+
16+
## DESCRIPTION
17+
18+
This command can add or modify dependencies.
19+
20+
The source for the dependency can be specified with:
21+
22+
* _crate_`@`_version_: Fetch from a registry with a version constraint of "_version_"
23+
* `--path` _path_: Fetch from the specified _path_
24+
* `--git` _url_: Pull from a git repo at _url_
25+
26+
If no source is specified, then a best effort will be made to select one, including:
27+
28+
* Existing dependencies in other tables (like `dev-dependencies`)
29+
* Workspace members
30+
* Latest release in the registry
31+
32+
When you add a package that is already present, the existing entry will be updated with the flags specified.
33+
34+
## OPTIONS
35+
36+
### Source options
37+
38+
{{#options}}
39+
40+
{{#option "`--git` _url_" }}
41+
[Git URL to add the specified crate from](../reference/specifying-dependencies.html#specifying-dependencies-from-git-repositories).
42+
{{/option}}
43+
44+
{{#option "`--branch` _branch_" }}
45+
Branch to use when adding from git.
46+
{{/option}}
47+
48+
{{#option "`--tag` _tag_" }}
49+
Tag to use when adding from git.
50+
{{/option}}
51+
52+
{{#option "`--rev` _sha_" }}
53+
Specific commit to use when adding from git.
54+
{{/option}}
55+
56+
{{#option "`--path` _path_" }}
57+
[Filesystem path](../reference/specifying-dependencies.html#specifying-path-dependencies) to local crate to add.
58+
{{/option}}
59+
60+
{{> options-registry }}
61+
62+
{{/options}}
63+
64+
### Section options
65+
66+
{{#options}}
67+
68+
{{#option "`--dev`" }}
69+
Add as a [development dependency](../reference/specifying-dependencies.html#development-dependencies).
70+
{{/option}}
71+
72+
{{#option "`--build`" }}
73+
Add as a [build dependency](../reference/specifying-dependencies.html#build-dependencies).
74+
{{/option}}
75+
76+
{{#option "`--target` _target_" }}
77+
Add as a dependency to the [given target platform](../reference/specifying-dependencies.html#platform-specific-dependencies).
78+
{{/option}}
79+
80+
{{/options}}
81+
82+
83+
</dl>
84+
85+
### Dependency options
86+
87+
{{#options}}
88+
89+
{{#option "`--rename` _name_" }}
90+
[Rename](../reference/specifying-dependencies.html#renaming-dependencies-in-cargotoml) the dependency.
91+
{{/option}}
92+
93+
{{#option "`--optional`" }}
94+
Mark the dependency as [optional](../reference/features.html#optional-dependencies).
95+
{{/option}}
96+
97+
{{#option "`--no-optional`" }}
98+
Mark the dependency as [required](../reference/features.html#optional-dependencies).
99+
{{/option}}
100+
101+
{{#option "`--no-default-features`" }}
102+
Disable the [default features](../reference/features.html#dependency-features).
103+
{{/option}}
104+
105+
{{#option "`--default-features`" }}
106+
Re-enable the [default features](../reference/features.html#dependency-features).
107+
{{/option}}
108+
109+
{{#option "`--features` _features_" }}
110+
Space or comma separated list of [features to
111+
activate](../reference/features.html#dependency-features). When adding multiple
112+
crates, the features for a specific crate may be enabled with
113+
`package-name/feature-name` syntax. This flag may be specified multiple times,
114+
which enables all specified features.
115+
{{/option}}
116+
117+
{{/options}}
118+
119+
120+
### Display Options
121+
122+
{{#options}}
123+
{{> options-display }}
124+
{{/options}}
125+
126+
### Manifest Options
127+
128+
{{#options}}
129+
{{> options-manifest-path }}
130+
{{/options}}
131+
132+
{{> section-options-common }}
133+
134+
{{> section-environment }}
135+
136+
{{> section-exit-status }}
137+
138+
## EXAMPLES
139+
140+
1. Add `regex` as a dependency
141+
142+
cargo add regex
143+
144+
2. Add `trybuild` as a dev-dependency
145+
146+
cargo add --dev trybuild
147+
148+
3. Add an older version of `nom` as a dependency
149+
150+
cargo add nom@5
151+
152+
4. Add support for serializing data structures to json with `derive`s
153+
154+
cargo add serde serde_json -F serde/derive
155+
156+
## SEE ALSO
157+
{{man "cargo" 1}}

‎src/doc/man/generated_txt/cargo-add.txt

+180
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,180 @@
1+
CARGO-ADD(1)
2+
3+
NAME
4+
cargo-add - Add dependencies to a Cargo.toml manifest file
5+
6+
SYNOPSIS
7+
cargo add [options] crate...
8+
cargo add [options] --path path
9+
cargo add [options] --git url [crate...]
10+
11+
DESCRIPTION
12+
This command can add or modify dependencies.
13+
14+
The source for the dependency can be specified with:
15+
16+
o crate@version: Fetch from a registry with a version constraint of
17+
"version"
18+
19+
o --path path: Fetch from the specified path
20+
21+
o --git url: Pull from a git repo at url
22+
23+
If no source is specified, then a best effort will be made to select
24+
one, including:
25+
26+
o Existing dependencies in other tables (like dev-dependencies)
27+
28+
o Workspace members
29+
30+
o Latest release in the registry
31+
32+
When you add a package that is already present, the existing entry will
33+
be updated with the flags specified.
34+
35+
OPTIONS
36+
Source options
37+
--git url
38+
Git URL to add the specified crate from
39+
<https://doc.rust-lang.org/cargo/reference/specifying-dependencies.html#specifying-dependencies-from-git-repositories>.
40+
41+
--branch branch
42+
Branch to use when adding from git.
43+
44+
--tag tag
45+
Tag to use when adding from git.
46+
47+
--rev sha
48+
Specific commit to use when adding from git.
49+
50+
--path path
51+
Filesystem path
52+
<https://doc.rust-lang.org/cargo/reference/specifying-dependencies.html#specifying-path-dependencies>
53+
to local crate to add.
54+
55+
--registry registry
56+
Name of the registry to use. Registry names are defined in Cargo
57+
config files
58+
<https://doc.rust-lang.org/cargo/reference/config.html>. If not
59+
specified, the default registry is used, which is defined by the
60+
registry.default config key which defaults to crates-io.
61+
62+
Section options
63+
--dev
64+
Add as a development dependency
65+
<https://doc.rust-lang.org/cargo/reference/specifying-dependencies.html#development-dependencies>.
66+
67+
--build
68+
Add as a build dependency
69+
<https://doc.rust-lang.org/cargo/reference/specifying-dependencies.html#build-dependencies>.
70+
71+
--target target
72+
Add as a dependency to the given target platform
73+
<https://doc.rust-lang.org/cargo/reference/specifying-dependencies.html#platform-specific-dependencies>.
74+
75+
</dl>
76+
77+
Dependency options
78+
--rename name
79+
Rename
80+
<https://doc.rust-lang.org/cargo/reference/specifying-dependencies.html#renaming-dependencies-in-cargotoml>
81+
the dependency.
82+
83+
--optional
84+
Mark the dependency as optional
85+
<https://doc.rust-lang.org/cargo/reference/features.html#optional-dependencies>.
86+
87+
--no-optional
88+
Mark the dependency as required
89+
<https://doc.rust-lang.org/cargo/reference/features.html#optional-dependencies>.
90+
91+
--no-default-features
92+
Disable the default features
93+
<https://doc.rust-lang.org/cargo/reference/features.html#dependency-features>.
94+
95+
--default-features
96+
Re-enable the default features
97+
<https://doc.rust-lang.org/cargo/reference/features.html#dependency-features>.
98+
99+
--features features
100+
Space or comma separated list of features to activate
101+
<https://doc.rust-lang.org/cargo/reference/features.html#dependency-features>.
102+
When adding multiple crates, the features for a specific crate may
103+
be enabled with package-name/feature-name syntax. This flag may be
104+
specified multiple times, which enables all specified features.
105+
106+
Display Options
107+
-v, --verbose
108+
Use verbose output. May be specified twice for "very verbose" output
109+
which includes extra output such as dependency warnings and build
110+
script output. May also be specified with the term.verbose config
111+
value <https://doc.rust-lang.org/cargo/reference/config.html>.
112+
113+
-q, --quiet
114+
Do not print cargo log messages. May also be specified with the
115+
term.quiet config value
116+
<https://doc.rust-lang.org/cargo/reference/config.html>.
117+
118+
--color when
119+
Control when colored output is used. Valid values:
120+
121+
o auto (default): Automatically detect if color support is
122+
available on the terminal.
123+
124+
o always: Always display colors.
125+
126+
o never: Never display colors.
127+
128+
May also be specified with the term.color config value
129+
<https://doc.rust-lang.org/cargo/reference/config.html>.
130+
131+
Manifest Options
132+
--manifest-path path
133+
Path to the Cargo.toml file. By default, Cargo searches for the
134+
Cargo.toml file in the current directory or any parent directory.
135+
136+
Common Options
137+
+toolchain
138+
If Cargo has been installed with rustup, and the first argument to
139+
cargo begins with +, it will be interpreted as a rustup toolchain
140+
name (such as +stable or +nightly). See the rustup documentation
141+
<https://rust-lang.github.io/rustup/overrides.html> for more
142+
information about how toolchain overrides work.
143+
144+
-h, --help
145+
Prints help information.
146+
147+
-Z flag
148+
Unstable (nightly-only) flags to Cargo. Run cargo -Z help for
149+
details.
150+
151+
ENVIRONMENT
152+
See the reference
153+
<https://doc.rust-lang.org/cargo/reference/environment-variables.html>
154+
for details on environment variables that Cargo reads.
155+
156+
EXIT STATUS
157+
o 0: Cargo succeeded.
158+
159+
o 101: Cargo failed to complete.
160+
161+
EXAMPLES
162+
1. Add regex as a dependency
163+
164+
cargo add regex
165+
166+
2. Add trybuild as a dev-dependency
167+
168+
cargo add --dev trybuild
169+
170+
3. Add an older version of nom as a dependency
171+
172+
cargo add nom@5
173+
174+
4. Add support for serializing data structures to json with derives
175+
176+
cargo add serde serde_json -F serde/derive
177+
178+
SEE ALSO
179+
cargo(1)
180+

‎src/doc/src/SUMMARY.md

+1
Original file line numberDiff line numberDiff line change
@@ -61,6 +61,7 @@
6161
* [cargo test](commands/cargo-test.md)
6262
* [cargo report](commands/cargo-report.md)
6363
* [Manifest Commands](commands/manifest-commands.md)
64+
* [cargo add](commands/cargo-add.md)
6465
* [cargo generate-lockfile](commands/cargo-generate-lockfile.md)
6566
* [cargo locate-project](commands/cargo-locate-project.md)
6667
* [cargo metadata](commands/cargo-metadata.md)

0 commit comments

Comments
 (0)