]>
Commit | Line | Data |
---|---|---|
4d590f95 BE |
1 | ## Configuration |
2 | ||
dd8f7d8d | 3 | This document explains how Cargo’s configuration system works, as well as |
f7c91ba6 | 4 | available keys or configuration. For configuration of a package through its |
b119b891 | 5 | manifest, see the [manifest format](manifest.md). |
4d590f95 BE |
6 | |
7 | ### Hierarchical structure | |
8 | ||
4a8bd29f | 9 | Cargo allows local configuration for a particular package as well as global |
dd8f7d8d EH |
10 | configuration. It looks for configuration files in the current directory and |
11 | all parent directories. If, for example, Cargo were invoked in | |
12 | `/projects/foo/bar/baz`, then the following configuration files would be | |
13 | probed for and unified in this order: | |
4d590f95 | 14 | |
25409e56 | 15 | * `/projects/foo/bar/baz/.cargo/config.toml` |
16 | * `/projects/foo/bar/.cargo/config.toml` | |
17 | * `/projects/foo/.cargo/config.toml` | |
18 | * `/projects/.cargo/config.toml` | |
19 | * `/.cargo/config.toml` | |
20 | * `$CARGO_HOME/config.toml` which defaults to: | |
21 | * Windows: `%USERPROFILE%\.cargo\config.toml` | |
22 | * Unix: `$HOME/.cargo/config.toml` | |
4d590f95 | 23 | |
4a8bd29f | 24 | With this structure, you can specify configuration per-package, and even |
271860a9 | 25 | possibly check it into version control. You can also specify personal defaults |
4d590f95 BE |
26 | with a configuration file in your home directory. |
27 | ||
dd8f7d8d EH |
28 | If a key is specified in multiple config files, the values will get merged |
29 | together. Numbers, strings, and booleans will use the value in the deeper | |
30 | config directory taking precedence over ancestor directories, where the | |
31 | home directory is the lowest priority. Arrays will be joined together. | |
4d590f95 | 32 | |
4e180e69 IK |
33 | At present, when being invoked from a workspace, Cargo does not read config |
34 | files from crates within the workspace. i.e. if a workspace has two crates in | |
35 | it, named `/projects/foo/bar/baz/mylib` and `/projects/foo/bar/baz/mybin`, and | |
36 | there are Cargo configs at `/projects/foo/bar/baz/mylib/.cargo/config.toml` | |
37 | and `/projects/foo/bar/baz/mybin/.cargo/config.toml`, Cargo does not read | |
38 | those configuration files if it is invoked from the workspace root | |
39 | (`/projects/foo/bar/baz/`). | |
40 | ||
d20d395c EH |
41 | > **Note:** Cargo also reads config files without the `.toml` extension, such as |
42 | > `.cargo/config`. Support for the `.toml` extension was added in version 1.39 | |
43 | > and is the preferred form. If both files exist, Cargo will use the file | |
44 | > without the extension. | |
45 | ||
dd8f7d8d | 46 | ### Configuration format |
4d590f95 | 47 | |
dd8f7d8d EH |
48 | Configuration files are written in the [TOML format][toml] (like the |
49 | manifest), with simple key-value pairs inside of sections (tables). The | |
50 | following is a quick overview of all settings, with detailed descriptions | |
51 | found below. | |
4d590f95 BE |
52 | |
53 | ```toml | |
dd8f7d8d | 54 | paths = ["/path/to/override"] # path dependency overrides |
4d590f95 | 55 | |
dd8f7d8d EH |
56 | [alias] # command aliases |
57 | b = "build" | |
58 | c = "check" | |
59 | t = "test" | |
60 | r = "run" | |
61 | rr = "run --release" | |
62 | space_example = ["run", "--release", "--", "\"command list\""] | |
ba375813 | 63 | |
4d590f95 | 64 | [build] |
f838a003 EB |
65 | jobs = 1 # number of parallel jobs, defaults to # of CPUs |
66 | rustc = "rustc" # the rust compiler tool | |
67 | rustc-wrapper = "…" # run this wrapper instead of `rustc` | |
68 | rustc-workspace-wrapper = "…" # run this wrapper instead of `rustc` for workspace members | |
69 | rustdoc = "rustdoc" # the doc generator tool | |
70 | target = "triple" # build for the target triple (ignored by `cargo install`) | |
71 | target-dir = "target" # path of where to place all generated artifacts | |
72 | rustflags = ["…", "…"] # custom flags to pass to all compiler invocations | |
73 | rustdocflags = ["…", "…"] # custom flags to pass to rustdoc | |
74 | incremental = true # whether or not to enable incremental compilation | |
75 | dep-info-basedir = "…" # path for the base directory for targets in depfiles | |
4d590f95 | 76 | |
6128b54b | 77 | [doc] |
e840c8e8 J |
78 | browser = "chromium" # browser to use with `cargo doc --open`, |
79 | # overrides the `BROWSER` environment variable | |
80 | ||
ab38ce0f JT |
81 | [env] |
82 | # Set ENV_VAR_NAME=value for any process run by Cargo | |
83 | ENV_VAR_NAME = "value" | |
84 | # Set even if already present in environment | |
85 | ENV_VAR_NAME_2 = { value = "value", force = true } | |
86 | # Value is relative to .cargo directory containing `config.toml`, make absolute | |
87 | ENV_VAR_NAME_3 = { value = "relative/path", relative = true } | |
88 | ||
a717196b AH |
89 | [future-incompat-report] |
90 | frequency = 'always' # when to display a notification about a future incompat report | |
91 | ||
dd8f7d8d | 92 | [cargo-new] |
dd8f7d8d EH |
93 | vcs = "none" # VCS to use ('git', 'hg', 'pijul', 'fossil', 'none') |
94 | ||
95 | [http] | |
96 | debug = false # HTTP debugging | |
97 | proxy = "host:port" # HTTP proxy in libcurl format | |
98 | ssl-version = "tlsv1.3" # TLS version to use | |
99 | ssl-version.max = "tlsv1.3" # maximum TLS version | |
100 | ssl-version.min = "tlsv1.1" # minimum TLS version | |
101 | timeout = 30 # timeout for each HTTP request, in seconds | |
102 | low-speed-limit = 10 # network timeout threshold (bytes/sec) | |
103 | cainfo = "cert.pem" # path to Certificate Authority (CA) bundle | |
104 | check-revoke = true # check for SSL certificate revocation | |
105 | multiplexing = true # HTTP/2 multiplexing | |
106 | user-agent = "…" # the user-agent header | |
107 | ||
108 | [install] | |
109 | root = "/some/path" # `cargo install` destination directory | |
4d590f95 | 110 | |
4d590f95 | 111 | [net] |
dd8f7d8d EH |
112 | retry = 2 # network retries |
113 | git-fetch-with-cli = true # use the `git` executable for git operations | |
0fe36b6e | 114 | offline = true # do not access the network |
4d590f95 | 115 | |
1e0d564f JG |
116 | [patch.<registry>] |
117 | # Same keys as for [patch] in Cargo.toml | |
118 | ||
8e935d4d EH |
119 | [profile.<name>] # Modify profile settings via config. |
120 | opt-level = 0 # Optimization level. | |
121 | debug = true # Include debug info. | |
8b3c9adf | 122 | split-debuginfo = '...' # Debug info splitting behavior. |
8e935d4d EH |
123 | debug-assertions = true # Enables debug assertions. |
124 | overflow-checks = true # Enables runtime integer overflow checks. | |
125 | lto = false # Sets link-time optimization. | |
126 | panic = 'unwind' # The panic strategy. | |
127 | incremental = true # Incremental compilation. | |
128 | codegen-units = 16 # Number of code generation units. | |
129 | rpath = false # Sets the rpath linking option. | |
130 | [profile.<name>.build-override] # Overrides build-script settings. | |
131 | # Same keys for a normal profile. | |
132 | [profile.<name>.package.<name>] # Override profile for a package. | |
133 | # Same keys for a normal profile (minus `panic`, `lto`, and `rpath`). | |
134 | ||
dd8f7d8d EH |
135 | [registries.<name>] # registries other than crates.io |
136 | index = "…" # URL of the registry index | |
137 | token = "…" # authentication token for the registry | |
138 | ||
139 | [registry] | |
140 | default = "…" # name of the default registry | |
141 | token = "…" # authentication token for crates.io | |
142 | ||
143 | [source.<name>] # source definition and replacement | |
144 | replace-with = "…" # replace this source with the given named source | |
145 | directory = "…" # path to a directory source | |
146 | registry = "…" # URL to a registry source | |
147 | local-registry = "…" # path to a local registry source | |
148 | git = "…" # URL of a git repository source | |
149 | branch = "…" # branch name for the git repository | |
150 | tag = "…" # tag name for the git repository | |
151 | rev = "…" # revision for the git repository | |
152 | ||
153 | [target.<triple>] | |
154 | linker = "…" # linker to use | |
155 | runner = "…" # wrapper to run executables | |
156 | rustflags = ["…", "…"] # custom flags for `rustc` | |
157 | ||
158 | [target.<cfg>] | |
159 | runner = "…" # wrapper to run executables | |
160 | rustflags = ["…", "…"] # custom flags for `rustc` | |
161 | ||
162 | [target.<triple>.<links>] # `links` build script override | |
163 | rustc-link-lib = ["foo"] | |
164 | rustc-link-search = ["/path/to/foo"] | |
165 | rustc-flags = ["-L", "/some/path"] | |
166 | rustc-cfg = ['key="value"'] | |
167 | rustc-env = {key = "value"} | |
168 | rustc-cdylib-link-arg = ["…"] | |
169 | metadata_key1 = "value" | |
170 | metadata_key2 = "value" | |
171 | ||
172 | [term] | |
7ac6f537 | 173 | quiet = false # whether cargo output is quiet |
dd8f7d8d EH |
174 | verbose = false # whether cargo provides verbose output |
175 | color = 'auto' # whether cargo colorizes output | |
d649c661 | 176 | progress.when = 'auto' # whether cargo shows progress bar |
177 | progress.width = 80 # width of progress bar | |
4d590f95 BE |
178 | ``` |
179 | ||
180 | ### Environment variables | |
181 | ||
182 | Cargo can also be configured through environment variables in addition to the | |
dd8f7d8d EH |
183 | TOML configuration files. For each configuration key of the form `foo.bar` the |
184 | environment variable `CARGO_FOO_BAR` can also be used to define the value. | |
185 | Keys are converted to uppercase, dots and dashes are converted to underscores. | |
186 | For example the `target.x86_64-unknown-linux-gnu.runner` key can also be | |
187 | defined by the `CARGO_TARGET_X86_64_UNKNOWN_LINUX_GNU_RUNNER` environment | |
188 | variable. | |
189 | ||
190 | Environment variables will take precedence over TOML configuration files. | |
191 | Currently only integer, boolean, string and some array values are supported to | |
192 | be defined by environment variables. Descriptions below indicate which keys | |
193 | support environment variables. | |
4d590f95 BE |
194 | |
195 | In addition to the system above, Cargo recognizes a few other specific | |
196 | [environment variables][env]. | |
197 | ||
dd8f7d8d EH |
198 | ### Config-relative paths |
199 | ||
200 | Paths in config files may be absolute, relative, or a bare name without any | |
201 | path separators. Paths for executables without a path separator will use the | |
202 | `PATH` environment variable to search for the executable. Paths for | |
203 | non-executables will be relative to where the config value is defined. For | |
204 | config files, that is relative to the parent directory of the `.cargo` | |
205 | directory where the value was defined. For environment variables it is | |
206 | relative to the current working directory. | |
207 | ||
208 | ```toml | |
209 | # Relative path examples. | |
210 | ||
211 | [target.x86_64-unknown-linux-gnu] | |
212 | runner = "foo" # Searches `PATH` for `foo`. | |
213 | ||
214 | [source.vendored-sources] | |
25409e56 | 215 | # Directory is relative to the parent where `.cargo/config.toml` is located. |
216 | # For example, `/my/project/.cargo/config.toml` would result in `/my/project/vendor`. | |
dd8f7d8d EH |
217 | directory = "vendor" |
218 | ``` | |
219 | ||
1c44404e J |
220 | ### Executable paths with arguments |
221 | ||
222 | Some Cargo commands invoke external programs, which can be configured as a path | |
223 | and some number of arguments. | |
224 | ||
225 | The value may be an array of strings like `['/path/to/program', 'somearg']` or | |
226 | a space-separated string like `'/path/to/program somearg'`. If the path to the | |
227 | executable contains a space, the list form must be used. | |
228 | ||
229 | If Cargo is passing other arguments to the program such as a path to open or | |
230 | run, they will be passed after the last specified argument in the value of an | |
231 | option of this format. If the specified program does not have path separators, | |
232 | Cargo will search `PATH` for its executable. | |
233 | ||
737382d7 EH |
234 | ### Credentials |
235 | ||
236 | Configuration values with sensitive information are stored in the | |
25409e56 | 237 | `$CARGO_HOME/credentials.toml` file. This file is automatically created and updated |
737382d7 EH |
238 | by [`cargo login`]. It follows the same format as Cargo config files. |
239 | ||
240 | ```toml | |
241 | [registry] | |
dd8f7d8d | 242 | token = "…" # Access token for crates.io |
737382d7 | 243 | |
dd8f7d8d EH |
244 | [registries.<name>] |
245 | token = "…" # Access token for the named registry | |
737382d7 EH |
246 | ``` |
247 | ||
248 | Tokens are used by some Cargo commands such as [`cargo publish`] for | |
249 | authenticating with remote registries. Care should be taken to protect the | |
250 | tokens and to keep them secret. | |
251 | ||
252 | As with most other config values, tokens may be specified with environment | |
dd8f7d8d | 253 | variables. The token for [crates.io] may be specified with the |
737382d7 EH |
254 | `CARGO_REGISTRY_TOKEN` environment variable. Tokens for other registries may |
255 | be specified with environment variables of the form | |
dd8f7d8d EH |
256 | `CARGO_REGISTRIES_<name>_TOKEN` where `<name>` is the name of the registry in |
257 | all capital letters. | |
258 | ||
259 | ### Configuration keys | |
260 | ||
261 | This section documents all configuration keys. The description for keys with | |
262 | variable parts are annotated with angled brackets like `target.<triple>` where | |
263 | the `<triple>` part can be any target triple like | |
264 | `target.x86_64-pc-windows-msvc`. | |
265 | ||
266 | #### `paths` | |
267 | * Type: array of strings (paths) | |
268 | * Default: none | |
269 | * Environment: not supported | |
270 | ||
271 | An array of paths to local packages which are to be used as overrides for | |
d1d08378 EH |
272 | dependencies. For more information see the [Overriding Dependencies |
273 | guide](overriding-dependencies.md#paths-overrides). | |
dd8f7d8d EH |
274 | |
275 | #### `[alias]` | |
276 | * Type: string or array of strings | |
277 | * Default: see below | |
278 | * Environment: `CARGO_ALIAS_<name>` | |
279 | ||
280 | The `[alias]` table defines CLI command aliases. For example, running `cargo | |
281 | b` is an alias for running `cargo build`. Each key in the table is the | |
282 | subcommand, and the value is the actual command to run. The value may be an | |
283 | array of strings, where the first element is the command and the following are | |
284 | arguments. It may also be a string, which will be split on spaces into | |
285 | subcommand and arguments. The following aliases are built-in to Cargo: | |
286 | ||
287 | ```toml | |
288 | [alias] | |
289 | b = "build" | |
290 | c = "check" | |
b2e5d8a4 | 291 | d = "doc" |
dd8f7d8d EH |
292 | t = "test" |
293 | r = "run" | |
294 | ``` | |
295 | ||
296 | Aliases are not allowed to redefine existing built-in commands. | |
297 | ||
298 | #### `[build]` | |
299 | ||
300 | The `[build]` table controls build-time operations and compiler settings. | |
301 | ||
302 | ##### `build.jobs` | |
303 | * Type: integer | |
304 | * Default: number of logical CPUs | |
305 | * Environment: `CARGO_BUILD_JOBS` | |
306 | ||
307 | Sets the maximum number of compiler processes to run in parallel. | |
308 | ||
309 | Can be overridden with the `--jobs` CLI option. | |
310 | ||
311 | ##### `build.rustc` | |
312 | * Type: string (program path) | |
313 | * Default: "rustc" | |
314 | * Environment: `CARGO_BUILD_RUSTC` or `RUSTC` | |
315 | ||
316 | Sets the executable to use for `rustc`. | |
317 | ||
318 | ##### `build.rustc-wrapper` | |
319 | * Type: string (program path) | |
320 | * Default: none | |
321 | * Environment: `CARGO_BUILD_RUSTC_WRAPPER` or `RUSTC_WRAPPER` | |
322 | ||
323 | Sets a wrapper to execute instead of `rustc`. The first argument passed to the | |
324 | wrapper is the path to the actual `rustc`. | |
325 | ||
f838a003 EB |
326 | ##### `build.rustc-workspace-wrapper` |
327 | * Type: string (program path) | |
328 | * Default: none | |
329 | * Environment: `CARGO_BUILD_RUSTC_WORKSPACE_WRAPPER` or `RUSTC_WORKSPACE_WRAPPER` | |
330 | ||
331 | Sets a wrapper to execute instead of `rustc`, for workspace members only. | |
332 | The first argument passed to the wrapper is the path to the actual `rustc`. | |
333 | It affects the filename hash so that artifacts produced by the wrapper are cached separately. | |
334 | ||
dd8f7d8d EH |
335 | ##### `build.rustdoc` |
336 | * Type: string (program path) | |
337 | * Default: "rustdoc" | |
338 | * Environment: `CARGO_BUILD_RUSTDOC` or `RUSTDOC` | |
339 | ||
340 | Sets the executable to use for `rustdoc`. | |
341 | ||
342 | ##### `build.target` | |
343 | * Type: string | |
344 | * Default: host platform | |
345 | * Environment: `CARGO_BUILD_TARGET` | |
346 | ||
347 | The default target platform triple to compile to. | |
348 | ||
349 | This may also be a relative path to a `.json` target spec file. | |
350 | ||
351 | Can be overridden with the `--target` CLI option. | |
352 | ||
353 | ##### `build.target-dir` | |
354 | * Type: string (path) | |
355 | * Default: "target" | |
356 | * Environment: `CARGO_BUILD_TARGET_DIR` or `CARGO_TARGET_DIR` | |
357 | ||
358 | The path to where all compiler output is placed. The default if not specified | |
359 | is a directory named `target` located at the root of the workspace. | |
360 | ||
361 | Can be overridden with the `--target-dir` CLI option. | |
362 | ||
363 | ##### `build.rustflags` | |
364 | * Type: string or array of strings | |
365 | * Default: none | |
26a499b9 | 366 | * Environment: `CARGO_BUILD_RUSTFLAGS` or `CARGO_ENCODED_RUSTFLAGS` or `RUSTFLAGS` |
dd8f7d8d EH |
367 | |
368 | Extra command-line flags to pass to `rustc`. The value may be a array of | |
369 | strings or a space-separated string. | |
370 | ||
f6d4039c | 371 | There are four mutually exclusive sources of extra flags. They are checked in |
dd8f7d8d EH |
372 | order, with the first one being used: |
373 | ||
26a499b9 | 374 | 1. `CARGO_ENCODED_RUSTFLAGS` environment variable. |
375 | 2. `RUSTFLAGS` environment variable. | |
376 | 3. All matching `target.<triple>.rustflags` and `target.<cfg>.rustflags` | |
dd8f7d8d | 377 | config entries joined together. |
26a499b9 | 378 | 4. `build.rustflags` config value. |
dd8f7d8d EH |
379 | |
380 | Additional flags may also be passed with the [`cargo rustc`] command. | |
381 | ||
382 | If the `--target` flag (or [`build.target`](#buildtarget)) is used, then the | |
383 | flags will only be passed to the compiler for the target. Things being built | |
384 | for the host, such as build scripts or proc macros, will not receive the args. | |
385 | Without `--target`, the flags will be passed to all compiler invocations | |
386 | (including build scripts and proc macros) because dependencies are shared. If | |
387 | you have args that you do not want to pass to build scripts or proc macros and | |
388 | are building for the host, pass `--target` with the host triple. | |
389 | ||
4d3772b8 | 390 | It is not recommended to pass in flags that Cargo itself usually manages. For |
58694812 | 391 | example, the flags driven by [profiles](profiles.md) are best handled by setting the |
4d3772b8 EH |
392 | appropriate profile setting. |
393 | ||
2d08c73c EH |
394 | > **Caution**: Due to the low-level nature of passing flags directly to the |
395 | > compiler, this may cause a conflict with future versions of Cargo which may | |
396 | > issue the same or similar flags on its own which may interfere with the | |
397 | > flags you specify. This is an area where Cargo may not always be backwards | |
398 | > compatible. | |
399 | ||
dd8f7d8d EH |
400 | ##### `build.rustdocflags` |
401 | * Type: string or array of strings | |
402 | * Default: none | |
26a499b9 | 403 | * Environment: `CARGO_BUILD_RUSTDOCFLAGS` or `CARGO_ENCODED_RUSTDOCFLAGS` or `RUSTDOCFLAGS` |
dd8f7d8d EH |
404 | |
405 | Extra command-line flags to pass to `rustdoc`. The value may be a array of | |
406 | strings or a space-separated string. | |
407 | ||
f6d4039c | 408 | There are three mutually exclusive sources of extra flags. They are checked in |
dd8f7d8d EH |
409 | order, with the first one being used: |
410 | ||
26a499b9 | 411 | 1. `CARGO_ENCODED_RUSTDOCFLAGS` environment variable. |
412 | 2. `RUSTDOCFLAGS` environment variable. | |
413 | 3. `build.rustdocflags` config value. | |
dd8f7d8d EH |
414 | |
415 | Additional flags may also be passed with the [`cargo rustdoc`] command. | |
416 | ||
417 | ##### `build.incremental` | |
418 | * Type: bool | |
419 | * Default: from profile | |
420 | * Environment: `CARGO_BUILD_INCREMENTAL` or `CARGO_INCREMENTAL` | |
421 | ||
422 | Whether or not to perform [incremental compilation]. The default if not set is | |
58694812 | 423 | to use the value from the [profile](profiles.md#incremental). Otherwise this overrides the setting of |
dd8f7d8d EH |
424 | all profiles. |
425 | ||
426 | The `CARGO_INCREMENTAL` environment variable can be set to `1` to force enable | |
427 | incremental compilation for all profiles, or `0` to disable it. This env var | |
428 | overrides the config setting. | |
429 | ||
430 | ##### `build.dep-info-basedir` | |
431 | * Type: string (path) | |
432 | * Default: none | |
433 | * Environment: `CARGO_BUILD_DEP_INFO_BASEDIR` | |
434 | ||
765c80da EH |
435 | Strips the given path prefix from [dep |
436 | info](../guide/build-cache.md#dep-info-files) file paths. This config setting | |
437 | is intended to convert absolute paths to relative paths for tools that require | |
438 | relative paths. | |
dd8f7d8d EH |
439 | |
440 | The setting itself is a config-relative path. So, for example, a value of | |
441 | `"."` would strip all paths starting with the parent directory of the `.cargo` | |
442 | directory. | |
443 | ||
444 | ##### `build.pipelining` | |
dd8f7d8d | 445 | |
65ddbbdf | 446 | This option is deprecated and unused. Cargo always has pipelining enabled. |
dd8f7d8d | 447 | |
6128b54b | 448 | #### `[doc]` |
e840c8e8 | 449 | |
6128b54b | 450 | The `[doc]` table defines options for the [`cargo doc`] command. |
e840c8e8 | 451 | |
6128b54b | 452 | ##### `doc.browser` |
e840c8e8 | 453 | |
58694812 | 454 | * Type: string or array of strings ([program path with args]) |
1c44404e J |
455 | * Default: `BROWSER` environment variable, or, if that is missing, |
456 | opening the link in a system specific way | |
457 | ||
e840c8e8 J |
458 | This option sets the browser to be used by [`cargo doc`], overriding the |
459 | `BROWSER` environment variable when opening documentation with the `--open` | |
460 | option. | |
461 | ||
dd8f7d8d EH |
462 | #### `[cargo-new]` |
463 | ||
464 | The `[cargo-new]` table defines defaults for the [`cargo new`] command. | |
465 | ||
96f8dbf8 J |
466 | ##### `cargo-new.name` |
467 | ||
468 | This option is deprecated and unused. | |
469 | ||
470 | ##### `cargo-new.email` | |
471 | ||
472 | This option is deprecated and unused. | |
473 | ||
dd8f7d8d EH |
474 | ##### `cargo-new.vcs` |
475 | * Type: string | |
476 | * Default: "git" or "none" | |
477 | * Environment: `CARGO_CARGO_NEW_VCS` | |
478 | ||
479 | Specifies the source control system to use for initializing a new repository. | |
480 | Valid values are `git`, `hg` (for Mercurial), `pijul`, `fossil` or `none` to | |
481 | disable this behavior. Defaults to `git`, or `none` if already inside a VCS | |
482 | repository. Can be overridden with the `--vcs` CLI option. | |
483 | ||
ab38ce0f JT |
484 | ### `[env]` |
485 | ||
486 | The `[env]` section allows you to set additional environment variables for | |
487 | build scripts, rustc invocations, `cargo run` and `cargo build`. | |
488 | ||
489 | ```toml | |
490 | [env] | |
491 | OPENSSL_DIR = "/opt/openssl" | |
492 | ``` | |
493 | ||
494 | By default, the variables specified will not override values that already exist | |
495 | in the environment. This behavior can be changed by setting the `force` flag. | |
496 | ||
497 | Setting the `relative` flag evaluates the value as a config-relative path that | |
498 | is relative to the parent directory of the `.cargo` directory that contains the | |
499 | `config.toml` file. The value of the environment variable will be the full | |
500 | absolute path. | |
501 | ||
502 | ```toml | |
503 | [env] | |
504 | TMPDIR = { value = "/home/tmp", force = true } | |
505 | OPENSSL_DIR = { value = "vendor/openssl", relative = true } | |
506 | ``` | |
507 | ||
4fcf5ca6 AH |
508 | ### `[future-incompat-report]` |
509 | ||
510 | The `[future-incompat-report]` table controls setting for [future incompat reporting](future-incompat-report.md) | |
511 | ||
512 | #### `future-incompat-report.frequency` | |
513 | * Type: string | |
514 | * Default: "always" | |
515 | * Environment: `CARGO_FUTURE_INCOMPAT_REPORT_FREQUENCY` | |
516 | ||
517 | Controls how often we display a notification to the terminal when a future incompat report is available. Possible values: | |
518 | ||
519 | * `always` (default): Always display a notification when a command (e.g. `cargo build`) produces a future incompat report | |
520 | * `never`: Never display a notification | |
521 | ||
dd8f7d8d EH |
522 | #### `[http]` |
523 | ||
524 | The `[http]` table defines settings for HTTP behavior. This includes fetching | |
525 | crate dependencies and accessing remote git repositories. | |
526 | ||
527 | ##### `http.debug` | |
528 | * Type: boolean | |
529 | * Default: false | |
530 | * Environment: `CARGO_HTTP_DEBUG` | |
531 | ||
532 | If `true`, enables debugging of HTTP requests. The debug information can be | |
533 | seen by setting the `CARGO_LOG=cargo::ops::registry=debug` environment | |
534 | variable (or use `trace` for even more information). | |
535 | ||
536 | Be wary when posting logs from this output in a public location. The output | |
537 | may include headers with authentication tokens which you don't want to leak! | |
538 | Be sure to review logs before posting them. | |
737382d7 | 539 | |
dd8f7d8d EH |
540 | ##### `http.proxy` |
541 | * Type: string | |
542 | * Default: none | |
543 | * Environment: `CARGO_HTTP_PROXY` or `HTTPS_PROXY` or `https_proxy` or `http_proxy` | |
544 | ||
545 | Sets an HTTP and HTTPS proxy to use. The format is in [libcurl format] as in | |
546 | `[protocol://]host[:port]`. If not set, Cargo will also check the `http.proxy` | |
547 | setting in your global git configuration. If none of those are set, the | |
548 | `HTTPS_PROXY` or `https_proxy` environment variables set the proxy for HTTPS | |
549 | requests, and `http_proxy` sets it for HTTP requests. | |
550 | ||
551 | ##### `http.timeout` | |
552 | * Type: integer | |
553 | * Default: 30 | |
554 | * Environment: `CARGO_HTTP_TIMEOUT` or `HTTP_TIMEOUT` | |
555 | ||
556 | Sets the timeout for each HTTP request, in seconds. | |
557 | ||
558 | ##### `http.cainfo` | |
559 | * Type: string (path) | |
560 | * Default: none | |
561 | * Environment: `CARGO_HTTP_CAINFO` | |
562 | ||
563 | Path to a Certificate Authority (CA) bundle file, used to verify TLS | |
564 | certificates. If not specified, Cargo attempts to use the system certificates. | |
565 | ||
566 | ##### `http.check-revoke` | |
567 | * Type: boolean | |
568 | * Default: true (Windows) false (all others) | |
569 | * Environment: `CARGO_HTTP_CHECK_REVOKE` | |
570 | ||
571 | This determines whether or not TLS certificate revocation checks should be | |
572 | performed. This only works on Windows. | |
573 | ||
574 | ##### `http.ssl-version` | |
575 | * Type: string or min/max table | |
576 | * Default: none | |
577 | * Environment: `CARGO_HTTP_SSL_VERSION` | |
578 | ||
579 | This sets the minimum TLS version to use. It takes a string, with one of the | |
580 | possible values of "default", "tlsv1", "tlsv1.0", "tlsv1.1", "tlsv1.2", or | |
581 | "tlsv1.3". | |
582 | ||
583 | This may alternatively take a table with two keys, `min` and `max`, which each | |
584 | take a string value of the same kind that specifies the minimum and maximum | |
585 | range of TLS versions to use. | |
586 | ||
587 | The default is a minimum version of "tlsv1.0" and a max of the newest version | |
588 | supported on your platform, typically "tlsv1.3". | |
589 | ||
590 | ##### `http.low-speed-limit` | |
591 | * Type: integer | |
592 | * Default: 10 | |
593 | * Environment: `CARGO_HTTP_LOW_SPEED_LIMIT` | |
594 | ||
595 | This setting controls timeout behavior for slow connections. If the average | |
596 | transfer speed in bytes per second is below the given value for | |
597 | [`http.timeout`](#httptimeout) seconds (default 30 seconds), then the | |
598 | connection is considered too slow and Cargo will abort and retry. | |
599 | ||
600 | ##### `http.multiplexing` | |
601 | * Type: boolean | |
602 | * Default: true | |
603 | * Environment: `CARGO_HTTP_MULTIPLEXING` | |
604 | ||
605 | When `true`, Cargo will attempt to use the HTTP2 protocol with multiplexing. | |
606 | This allows multiple requests to use the same connection, usually improving | |
607 | performance when fetching multiple files. If `false`, Cargo will use HTTP 1.1 | |
608 | without pipelining. | |
609 | ||
610 | ##### `http.user-agent` | |
611 | * Type: string | |
612 | * Default: Cargo's version | |
613 | * Environment: `CARGO_HTTP_USER_AGENT` | |
614 | ||
615 | Specifies a custom user-agent header to use. The default if not specified is a | |
616 | string that includes Cargo's version. | |
617 | ||
618 | #### `[install]` | |
619 | ||
620 | The `[install]` table defines defaults for the [`cargo install`] command. | |
621 | ||
622 | ##### `install.root` | |
623 | * Type: string (path) | |
624 | * Default: Cargo's home directory | |
625 | * Environment: `CARGO_INSTALL_ROOT` | |
626 | ||
627 | Sets the path to the root directory for installing executables for [`cargo | |
628 | install`]. Executables go into a `bin` directory underneath the root. | |
629 | ||
991e5601 | 630 | To track information of installed executables, some extra files, such as |
d54b10f5 | 631 | `.crates.toml` and `.crates2.json`, are also created under this root. |
991e5601 | 632 | |
dd8f7d8d EH |
633 | The default if not specified is Cargo's home directory (default `.cargo` in |
634 | your home directory). | |
635 | ||
636 | Can be overridden with the `--root` command-line option. | |
637 | ||
638 | #### `[net]` | |
639 | ||
640 | The `[net]` table controls networking configuration. | |
641 | ||
642 | ##### `net.retry` | |
643 | * Type: integer | |
644 | * Default: 2 | |
645 | * Environment: `CARGO_NET_RETRY` | |
646 | ||
647 | Number of times to retry possibly spurious network errors. | |
648 | ||
649 | ##### `net.git-fetch-with-cli` | |
650 | * Type: boolean | |
651 | * Default: false | |
652 | * Environment: `CARGO_NET_GIT_FETCH_WITH_CLI` | |
653 | ||
654 | If this is `true`, then Cargo will use the `git` executable to fetch registry | |
655 | indexes and git dependencies. If `false`, then it uses a built-in `git` | |
656 | library. | |
657 | ||
658 | Setting this to `true` can be helpful if you have special authentication | |
5d9eff36 EH |
659 | requirements that Cargo does not support. See [Git |
660 | Authentication](../appendix/git-authentication.md) for more information about | |
661 | setting up git authentication. | |
dd8f7d8d EH |
662 | |
663 | ##### `net.offline` | |
664 | * Type: boolean | |
665 | * Default: false | |
666 | * Environment: `CARGO_NET_OFFLINE` | |
667 | ||
668 | If this is `true`, then Cargo will avoid accessing the network, and attempt to | |
669 | proceed with locally cached data. If `false`, Cargo will access the network as | |
670 | needed, and generate an error if it encounters a network error. | |
671 | ||
672 | Can be overridden with the `--offline` command-line option. | |
673 | ||
1e0d564f JG |
674 | #### `[patch]` |
675 | ||
676 | Just as you can override dependencies using [`[patch]` in | |
677 | `Cargo.toml`](overriding-dependencies.md#the-patch-section), you can | |
678 | override them in the cargo configuration file to apply those patches to | |
679 | any affected build. The format is identical to the one used in | |
680 | `Cargo.toml`. | |
681 | ||
682 | Since `.cargo/config.toml` files are not usually checked into source | |
683 | control, you should prefer patching using `Cargo.toml` where possible to | |
684 | ensure that other developers can compile your crate in their own | |
685 | environments. Patching through cargo configuration files is generally | |
686 | only appropriate when the patch section is automatically generated by an | |
687 | external build tool. | |
688 | ||
689 | If a given dependency is patched both in a cargo configuration file and | |
690 | a `Cargo.toml` file, the patch in the configuration file is used. If | |
691 | multiple configuration files patch the same dependency, standard cargo | |
692 | configuration merging is used, which prefers the value defined closest | |
693 | to the current directory, with `$HOME/.cargo/config.toml` taking the | |
694 | lowest precedence. | |
695 | ||
696 | Relative `path` dependencies in such a `[patch]` section are resolved | |
697 | relative to the configuration file they appear in. | |
698 | ||
8e935d4d EH |
699 | #### `[profile]` |
700 | ||
701 | The `[profile]` table can be used to globally change profile settings, and | |
702 | override settings specified in `Cargo.toml`. It has the same syntax and | |
703 | options as profiles specified in `Cargo.toml`. See the [Profiles chapter] for | |
704 | details about the options. | |
705 | ||
706 | [Profiles chapter]: profiles.md | |
707 | ||
708 | ##### `[profile.<name>.build-override]` | |
709 | * Environment: `CARGO_PROFILE_<name>_BUILD_OVERRIDE_<key>` | |
710 | ||
711 | The build-override table overrides settings for build scripts, proc macros, | |
712 | and their dependencies. It has the same keys as a normal profile. See the | |
713 | [overrides section](profiles.md#overrides) for more details. | |
714 | ||
715 | ##### `[profile.<name>.package.<name>]` | |
716 | * Environment: not supported | |
717 | ||
718 | The package table overrides settings for specific packages. It has the same | |
719 | keys as a normal profile, minus the `panic`, `lto`, and `rpath` settings. See | |
720 | the [overrides section](profiles.md#overrides) for more details. | |
721 | ||
722 | ##### `profile.<name>.codegen-units` | |
723 | * Type: integer | |
724 | * Default: See profile docs. | |
725 | * Environment: `CARGO_PROFILE_<name>_CODEGEN_UNITS` | |
726 | ||
727 | See [codegen-units](profiles.md#codegen-units). | |
728 | ||
729 | ##### `profile.<name>.debug` | |
730 | * Type: integer or boolean | |
731 | * Default: See profile docs. | |
732 | * Environment: `CARGO_PROFILE_<name>_DEBUG` | |
733 | ||
734 | See [debug](profiles.md#debug). | |
735 | ||
8b3c9adf WL |
736 | ##### `profile.<name>.split-debuginfo` |
737 | * Type: string | |
738 | * Default: See profile docs. | |
739 | * Environment: `CARGO_PROFILE_<name>_SPLIT_DEBUGINFO` | |
740 | ||
741 | See [split-debuginfo](profiles.md#split-debuginfo). | |
742 | ||
8e935d4d EH |
743 | ##### `profile.<name>.debug-assertions` |
744 | * Type: boolean | |
745 | * Default: See profile docs. | |
746 | * Environment: `CARGO_PROFILE_<name>_DEBUG_ASSERTIONS` | |
747 | ||
748 | See [debug-assertions](profiles.md#debug-assertions). | |
749 | ||
750 | ##### `profile.<name>.incremental` | |
751 | * Type: boolean | |
752 | * Default: See profile docs. | |
753 | * Environment: `CARGO_PROFILE_<name>_INCREMENTAL` | |
754 | ||
755 | See [incremental](profiles.md#incremental). | |
756 | ||
757 | ##### `profile.<name>.lto` | |
758 | * Type: string or boolean | |
759 | * Default: See profile docs. | |
760 | * Environment: `CARGO_PROFILE_<name>_LTO` | |
761 | ||
762 | See [lto](profiles.md#lto). | |
763 | ||
764 | ##### `profile.<name>.overflow-checks` | |
765 | * Type: boolean | |
766 | * Default: See profile docs. | |
767 | * Environment: `CARGO_PROFILE_<name>_OVERFLOW_CHECKS` | |
768 | ||
769 | See [overflow-checks](profiles.md#overflow-checks). | |
770 | ||
771 | ##### `profile.<name>.opt-level` | |
772 | * Type: integer or string | |
773 | * Default: See profile docs. | |
774 | * Environment: `CARGO_PROFILE_<name>_OPT_LEVEL` | |
775 | ||
776 | See [opt-level](profiles.md#opt-level). | |
777 | ||
778 | ##### `profile.<name>.panic` | |
779 | * Type: string | |
780 | * default: See profile docs. | |
781 | * Environment: `CARGO_PROFILE_<name>_PANIC` | |
782 | ||
783 | See [panic](profiles.md#panic). | |
784 | ||
785 | ##### `profile.<name>.rpath` | |
786 | * Type: boolean | |
787 | * default: See profile docs. | |
788 | * Environment: `CARGO_PROFILE_<name>_RPATH` | |
789 | ||
790 | See [rpath](profiles.md#rpath). | |
791 | ||
792 | ||
dd8f7d8d EH |
793 | #### `[registries]` |
794 | ||
795 | The `[registries]` table is used for specifying additional [registries]. It | |
796 | consists of a sub-table for each named registry. | |
797 | ||
798 | ##### `registries.<name>.index` | |
799 | * Type: string (url) | |
800 | * Default: none | |
801 | * Environment: `CARGO_REGISTRIES_<name>_INDEX` | |
802 | ||
803 | Specifies the URL of the git index for the registry. | |
804 | ||
805 | ##### `registries.<name>.token` | |
806 | * Type: string | |
807 | * Default: none | |
808 | * Environment: `CARGO_REGISTRIES_<name>_TOKEN` | |
809 | ||
810 | Specifies the authentication token for the given registry. This value should | |
811 | only appear in the [credentials](#credentials) file. This is used for registry | |
812 | commands like [`cargo publish`] that require authentication. | |
813 | ||
814 | Can be overridden with the `--token` command-line option. | |
815 | ||
816 | #### `[registry]` | |
817 | ||
818 | The `[registry]` table controls the default registry used when one is not | |
819 | specified. | |
820 | ||
821 | ##### `registry.index` | |
822 | ||
9d00f9f0 | 823 | This value is no longer accepted and should not be used. |
dd8f7d8d EH |
824 | |
825 | ##### `registry.default` | |
826 | * Type: string | |
827 | * Default: `"crates-io"` | |
828 | * Environment: `CARGO_REGISTRY_DEFAULT` | |
829 | ||
830 | The name of the registry (from the [`registries` table](#registries)) to use | |
831 | by default for registry commands like [`cargo publish`]. | |
832 | ||
833 | Can be overridden with the `--registry` command-line option. | |
834 | ||
835 | ##### `registry.token` | |
836 | * Type: string | |
837 | * Default: none | |
838 | * Environment: `CARGO_REGISTRY_TOKEN` | |
839 | ||
840 | Specifies the authentication token for [crates.io]. This value should only | |
841 | appear in the [credentials](#credentials) file. This is used for registry | |
842 | commands like [`cargo publish`] that require authentication. | |
843 | ||
844 | Can be overridden with the `--token` command-line option. | |
845 | ||
846 | #### `[source]` | |
847 | ||
848 | The `[source]` table defines the registry sources available. See [Source | |
849 | Replacement] for more information. It consists of a sub-table for each named | |
850 | source. A source should only define one kind (directory, registry, | |
851 | local-registry, or git). | |
852 | ||
853 | ##### `source.<name>.replace-with` | |
854 | * Type: string | |
855 | * Default: none | |
856 | * Environment: not supported | |
857 | ||
858 | If set, replace this source with the given named source. | |
859 | ||
860 | ##### `source.<name>.directory` | |
861 | * Type: string (path) | |
862 | * Default: none | |
863 | * Environment: not supported | |
864 | ||
865 | Sets the path to a directory to use as a directory source. | |
866 | ||
867 | ##### `source.<name>.registry` | |
868 | * Type: string (url) | |
869 | * Default: none | |
870 | * Environment: not supported | |
871 | ||
872 | Sets the URL to use for a registry source. | |
873 | ||
874 | ##### `source.<name>.local-registry` | |
875 | * Type: string (path) | |
876 | * Default: none | |
877 | * Environment: not supported | |
878 | ||
879 | Sets the path to a directory to use as a local registry source. | |
880 | ||
881 | ##### `source.<name>.git` | |
882 | * Type: string (url) | |
883 | * Default: none | |
884 | * Environment: not supported | |
885 | ||
886 | Sets the URL to use for a git repository source. | |
887 | ||
888 | ##### `source.<name>.branch` | |
889 | * Type: string | |
890 | * Default: none | |
891 | * Environment: not supported | |
892 | ||
893 | Sets the branch name to use for a git repository. | |
894 | ||
895 | If none of `branch`, `tag`, or `rev` is set, defaults to the `master` branch. | |
896 | ||
897 | ##### `source.<name>.tag` | |
898 | * Type: string | |
899 | * Default: none | |
900 | * Environment: not supported | |
901 | ||
902 | Sets the tag name to use for a git repository. | |
903 | ||
904 | If none of `branch`, `tag`, or `rev` is set, defaults to the `master` branch. | |
905 | ||
906 | ##### `source.<name>.rev` | |
907 | * Type: string | |
908 | * Default: none | |
909 | * Environment: not supported | |
910 | ||
911 | Sets the [revision] to use for a git repository. | |
912 | ||
913 | If none of `branch`, `tag`, or `rev` is set, defaults to the `master` branch. | |
914 | ||
915 | ||
916 | #### `[target]` | |
917 | ||
918 | The `[target]` table is used for specifying settings for specific platform | |
919 | targets. It consists of a sub-table which is either a platform triple or a | |
920 | [`cfg()` expression]. The given values will be used if the target platform | |
921 | matches either the `<triple>` value or the `<cfg>` expression. | |
922 | ||
923 | ```toml | |
924 | [target.thumbv7m-none-eabi] | |
925 | linker = "arm-none-eabi-gcc" | |
926 | runner = "my-emulator" | |
927 | rustflags = ["…", "…"] | |
928 | ||
929 | [target.'cfg(all(target_arch = "arm", target_os = "none"))'] | |
930 | runner = "my-arm-wrapper" | |
931 | rustflags = ["…", "…"] | |
932 | ``` | |
933 | ||
934 | `cfg` values come from those built-in to the compiler (run `rustc --print=cfg` | |
935 | to view), values set by [build scripts], and extra `--cfg` flags passed to | |
936 | `rustc` (such as those defined in `RUSTFLAGS`). Do not try to match on | |
937 | `debug_assertions` or Cargo features like `feature="foo"`. | |
938 | ||
939 | If using a target spec JSON file, the `<triple>` value is the filename stem. | |
940 | For example `--target foo/bar.json` would match `[target.bar]`. | |
941 | ||
942 | ##### `target.<triple>.ar` | |
943 | ||
944 | This option is deprecated and unused. | |
945 | ||
946 | ##### `target.<triple>.linker` | |
947 | * Type: string (program path) | |
948 | * Default: none | |
949 | * Environment: `CARGO_TARGET_<triple>_LINKER` | |
950 | ||
951 | Specifies the linker which is passed to `rustc` (via [`-C linker`]) when the | |
952 | `<triple>` is being compiled for. By default, the linker is not overridden. | |
953 | ||
954 | ##### `target.<triple>.runner` | |
58694812 | 955 | * Type: string or array of strings ([program path with args]) |
dd8f7d8d EH |
956 | * Default: none |
957 | * Environment: `CARGO_TARGET_<triple>_RUNNER` | |
958 | ||
959 | If a runner is provided, executables for the target `<triple>` will be | |
960 | executed by invoking the specified runner with the actual executable passed as | |
961 | an argument. This applies to [`cargo run`], [`cargo test`] and [`cargo bench`] | |
962 | commands. By default, compiled executables are executed directly. | |
963 | ||
dd8f7d8d EH |
964 | ##### `target.<cfg>.runner` |
965 | ||
966 | This is similar to the [target runner](#targettriplerunner), but using | |
967 | a [`cfg()` expression]. If both a `<triple>` and `<cfg>` runner match, | |
968 | the `<triple>` will take precedence. It is an error if more than one | |
969 | `<cfg>` runner matches the current target. | |
970 | ||
971 | ##### `target.<triple>.rustflags` | |
972 | * Type: string or array of strings | |
973 | * Default: none | |
974 | * Environment: `CARGO_TARGET_<triple>_RUSTFLAGS` | |
975 | ||
976 | Passes a set of custom flags to the compiler for this `<triple>`. The value | |
977 | may be a array of strings or a space-separated string. | |
978 | ||
979 | See [`build.rustflags`](#buildrustflags) for more details on the different | |
980 | ways to specific extra flags. | |
981 | ||
982 | ##### `target.<cfg>.rustflags` | |
983 | ||
984 | This is similar to the [target rustflags](#targettriplerustflags), but | |
985 | using a [`cfg()` expression]. If several `<cfg>` and `<triple>` entries | |
986 | match the current target, the flags are joined together. | |
987 | ||
988 | ##### `target.<triple>.<links>` | |
989 | ||
990 | The links sub-table provides a way to [override a build script]. When | |
991 | specified, the build script for the given `links` library will not be | |
992 | run, and the given values will be used instead. | |
993 | ||
994 | ```toml | |
995 | [target.x86_64-unknown-linux-gnu.foo] | |
996 | rustc-link-lib = ["foo"] | |
997 | rustc-link-search = ["/path/to/foo"] | |
998 | rustc-flags = "-L /some/path" | |
999 | rustc-cfg = ['key="value"'] | |
1000 | rustc-env = {key = "value"} | |
1001 | rustc-cdylib-link-arg = ["…"] | |
1002 | metadata_key1 = "value" | |
1003 | metadata_key2 = "value" | |
1004 | ``` | |
1005 | ||
1006 | #### `[term]` | |
1007 | ||
1008 | The `[term]` table controls terminal output and interaction. | |
1009 | ||
ed9ec388 SJ |
1010 | ##### `term.quiet` |
1011 | * Type: boolean | |
1012 | * Default: false | |
1013 | * Environment: `CARGO_TERM_QUIET` | |
1014 | ||
1015 | Controls whether or not log messages are displayed by Cargo. | |
1016 | ||
1017 | Specifying the `--quiet` flag will override and force quiet output. | |
1018 | Specifying the `--verbose` flag will override and disable quiet output. | |
1019 | ||
dd8f7d8d EH |
1020 | ##### `term.verbose` |
1021 | * Type: boolean | |
1022 | * Default: false | |
1023 | * Environment: `CARGO_TERM_VERBOSE` | |
1024 | ||
1025 | Controls whether or not extra detailed messages are displayed by Cargo. | |
1026 | ||
1027 | Specifying the `--quiet` flag will override and disable verbose output. | |
1028 | Specifying the `--verbose` flag will override and force verbose output. | |
1029 | ||
1030 | ##### `term.color` | |
1031 | * Type: string | |
1032 | * Default: "auto" | |
1033 | * Environment: `CARGO_TERM_COLOR` | |
1034 | ||
1035 | Controls whether or not colored output is used in the terminal. Possible values: | |
1036 | ||
1037 | * `auto` (default): Automatically detect if color support is available on the | |
1038 | terminal. | |
1039 | * `always`: Always display colors. | |
1040 | * `never`: Never display colors. | |
1041 | ||
1042 | Can be overridden with the `--color` command-line option. | |
1043 | ||
d649c661 | 1044 | ##### `term.progress.when` |
1045 | * Type: string | |
1046 | * Default: "auto" | |
1047 | * Environment: `CARGO_TERM_PROGRESS_WHEN` | |
1048 | ||
1049 | Controls whether or not progress bar is shown in the terminal. Possible values: | |
1050 | ||
1051 | * `auto` (default): Intelligently guess whether to show progress bar. | |
1052 | * `always`: Always show progress bar. | |
1053 | * `never`: Never show progress bar. | |
1054 | ||
1055 | ##### `term.progress.width` | |
1056 | * Type: integer | |
1057 | * Default: none | |
1058 | * Environment: `CARGO_TERM_PROGRESS_WIDTH` | |
1059 | ||
1060 | Sets the width for progress bar. | |
dd8f7d8d EH |
1061 | |
1062 | [`cargo bench`]: ../commands/cargo-bench.md | |
b119b891 | 1063 | [`cargo login`]: ../commands/cargo-login.md |
e840c8e8 | 1064 | [`cargo doc`]: ../commands/cargo-doc.md |
dd8f7d8d | 1065 | [`cargo new`]: ../commands/cargo-new.md |
b119b891 | 1066 | [`cargo publish`]: ../commands/cargo-publish.md |
dd8f7d8d EH |
1067 | [`cargo run`]: ../commands/cargo-run.md |
1068 | [`cargo rustc`]: ../commands/cargo-rustc.md | |
1069 | [`cargo test`]: ../commands/cargo-test.md | |
1070 | [`cargo rustdoc`]: ../commands/cargo-rustdoc.md | |
1071 | [`cargo install`]: ../commands/cargo-install.md | |
b119b891 | 1072 | [env]: environment-variables.md |
dd8f7d8d EH |
1073 | [`cfg()` expression]: ../../reference/conditional-compilation.html |
1074 | [build scripts]: build-scripts.md | |
1075 | [`-C linker`]: ../../rustc/codegen-options/index.md#linker | |
1076 | [override a build script]: build-scripts.md#overriding-build-scripts | |
a133f25c | 1077 | [toml]: https://toml.io/ |
dd8f7d8d | 1078 | [incremental compilation]: profiles.md#incremental |
1c44404e | 1079 | [program path with args]: #executable-paths-with-arguments |
3302a206 | 1080 | [libcurl format]: https://everything.curl.dev/libcurl/proxies#proxy-types |
dd8f7d8d EH |
1081 | [source replacement]: source-replacement.md |
1082 | [revision]: https://git-scm.com/docs/gitrevisions | |
1083 | [registries]: registries.md | |
1084 | [crates.io]: https://crates.io/ |