fork/cargo

git clone https://git.julia.blue/fork/cargo

borsAuto merge of #14427 - dpaoliello:add, r=epage64c4b6d32

0.91.0
10.9 KiB292 linesraw
1CARGO-ADD(1)
2
3NAME
4       cargo-add — Add dependencies to a Cargo.toml manifest file
5
6SYNOPSIS
7       cargo add [options] crate…
8       cargo add [options] --path path
9       cargo add [options] --git url [crate…]
10
11DESCRIPTION
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       Upon successful invocation, the enabled (+) and disabled (-) features
36       <https://doc.rust-lang.org/cargo/reference/features.html> of the
37       specified dependency will be listed in the command’s output.
38
39OPTIONS
40   Source options
41       --git url
42           Git URL to add the specified crate from
43           <https://doc.rust-lang.org/cargo/reference/specifying-dependencies.html#specifying-dependencies-from-git-repositories>.
44
45       --branch branch
46           Branch to use when adding from git.
47
48       --tag tag
49           Tag to use when adding from git.
50
51       --rev sha
52           Specific commit to use when adding from git.
53
54       --path path
55           Filesystem path
56           <https://doc.rust-lang.org/cargo/reference/specifying-dependencies.html#specifying-path-dependencies>
57           to local crate to add.
58
59       --base base
60           The path base
61           <https://doc.rust-lang.org/cargo/reference/unstable.html#path-bases>
62           to use when adding a local crate.
63
64           Unstable (nightly-only)
65           <https://doc.rust-lang.org/cargo/reference/unstable.html#path-bases>
66
67       --registry registry
68           Name of the registry to use. Registry names are defined in Cargo
69           config files
70           <https://doc.rust-lang.org/cargo/reference/config.html>. If not
71           specified, the default registry is used, which is defined by the
72           registry.default config key which defaults to crates-io.
73
74   Section options
75       --dev
76           Add as a development dependency
77           <https://doc.rust-lang.org/cargo/reference/specifying-dependencies.html#development-dependencies>.
78
79       --build
80           Add as a build dependency
81           <https://doc.rust-lang.org/cargo/reference/specifying-dependencies.html#build-dependencies>.
82
83       --target target
84           Add as a dependency to the given target platform
85           <https://doc.rust-lang.org/cargo/reference/specifying-dependencies.html#platform-specific-dependencies>.
86
87           To avoid unexpected shell expansions, you may use quotes around each
88           target, e.g., --target 'cfg(unix)'.
89
90   Dependency options
91       --dry-run
92           Don’t actually write the manifest
93
94       --rename name
95           Rename
96           <https://doc.rust-lang.org/cargo/reference/specifying-dependencies.html#renaming-dependencies-in-cargotoml>
97           the dependency.
98
99       --optional
100           Mark the dependency as optional
101           <https://doc.rust-lang.org/cargo/reference/features.html#optional-dependencies>.
102
103       --no-optional
104           Mark the dependency as required
105           <https://doc.rust-lang.org/cargo/reference/features.html#optional-dependencies>.
106
107       --public
108           Mark the dependency as public.
109
110           The dependency can be referenced in your library’s public API.
111
112           Unstable (nightly-only)
113           <https://doc.rust-lang.org/cargo/reference/unstable.html#public-dependency>
114
115       --no-public
116           Mark the dependency as private.
117
118           While you can use the crate in your implementation, it cannot be
119           referenced in your public API.
120
121           Unstable (nightly-only)
122           <https://doc.rust-lang.org/cargo/reference/unstable.html#public-dependency>
123
124       --no-default-features
125           Disable the default features
126           <https://doc.rust-lang.org/cargo/reference/features.html#dependency-features>.
127
128       --default-features
129           Re-enable the default features
130           <https://doc.rust-lang.org/cargo/reference/features.html#dependency-features>.
131
132       -F features, --features features
133           Space or comma separated list of features to activate
134           <https://doc.rust-lang.org/cargo/reference/features.html#dependency-features>.
135           When adding multiple crates, the features for a specific crate may
136           be enabled with package-name/feature-name syntax. This flag may be
137           specified multiple times, which enables all specified features.
138
139   Display Options
140       -v, --verbose
141           Use verbose output. May be specified twice for “very verbose”
142           output which includes extra output such as dependency warnings and
143           build script output. May also be specified with the term.verbose
144           config value
145           <https://doc.rust-lang.org/cargo/reference/config.html>.
146
147       -q, --quiet
148           Do not print cargo log messages. May also be specified with the
149           term.quiet config value
150           <https://doc.rust-lang.org/cargo/reference/config.html>.
151
152       --color when
153           Control when colored output is used. Valid values:
154
155           o  auto (default): Automatically detect if color support is
156              available on the terminal.
157
158           o  always: Always display colors.
159
160           o  never: Never display colors.
161
162           May also be specified with the term.color config value
163           <https://doc.rust-lang.org/cargo/reference/config.html>.
164
165   Manifest Options
166       --manifest-path path
167           Path to the Cargo.toml file. By default, Cargo searches for the
168           Cargo.toml file in the current directory or any parent directory.
169
170       -p spec, --package spec
171           Add dependencies to only the specified package.
172
173       --ignore-rust-version
174           Ignore rust-version specification in packages.
175
176       --locked
177           Asserts that the exact same dependencies and versions are used as
178           when the existing Cargo.lock file was originally generated. Cargo
179           will exit with an error when either of the following scenarios
180           arises:
181
182           o  The lock file is missing.
183
184           o  Cargo attempted to change the lock file due to a different
185              dependency resolution.
186
187           It may be used in environments where deterministic builds are
188           desired, such as in CI pipelines.
189
190       --offline
191           Prevents Cargo from accessing the network for any reason. Without
192           this flag, Cargo will stop with an error if it needs to access the
193           network and the network is not available. With this flag, Cargo will
194           attempt to proceed without the network if possible.
195
196           Beware that this may result in different dependency resolution than
197           online mode. Cargo will restrict itself to crates that are
198           downloaded locally, even if there might be a newer version as
199           indicated in the local copy of the index. See the cargo-fetch(1)
200           command to download dependencies before going offline.
201
202           May also be specified with the net.offline config value
203           <https://doc.rust-lang.org/cargo/reference/config.html>.
204
205       --frozen
206           Equivalent to specifying both --locked and --offline.
207
208       --lockfile-path PATH
209           Changes the path of the lockfile from the default
210           (<workspace_root>/Cargo.lock) to PATH. PATH must end with Cargo.lock
211           (e.g. --lockfile-path /tmp/temporary-lockfile/Cargo.lock). Note that
212           providing --lockfile-path will ignore existing lockfile at the
213           default path, and instead will either use the lockfile from PATH, or
214           write a new lockfile into the provided PATH if it doesn’t exist.
215           This flag can be used to run most commands in read-only directories,
216           writing lockfile into the provided PATH.
217
218           This option is only available on the nightly channel
219           <https://doc.rust-lang.org/book/appendix-07-nightly-rust.html> and
220           requires the -Z unstable-options flag to enable (see #14421
221           <https://github.com/rust-lang/cargo/issues/14421>).
222
223   Common Options
224       +toolchain
225           If Cargo has been installed with rustup, and the first argument to
226           cargo begins with +, it will be interpreted as a rustup toolchain
227           name (such as +stable or +nightly). See the rustup documentation
228           <https://rust-lang.github.io/rustup/overrides.html> for more
229           information about how toolchain overrides work.
230
231       --config KEY=VALUE or PATH
232           Overrides a Cargo configuration value. The argument should be in
233           TOML syntax of KEY=VALUE, or provided as a path to an extra
234           configuration file. This flag may be specified multiple times. See
235           the command-line overrides section
236           <https://doc.rust-lang.org/cargo/reference/config.html#command-line-overrides>
237           for more information.
238
239       -C PATH
240           Changes the current working directory before executing any specified
241           operations. This affects things like where cargo looks by default
242           for the project manifest (Cargo.toml), as well as the directories
243           searched for discovering .cargo/config.toml, for example. This
244           option must appear before the command name, for example cargo -C
245           path/to/my-project build.
246
247           This option is only available on the nightly channel
248           <https://doc.rust-lang.org/book/appendix-07-nightly-rust.html> and
249           requires the -Z unstable-options flag to enable (see #10098
250           <https://github.com/rust-lang/cargo/issues/10098>).
251
252       -h, --help
253           Prints help information.
254
255       -Z flag
256           Unstable (nightly-only) flags to Cargo. Run cargo -Z help for
257           details.
258
259ENVIRONMENT
260       See the reference
261       <https://doc.rust-lang.org/cargo/reference/environment-variables.html>
262       for details on environment variables that Cargo reads.
263
264EXIT STATUS
265       o  0: Cargo succeeded.
266
267       o  101: Cargo failed to complete.
268
269EXAMPLES
270       1. Add regex as a dependency
271
272              cargo add regex
273
274       2. Add trybuild as a dev-dependency
275
276              cargo add --dev trybuild
277
278       3. Add an older version of nom as a dependency
279
280              cargo add nom@5
281
282       4. Add support for serializing data structures to json with derives
283
284              cargo add serde serde_json -F serde/derive
285
286       5. Add windows as a platform specific dependency on cfg(windows)
287
288              cargo add windows --target 'cfg(windows)'
289
290SEE ALSO
291       cargo(1), cargo-remove(1)
292