fork/cargo

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

borsAuto merge of #14620 - epage:guideless, r=weihanglo0473ee8b8

0.90.0
12.8 KiB303 linesraw
1CARGO-RUN(1)
2
3NAME
4       cargo-run — Run the current package
5
6SYNOPSIS
7       cargo run [options] [-- args]
8
9DESCRIPTION
10       Run a binary or example of the local package.
11
12       All the arguments following the two dashes (--) are passed to the binary
13       to run. If you’re passing arguments to both Cargo and the binary, the
14       ones after -- go to the binary, the ones before go to Cargo.
15
16       Unlike cargo-test(1) and cargo-bench(1), cargo run sets the working
17       directory of the binary executed to the current working directory, same
18       as if it was executed in the shell directly.
19
20OPTIONS
21   Package Selection
22       By default, the package in the current working directory is selected.
23       The -p flag can be used to choose a different package in a workspace.
24
25       -p spec, --package spec
26           The package to run. See cargo-pkgid(1) for the SPEC format.
27
28   Target Selection
29       When no target selection options are given, cargo run will run the
30       binary target. If there are multiple binary targets, you must pass a
31       target flag to choose one. Or, the default-run field may be specified in
32       the [package] section of Cargo.toml to choose the name of the binary to
33       run by default.
34
35       --bin name
36           Run the specified binary.
37
38       --example name
39           Run the specified example.
40
41   Feature Selection
42       The feature flags allow you to control which features are enabled. When
43       no feature options are given, the default feature is activated for every
44       selected package.
45
46       See the features documentation
47       <https://doc.rust-lang.org/cargo/reference/features.html#command-line-feature-options>
48       for more details.
49
50       -F features, --features features
51           Space or comma separated list of features to activate. Features of
52           workspace members may be enabled with package-name/feature-name
53           syntax. This flag may be specified multiple times, which enables all
54           specified features.
55
56       --all-features
57           Activate all available features of all selected packages.
58
59       --no-default-features
60           Do not activate the default feature of the selected packages.
61
62   Compilation Options
63       --target triple
64           Run for the given architecture. The default is the host
65           architecture. The general format of the triple is
66           <arch><sub>-<vendor>-<sys>-<abi>. Run rustc --print target-list for
67           a list of supported targets.
68
69           This may also be specified with the build.target config value
70           <https://doc.rust-lang.org/cargo/reference/config.html>.
71
72           Note that specifying this flag makes Cargo run in a different mode
73           where the target artifacts are placed in a separate directory. See
74           the build cache
75           <https://doc.rust-lang.org/cargo/reference/build-cache.html>
76           documentation for more details.
77
78       -r, --release
79           Run optimized artifacts with the release profile. See also the
80           --profile option for choosing a specific profile by name.
81
82       --profile name
83           Run with the given profile. See the reference
84           <https://doc.rust-lang.org/cargo/reference/profiles.html> for more
85           details on profiles.
86
87       --timings=fmts
88           Output information how long each compilation takes, and track
89           concurrency information over time. Accepts an optional
90           comma-separated list of output formats; --timings without an
91           argument will default to --timings=html. Specifying an output format
92           (rather than the default) is unstable and requires
93           -Zunstable-options. Valid output formats:
94
95           o  html (unstable, requires -Zunstable-options): Write a
96              human-readable file cargo-timing.html to the target/cargo-timings
97              directory with a report of the compilation. Also write a report
98              to the same directory with a timestamp in the filename if you
99              want to look at older runs. HTML output is suitable for human
100              consumption only, and does not provide machine-readable timing
101              data.
102
103           o  json (unstable, requires -Zunstable-options): Emit
104              machine-readable JSON information about timing information.
105
106   Output Options
107       --target-dir directory
108           Directory for all generated artifacts and intermediate files. May
109           also be specified with the CARGO_TARGET_DIR environment variable, or
110           the build.target-dir config value
111           <https://doc.rust-lang.org/cargo/reference/config.html>. Defaults to
112           target in the root of the workspace.
113
114   Display Options
115       -v, --verbose
116           Use verbose output. May be specified twice for “very verbose”
117           output which includes extra output such as dependency warnings and
118           build script output. May also be specified with the term.verbose
119           config value
120           <https://doc.rust-lang.org/cargo/reference/config.html>.
121
122       -q, --quiet
123           Do not print cargo log messages. May also be specified with the
124           term.quiet config value
125           <https://doc.rust-lang.org/cargo/reference/config.html>.
126
127       --color when
128           Control when colored output is used. Valid values:
129
130           o  auto (default): Automatically detect if color support is
131              available on the terminal.
132
133           o  always: Always display colors.
134
135           o  never: Never display colors.
136
137           May also be specified with the term.color config value
138           <https://doc.rust-lang.org/cargo/reference/config.html>.
139
140       --message-format fmt
141           The output format for diagnostic messages. Can be specified multiple
142           times and consists of comma-separated values. Valid values:
143
144           o  human (default): Display in a human-readable text format.
145              Conflicts with short and json.
146
147           o  short: Emit shorter, human-readable text messages. Conflicts with
148              human and json.
149
150           o  json: Emit JSON messages to stdout. See the reference
151              <https://doc.rust-lang.org/cargo/reference/external-tools.html#json-messages>
152              for more details. Conflicts with human and short.
153
154           o  json-diagnostic-short: Ensure the rendered field of JSON messages
155              contains the “short” rendering from rustc. Cannot be used
156              with human or short.
157
158           o  json-diagnostic-rendered-ansi: Ensure the rendered field of JSON
159              messages contains embedded ANSI color codes for respecting
160              rustc’s default color scheme. Cannot be used with human or
161              short.
162
163           o  json-render-diagnostics: Instruct Cargo to not include rustc
164              diagnostics in JSON messages printed, but instead Cargo itself
165              should render the JSON diagnostics coming from rustc. Cargo’s
166              own JSON diagnostics and others coming from rustc are still
167              emitted. Cannot be used with human or short.
168
169   Manifest Options
170       --manifest-path path
171           Path to the Cargo.toml file. By default, Cargo searches for the
172           Cargo.toml file in the current directory or any parent directory.
173
174       --ignore-rust-version
175           Ignore rust-version specification in packages.
176
177       --locked
178           Asserts that the exact same dependencies and versions are used as
179           when the existing Cargo.lock file was originally generated. Cargo
180           will exit with an error when either of the following scenarios
181           arises:
182
183           o  The lock file is missing.
184
185           o  Cargo attempted to change the lock file due to a different
186              dependency resolution.
187
188           It may be used in environments where deterministic builds are
189           desired, such as in CI pipelines.
190
191       --offline
192           Prevents Cargo from accessing the network for any reason. Without
193           this flag, Cargo will stop with an error if it needs to access the
194           network and the network is not available. With this flag, Cargo will
195           attempt to proceed without the network if possible.
196
197           Beware that this may result in different dependency resolution than
198           online mode. Cargo will restrict itself to crates that are
199           downloaded locally, even if there might be a newer version as
200           indicated in the local copy of the index. See the cargo-fetch(1)
201           command to download dependencies before going offline.
202
203           May also be specified with the net.offline config value
204           <https://doc.rust-lang.org/cargo/reference/config.html>.
205
206       --frozen
207           Equivalent to specifying both --locked and --offline.
208
209       --lockfile-path PATH
210           Changes the path of the lockfile from the default
211           (<workspace_root>/Cargo.lock) to PATH. PATH must end with Cargo.lock
212           (e.g. --lockfile-path /tmp/temporary-lockfile/Cargo.lock). Note that
213           providing --lockfile-path will ignore existing lockfile at the
214           default path, and instead will either use the lockfile from PATH, or
215           write a new lockfile into the provided PATH if it doesn’t exist.
216           This flag can be used to run most commands in read-only directories,
217           writing lockfile into the provided PATH.
218
219           This option is only available on the nightly channel
220           <https://doc.rust-lang.org/book/appendix-07-nightly-rust.html> and
221           requires the -Z unstable-options flag to enable (see #14421
222           <https://github.com/rust-lang/cargo/issues/14421>).
223
224   Common Options
225       +toolchain
226           If Cargo has been installed with rustup, and the first argument to
227           cargo begins with +, it will be interpreted as a rustup toolchain
228           name (such as +stable or +nightly). See the rustup documentation
229           <https://rust-lang.github.io/rustup/overrides.html> for more
230           information about how toolchain overrides work.
231
232       --config KEY=VALUE or PATH
233           Overrides a Cargo configuration value. The argument should be in
234           TOML syntax of KEY=VALUE, or provided as a path to an extra
235           configuration file. This flag may be specified multiple times. See
236           the command-line overrides section
237           <https://doc.rust-lang.org/cargo/reference/config.html#command-line-overrides>
238           for more information.
239
240       -C PATH
241           Changes the current working directory before executing any specified
242           operations. This affects things like where cargo looks by default
243           for the project manifest (Cargo.toml), as well as the directories
244           searched for discovering .cargo/config.toml, for example. This
245           option must appear before the command name, for example cargo -C
246           path/to/my-project build.
247
248           This option is only available on the nightly channel
249           <https://doc.rust-lang.org/book/appendix-07-nightly-rust.html> and
250           requires the -Z unstable-options flag to enable (see #10098
251           <https://github.com/rust-lang/cargo/issues/10098>).
252
253       -h, --help
254           Prints help information.
255
256       -Z flag
257           Unstable (nightly-only) flags to Cargo. Run cargo -Z help for
258           details.
259
260   Miscellaneous Options
261       -j N, --jobs N
262           Number of parallel jobs to run. May also be specified with the
263           build.jobs config value
264           <https://doc.rust-lang.org/cargo/reference/config.html>. Defaults to
265           the number of logical CPUs. If negative, it sets the maximum number
266           of parallel jobs to the number of logical CPUs plus provided value.
267           If a string default is provided, it sets the value back to defaults.
268           Should not be 0.
269
270       --keep-going
271           Build as many crates in the dependency graph as possible, rather
272           than aborting the build on the first one that fails to build.
273
274           For example if the current package depends on dependencies fails and
275           works, one of which fails to build, cargo run -j1 may or may not
276           build the one that succeeds (depending on which one of the two
277           builds Cargo picked to run first), whereas cargo run -j1
278           --keep-going would definitely run both builds, even if the one run
279           first fails.
280
281ENVIRONMENT
282       See the reference
283       <https://doc.rust-lang.org/cargo/reference/environment-variables.html>
284       for details on environment variables that Cargo reads.
285
286EXIT STATUS
287       o  0: Cargo succeeded.
288
289       o  101: Cargo failed to complete.
290
291EXAMPLES
292       1. Build the local package and run its main target (assuming only one
293          binary):
294
295              cargo run
296
297       2. Run an example with extra arguments:
298
299              cargo run --example exname -- --exoption exarg1 exarg2
300
301SEE ALSO
302       cargo(1), cargo-build(1)
303