]>
Commit | Line | Data |
---|---|---|
2d4aa38b EH |
1 | # cargo-run(1) |
2 | ||
3 | ||
4 | ## NAME | |
5 | ||
6 | cargo-run - Run the current package | |
7 | ||
8 | ## SYNOPSIS | |
9 | ||
10 | `cargo run` [_options_] [`--` _args_] | |
11 | ||
12 | ## DESCRIPTION | |
13 | ||
14 | Run a binary or example of the local package. | |
15 | ||
16 | All the arguments following the two dashes (`--`) are passed to the binary to | |
17 | run. If you're passing arguments to both Cargo and the binary, the ones after | |
18 | `--` go to the binary, the ones before go to Cargo. | |
19 | ||
20 | ## OPTIONS | |
21 | ||
22 | ### Package Selection | |
23 | ||
24 | By default, the package in the current working directory is selected. The `-p` | |
25 | flag can be used to choose a different package in a workspace. | |
26 | ||
27 | <dl> | |
28 | ||
29 | <dt class="option-term" id="option-cargo-run--p"><a class="option-anchor" href="#option-cargo-run--p"></a><code>-p</code> <em>spec</em></dt> | |
30 | <dt class="option-term" id="option-cargo-run---package"><a class="option-anchor" href="#option-cargo-run---package"></a><code>--package</code> <em>spec</em></dt> | |
1a86f232 | 31 | <dd class="option-desc">The package to run. See <a href="cargo-pkgid.html">cargo-pkgid(1)</a> for the SPEC |
2d4aa38b EH |
32 | format.</dd> |
33 | ||
34 | ||
35 | </dl> | |
36 | ||
37 | ||
38 | ### Target Selection | |
39 | ||
40 | When no target selection options are given, `cargo run` will run the binary | |
41 | target. If there are multiple binary targets, you must pass a target flag to | |
42 | choose one. Or, the `default-run` field may be specified in the `[package]` | |
43 | section of `Cargo.toml` to choose the name of the binary to run by default. | |
44 | ||
45 | <dl> | |
46 | ||
47 | <dt class="option-term" id="option-cargo-run---bin"><a class="option-anchor" href="#option-cargo-run---bin"></a><code>--bin</code> <em>name</em></dt> | |
48 | <dd class="option-desc">Run the specified binary.</dd> | |
49 | ||
50 | ||
51 | <dt class="option-term" id="option-cargo-run---example"><a class="option-anchor" href="#option-cargo-run---example"></a><code>--example</code> <em>name</em></dt> | |
52 | <dd class="option-desc">Run the specified example.</dd> | |
53 | ||
54 | ||
55 | </dl> | |
56 | ||
57 | ### Feature Selection | |
58 | ||
d087aeb8 EH |
59 | The feature flags allow you to control which features are enabled. When no |
60 | feature options are given, the `default` feature is activated for every | |
61 | selected package. | |
2d4aa38b | 62 | |
d087aeb8 EH |
63 | See [the features documentation](../reference/features.html#command-line-feature-options) |
64 | for more details. | |
2d4aa38b EH |
65 | |
66 | <dl> | |
67 | ||
f7280457 | 68 | <dt class="option-term" id="option-cargo-run--F"><a class="option-anchor" href="#option-cargo-run--F"></a><code>-F</code> <em>features</em></dt> |
2d4aa38b | 69 | <dt class="option-term" id="option-cargo-run---features"><a class="option-anchor" href="#option-cargo-run---features"></a><code>--features</code> <em>features</em></dt> |
d087aeb8 EH |
70 | <dd class="option-desc">Space or comma separated list of features to activate. Features of workspace |
71 | members may be enabled with <code>package-name/feature-name</code> syntax. This flag may | |
72 | be specified multiple times, which enables all specified features.</dd> | |
2d4aa38b EH |
73 | |
74 | ||
75 | <dt class="option-term" id="option-cargo-run---all-features"><a class="option-anchor" href="#option-cargo-run---all-features"></a><code>--all-features</code></dt> | |
76 | <dd class="option-desc">Activate all available features of all selected packages.</dd> | |
77 | ||
78 | ||
79 | <dt class="option-term" id="option-cargo-run---no-default-features"><a class="option-anchor" href="#option-cargo-run---no-default-features"></a><code>--no-default-features</code></dt> | |
d087aeb8 | 80 | <dd class="option-desc">Do not activate the <code>default</code> feature of the selected packages.</dd> |
2d4aa38b EH |
81 | |
82 | ||
83 | </dl> | |
84 | ||
85 | ||
86 | ### Compilation Options | |
87 | ||
88 | <dl> | |
89 | ||
90 | <dt class="option-term" id="option-cargo-run---target"><a class="option-anchor" href="#option-cargo-run---target"></a><code>--target</code> <em>triple</em></dt> | |
08734a66 | 91 | <dd class="option-desc">Run for the given architecture. The default is the host architecture. The general format of the triple is |
2d4aa38b EH |
92 | <code><arch><sub>-<vendor>-<sys>-<abi></code>. Run <code>rustc --print target-list</code> for a |
93 | list of supported targets.</p> | |
94 | <p>This may also be specified with the <code>build.target</code> | |
1a86f232 | 95 | <a href="../reference/config.html">config value</a>.</p> |
2d4aa38b EH |
96 | <p>Note that specifying this flag makes Cargo run in a different mode where the |
97 | target artifacts are placed in a separate directory. See the | |
1a86f232 | 98 | <a href="../guide/build-cache.html">build cache</a> documentation for more details.</dd> |
2d4aa38b EH |
99 | |
100 | ||
101 | ||
c92d917f | 102 | <dt class="option-term" id="option-cargo-run--r"><a class="option-anchor" href="#option-cargo-run--r"></a><code>-r</code></dt> |
2d4aa38b | 103 | <dt class="option-term" id="option-cargo-run---release"><a class="option-anchor" href="#option-cargo-run---release"></a><code>--release</code></dt> |
895f5271 EH |
104 | <dd class="option-desc">Run optimized artifacts with the <code>release</code> profile. |
105 | See also the <code>--profile</code> option for choosing a specific profile by name.</dd> | |
106 | ||
107 | ||
108 | ||
109 | <dt class="option-term" id="option-cargo-run---profile"><a class="option-anchor" href="#option-cargo-run---profile"></a><code>--profile</code> <em>name</em></dt> | |
110 | <dd class="option-desc">Run with the given profile. | |
111 | See the <a href="../reference/profiles.html">the reference</a> for more details on profiles.</dd> | |
2d4aa38b EH |
112 | |
113 | ||
114 | ||
db3776cf DO |
115 | <dt class="option-term" id="option-cargo-run---ignore-rust-version"><a class="option-anchor" href="#option-cargo-run---ignore-rust-version"></a><code>--ignore-rust-version</code></dt> |
116 | <dd class="option-desc">Run the target even if the selected Rust compiler is older than the | |
117 | required Rust version as configured in the project's <code>rust-version</code> field.</dd> | |
118 | ||
119 | ||
120 | ||
c8542471 | 121 | <dt class="option-term" id="option-cargo-run---timings=fmts"><a class="option-anchor" href="#option-cargo-run---timings=fmts"></a><code>--timings=</code><em>fmts</em></dt> |
c0669189 JT |
122 | <dd class="option-desc">Output information how long each compilation takes, and track concurrency |
123 | information over time. Accepts an optional comma-separated list of output | |
086e71da | 124 | formats; <code>--timings</code> without an argument will default to <code>--timings=html</code>. |
81e1998e JT |
125 | Specifying an output format (rather than the default) is unstable and requires |
126 | <code>-Zunstable-options</code>. Valid output formats:</p> | |
c0669189 | 127 | <ul> |
a6e6b89d | 128 | <li><code>html</code> (unstable, requires <code>-Zunstable-options</code>): Write a human-readable file <code>cargo-timing.html</code> to the |
e23f5f41 JT |
129 | <code>target/cargo-timings</code> directory with a report of the compilation. Also write |
130 | a report to the same directory with a timestamp in the filename if you want | |
131 | to look at older runs. HTML output is suitable for human consumption only, | |
132 | and does not provide machine-readable timing data.</li> | |
c0669189 JT |
133 | <li><code>json</code> (unstable, requires <code>-Zunstable-options</code>): Emit machine-readable JSON |
134 | information about timing information.</li> | |
135 | </ul></dd> | |
136 | ||
137 | ||
138 | ||
139 | ||
2d4aa38b EH |
140 | </dl> |
141 | ||
142 | ### Output Options | |
143 | ||
144 | <dl> | |
145 | <dt class="option-term" id="option-cargo-run---target-dir"><a class="option-anchor" href="#option-cargo-run---target-dir"></a><code>--target-dir</code> <em>directory</em></dt> | |
146 | <dd class="option-desc">Directory for all generated artifacts and intermediate files. May also be | |
147 | specified with the <code>CARGO_TARGET_DIR</code> environment variable, or the | |
ee53210f WL |
148 | <code>build.target-dir</code> <a href="../reference/config.html">config value</a>. |
149 | Defaults to <code>target</code> in the root of the workspace.</dd> | |
2d4aa38b EH |
150 | |
151 | ||
152 | </dl> | |
153 | ||
154 | ### Display Options | |
155 | ||
156 | <dl> | |
157 | ||
158 | <dt class="option-term" id="option-cargo-run--v"><a class="option-anchor" href="#option-cargo-run--v"></a><code>-v</code></dt> | |
159 | <dt class="option-term" id="option-cargo-run---verbose"><a class="option-anchor" href="#option-cargo-run---verbose"></a><code>--verbose</code></dt> | |
160 | <dd class="option-desc">Use verbose output. May be specified twice for "very verbose" output which | |
161 | includes extra output such as dependency warnings and build script output. | |
162 | May also be specified with the <code>term.verbose</code> | |
1a86f232 | 163 | <a href="../reference/config.html">config value</a>.</dd> |
2d4aa38b EH |
164 | |
165 | ||
166 | <dt class="option-term" id="option-cargo-run--q"><a class="option-anchor" href="#option-cargo-run--q"></a><code>-q</code></dt> | |
167 | <dt class="option-term" id="option-cargo-run---quiet"><a class="option-anchor" href="#option-cargo-run---quiet"></a><code>--quiet</code></dt> | |
cd4e2804 SJ |
168 | <dd class="option-desc">Do not print cargo log messages. |
169 | May also be specified with the <code>term.quiet</code> | |
170 | <a href="../reference/config.html">config value</a>.</dd> | |
2d4aa38b EH |
171 | |
172 | ||
173 | <dt class="option-term" id="option-cargo-run---color"><a class="option-anchor" href="#option-cargo-run---color"></a><code>--color</code> <em>when</em></dt> | |
174 | <dd class="option-desc">Control when colored output is used. Valid values:</p> | |
175 | <ul> | |
176 | <li><code>auto</code> (default): Automatically detect if color support is available on the | |
177 | terminal.</li> | |
178 | <li><code>always</code>: Always display colors.</li> | |
179 | <li><code>never</code>: Never display colors.</li> | |
180 | </ul> | |
181 | <p>May also be specified with the <code>term.color</code> | |
1a86f232 | 182 | <a href="../reference/config.html">config value</a>.</dd> |
2d4aa38b EH |
183 | |
184 | ||
185 | ||
186 | <dt class="option-term" id="option-cargo-run---message-format"><a class="option-anchor" href="#option-cargo-run---message-format"></a><code>--message-format</code> <em>fmt</em></dt> | |
187 | <dd class="option-desc">The output format for diagnostic messages. Can be specified multiple times | |
188 | and consists of comma-separated values. Valid values:</p> | |
189 | <ul> | |
d174b773 CR |
190 | <li><code>human</code> (default): Display in a human-readable text format. Conflicts with |
191 | <code>short</code> and <code>json</code>.</li> | |
192 | <li><code>short</code>: Emit shorter, human-readable text messages. Conflicts with <code>human</code> | |
193 | and <code>json</code>.</li> | |
2d4aa38b | 194 | <li><code>json</code>: Emit JSON messages to stdout. See |
1a86f232 | 195 | <a href="../reference/external-tools.html#json-messages">the reference</a> |
d174b773 | 196 | for more details. Conflicts with <code>human</code> and <code>short</code>.</li> |
2d4aa38b | 197 | <li><code>json-diagnostic-short</code>: Ensure the <code>rendered</code> field of JSON messages contains |
d174b773 | 198 | the "short" rendering from rustc. Cannot be used with <code>human</code> or <code>short</code>.</li> |
2d4aa38b EH |
199 | <li><code>json-diagnostic-rendered-ansi</code>: Ensure the <code>rendered</code> field of JSON messages |
200 | contains embedded ANSI color codes for respecting rustc's default color | |
d174b773 | 201 | scheme. Cannot be used with <code>human</code> or <code>short</code>.</li> |
195b1e0e | 202 | <li><code>json-render-diagnostics</code>: Instruct Cargo to not include rustc diagnostics |
2d4aa38b EH |
203 | in JSON messages printed, but instead Cargo itself should render the |
204 | JSON diagnostics coming from rustc. Cargo's own JSON diagnostics and others | |
d174b773 | 205 | coming from rustc are still emitted. Cannot be used with <code>human</code> or <code>short</code>.</li> |
2d4aa38b EH |
206 | </ul></dd> |
207 | ||
208 | ||
209 | ||
210 | </dl> | |
211 | ||
212 | ### Manifest Options | |
213 | ||
214 | <dl> | |
215 | ||
216 | <dt class="option-term" id="option-cargo-run---manifest-path"><a class="option-anchor" href="#option-cargo-run---manifest-path"></a><code>--manifest-path</code> <em>path</em></dt> | |
217 | <dd class="option-desc">Path to the <code>Cargo.toml</code> file. By default, Cargo searches for the | |
218 | <code>Cargo.toml</code> file in the current directory or any parent directory.</dd> | |
219 | ||
220 | ||
221 | ||
222 | <dt class="option-term" id="option-cargo-run---frozen"><a class="option-anchor" href="#option-cargo-run---frozen"></a><code>--frozen</code></dt> | |
223 | <dt class="option-term" id="option-cargo-run---locked"><a class="option-anchor" href="#option-cargo-run---locked"></a><code>--locked</code></dt> | |
224 | <dd class="option-desc">Either of these flags requires that the <code>Cargo.lock</code> file is | |
225 | up-to-date. If the lock file is missing, or it needs to be updated, Cargo will | |
226 | exit with an error. The <code>--frozen</code> flag also prevents Cargo from | |
227 | attempting to access the network to determine if it is out-of-date.</p> | |
228 | <p>These may be used in environments where you want to assert that the | |
229 | <code>Cargo.lock</code> file is up-to-date (such as a CI build) or want to avoid network | |
230 | access.</dd> | |
231 | ||
232 | ||
233 | <dt class="option-term" id="option-cargo-run---offline"><a class="option-anchor" href="#option-cargo-run---offline"></a><code>--offline</code></dt> | |
234 | <dd class="option-desc">Prevents Cargo from accessing the network for any reason. Without this | |
235 | flag, Cargo will stop with an error if it needs to access the network and | |
236 | the network is not available. With this flag, Cargo will attempt to | |
237 | proceed without the network if possible.</p> | |
238 | <p>Beware that this may result in different dependency resolution than online | |
239 | mode. Cargo will restrict itself to crates that are downloaded locally, even | |
240 | if there might be a newer version as indicated in the local copy of the index. | |
1a86f232 | 241 | See the <a href="cargo-fetch.html">cargo-fetch(1)</a> command to download dependencies before going |
2d4aa38b | 242 | offline.</p> |
1a86f232 | 243 | <p>May also be specified with the <code>net.offline</code> <a href="../reference/config.html">config value</a>.</dd> |
2d4aa38b EH |
244 | |
245 | ||
246 | ||
247 | </dl> | |
248 | ||
249 | ### Common Options | |
250 | ||
251 | <dl> | |
252 | ||
253 | <dt class="option-term" id="option-cargo-run-+toolchain"><a class="option-anchor" href="#option-cargo-run-+toolchain"></a><code>+</code><em>toolchain</em></dt> | |
254 | <dd class="option-desc">If Cargo has been installed with rustup, and the first argument to <code>cargo</code> | |
255 | begins with <code>+</code>, it will be interpreted as a rustup toolchain name (such | |
256 | as <code>+stable</code> or <code>+nightly</code>). | |
fac70ee7 | 257 | See the <a href="https://rust-lang.github.io/rustup/overrides.html">rustup documentation</a> |
2d4aa38b EH |
258 | for more information about how toolchain overrides work.</dd> |
259 | ||
260 | ||
65332bc9 WL |
261 | <dt class="option-term" id="option-cargo-run---config"><a class="option-anchor" href="#option-cargo-run---config"></a><code>--config</code> <em>KEY=VALUE</em> or <em>PATH</em></dt> |
262 | <dd class="option-desc">Overrides a Cargo configuration value. The argument should be in TOML syntax of <code>KEY=VALUE</code>, | |
263 | or provided as a path to an extra configuration file. This flag may be specified multiple times. | |
264 | See the <a href="../reference/config.html#command-line-overrides">command-line overrides section</a> for more information.</dd> | |
7eefb422 JG |
265 | |
266 | ||
2d4aa38b EH |
267 | <dt class="option-term" id="option-cargo-run--h"><a class="option-anchor" href="#option-cargo-run--h"></a><code>-h</code></dt> |
268 | <dt class="option-term" id="option-cargo-run---help"><a class="option-anchor" href="#option-cargo-run---help"></a><code>--help</code></dt> | |
269 | <dd class="option-desc">Prints help information.</dd> | |
270 | ||
271 | ||
272 | <dt class="option-term" id="option-cargo-run--Z"><a class="option-anchor" href="#option-cargo-run--Z"></a><code>-Z</code> <em>flag</em></dt> | |
273 | <dd class="option-desc">Unstable (nightly-only) flags to Cargo. Run <code>cargo -Z help</code> for details.</dd> | |
274 | ||
275 | ||
276 | </dl> | |
277 | ||
278 | ||
279 | ### Miscellaneous Options | |
280 | ||
281 | <dl> | |
282 | <dt class="option-term" id="option-cargo-run--j"><a class="option-anchor" href="#option-cargo-run--j"></a><code>-j</code> <em>N</em></dt> | |
283 | <dt class="option-term" id="option-cargo-run---jobs"><a class="option-anchor" href="#option-cargo-run---jobs"></a><code>--jobs</code> <em>N</em></dt> | |
284 | <dd class="option-desc">Number of parallel jobs to run. May also be specified with the | |
1a86f232 | 285 | <code>build.jobs</code> <a href="../reference/config.html">config value</a>. Defaults to |
5b76fb3d YT |
286 | the number of logical CPUs. If negative, it sets the maximum number of |
287 | parallel jobs to the number of logical CPUs plus provided value. | |
288 | Should not be 0.</dd> | |
2d4aa38b EH |
289 | |
290 | ||
4e45f588 DT |
291 | <dt class="option-term" id="option-cargo-run---keep-going"><a class="option-anchor" href="#option-cargo-run---keep-going"></a><code>--keep-going</code></dt> |
292 | <dd class="option-desc">Build as many crates in the dependency graph as possible, rather than aborting | |
293 | the build on the first one that fails to build. Unstable, requires | |
294 | <code>-Zunstable-options</code>.</dd> | |
295 | ||
296 | ||
2d4aa38b EH |
297 | </dl> |
298 | ||
2d4aa38b EH |
299 | ## ENVIRONMENT |
300 | ||
301 | See [the reference](../reference/environment-variables.html) for | |
302 | details on environment variables that Cargo reads. | |
303 | ||
304 | ||
305 | ## EXIT STATUS | |
306 | ||
307 | * `0`: Cargo succeeded. | |
308 | * `101`: Cargo failed to complete. | |
309 | ||
310 | ||
311 | ## EXAMPLES | |
312 | ||
313 | 1. Build the local package and run its main target (assuming only one binary): | |
314 | ||
315 | cargo run | |
316 | ||
317 | 2. Run an example with extra arguments: | |
318 | ||
319 | cargo run --example exname -- --exoption exarg1 exarg2 | |
320 | ||
321 | ## SEE ALSO | |
1a86f232 | 322 | [cargo(1)](cargo.html), [cargo-build(1)](cargo-build.html) |