fork/cargo

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

Weihang Lofix: use `host-tuple` for host target subsitution (#16003)f2932725b

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