]>
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 | |
271860a9 JG |
15 | * `/projects/foo/bar/baz/.cargo/config` |
16 | * `/projects/foo/bar/.cargo/config` | |
17 | * `/projects/foo/.cargo/config` | |
18 | * `/projects/.cargo/config` | |
4d590f95 | 19 | * `/.cargo/config` |
dd8f7d8d EH |
20 | * `$CARGO_HOME/config` which defaults to: |
21 | * Windows: `%USERPROFILE%\.cargo\config` | |
22 | * Unix: `$HOME/.cargo/config` | |
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 | |
dd8f7d8d | 33 | ### Configuration format |
4d590f95 | 34 | |
dd8f7d8d EH |
35 | Configuration files are written in the [TOML format][toml] (like the |
36 | manifest), with simple key-value pairs inside of sections (tables). The | |
37 | following is a quick overview of all settings, with detailed descriptions | |
38 | found below. | |
4d590f95 BE |
39 | |
40 | ```toml | |
dd8f7d8d | 41 | paths = ["/path/to/override"] # path dependency overrides |
4d590f95 | 42 | |
dd8f7d8d EH |
43 | [alias] # command aliases |
44 | b = "build" | |
45 | c = "check" | |
46 | t = "test" | |
47 | r = "run" | |
48 | rr = "run --release" | |
49 | space_example = ["run", "--release", "--", "\"command list\""] | |
ba375813 | 50 | |
4d590f95 BE |
51 | [build] |
52 | jobs = 1 # number of parallel jobs, defaults to # of CPUs | |
53 | rustc = "rustc" # the rust compiler tool | |
dd8f7d8d | 54 | rustc-wrapper = "…" # run this wrapper instead of `rustc` |
4d590f95 | 55 | rustdoc = "rustdoc" # the doc generator tool |
01421ef2 | 56 | target = "triple" # build for the target triple (ignored by `cargo install`) |
4d590f95 | 57 | target-dir = "target" # path of where to place all generated artifacts |
dd8f7d8d EH |
58 | rustflags = ["…", "…"] # custom flags to pass to all compiler invocations |
59 | rustdocflags = ["…", "…"] # custom flags to pass to rustdoc | |
2bfcb2f9 | 60 | incremental = true # whether or not to enable incremental compilation |
dd8f7d8d EH |
61 | dep-info-basedir = "…" # path for the base directory for targets in depfiles |
62 | pipelining = true # rustc pipelining | |
4d590f95 | 63 | |
dd8f7d8d EH |
64 | [cargo-new] |
65 | name = "Your Name" # name to use in `authors` field | |
66 | email = "you@example.com" # email address to use in `authors` field | |
67 | vcs = "none" # VCS to use ('git', 'hg', 'pijul', 'fossil', 'none') | |
68 | ||
69 | [http] | |
70 | debug = false # HTTP debugging | |
71 | proxy = "host:port" # HTTP proxy in libcurl format | |
72 | ssl-version = "tlsv1.3" # TLS version to use | |
73 | ssl-version.max = "tlsv1.3" # maximum TLS version | |
74 | ssl-version.min = "tlsv1.1" # minimum TLS version | |
75 | timeout = 30 # timeout for each HTTP request, in seconds | |
76 | low-speed-limit = 10 # network timeout threshold (bytes/sec) | |
77 | cainfo = "cert.pem" # path to Certificate Authority (CA) bundle | |
78 | check-revoke = true # check for SSL certificate revocation | |
79 | multiplexing = true # HTTP/2 multiplexing | |
80 | user-agent = "…" # the user-agent header | |
81 | ||
82 | [install] | |
83 | root = "/some/path" # `cargo install` destination directory | |
4d590f95 | 84 | |
4d590f95 | 85 | [net] |
dd8f7d8d EH |
86 | retry = 2 # network retries |
87 | git-fetch-with-cli = true # use the `git` executable for git operations | |
88 | offline = false # do not access the network | |
4d590f95 | 89 | |
dd8f7d8d EH |
90 | [registries.<name>] # registries other than crates.io |
91 | index = "…" # URL of the registry index | |
92 | token = "…" # authentication token for the registry | |
93 | ||
94 | [registry] | |
95 | default = "…" # name of the default registry | |
96 | token = "…" # authentication token for crates.io | |
97 | ||
98 | [source.<name>] # source definition and replacement | |
99 | replace-with = "…" # replace this source with the given named source | |
100 | directory = "…" # path to a directory source | |
101 | registry = "…" # URL to a registry source | |
102 | local-registry = "…" # path to a local registry source | |
103 | git = "…" # URL of a git repository source | |
104 | branch = "…" # branch name for the git repository | |
105 | tag = "…" # tag name for the git repository | |
106 | rev = "…" # revision for the git repository | |
107 | ||
108 | [target.<triple>] | |
109 | linker = "…" # linker to use | |
110 | runner = "…" # wrapper to run executables | |
111 | rustflags = ["…", "…"] # custom flags for `rustc` | |
112 | ||
113 | [target.<cfg>] | |
114 | runner = "…" # wrapper to run executables | |
115 | rustflags = ["…", "…"] # custom flags for `rustc` | |
116 | ||
117 | [target.<triple>.<links>] # `links` build script override | |
118 | rustc-link-lib = ["foo"] | |
119 | rustc-link-search = ["/path/to/foo"] | |
120 | rustc-flags = ["-L", "/some/path"] | |
121 | rustc-cfg = ['key="value"'] | |
122 | rustc-env = {key = "value"} | |
123 | rustc-cdylib-link-arg = ["…"] | |
124 | metadata_key1 = "value" | |
125 | metadata_key2 = "value" | |
126 | ||
127 | [term] | |
128 | verbose = false # whether cargo provides verbose output | |
129 | color = 'auto' # whether cargo colorizes output | |
4d590f95 BE |
130 | ``` |
131 | ||
132 | ### Environment variables | |
133 | ||
134 | Cargo can also be configured through environment variables in addition to the | |
dd8f7d8d EH |
135 | TOML configuration files. For each configuration key of the form `foo.bar` the |
136 | environment variable `CARGO_FOO_BAR` can also be used to define the value. | |
137 | Keys are converted to uppercase, dots and dashes are converted to underscores. | |
138 | For example the `target.x86_64-unknown-linux-gnu.runner` key can also be | |
139 | defined by the `CARGO_TARGET_X86_64_UNKNOWN_LINUX_GNU_RUNNER` environment | |
140 | variable. | |
141 | ||
142 | Environment variables will take precedence over TOML configuration files. | |
143 | Currently only integer, boolean, string and some array values are supported to | |
144 | be defined by environment variables. Descriptions below indicate which keys | |
145 | support environment variables. | |
4d590f95 BE |
146 | |
147 | In addition to the system above, Cargo recognizes a few other specific | |
148 | [environment variables][env]. | |
149 | ||
dd8f7d8d EH |
150 | ### Config-relative paths |
151 | ||
152 | Paths in config files may be absolute, relative, or a bare name without any | |
153 | path separators. Paths for executables without a path separator will use the | |
154 | `PATH` environment variable to search for the executable. Paths for | |
155 | non-executables will be relative to where the config value is defined. For | |
156 | config files, that is relative to the parent directory of the `.cargo` | |
157 | directory where the value was defined. For environment variables it is | |
158 | relative to the current working directory. | |
159 | ||
160 | ```toml | |
161 | # Relative path examples. | |
162 | ||
163 | [target.x86_64-unknown-linux-gnu] | |
164 | runner = "foo" # Searches `PATH` for `foo`. | |
165 | ||
166 | [source.vendored-sources] | |
167 | # Directory is relative to the parent where `.cargo/config` is located. | |
168 | # For example, `/my/project/.cargo/config` would result in `/my/project/vendor`. | |
169 | directory = "vendor" | |
170 | ``` | |
171 | ||
737382d7 EH |
172 | ### Credentials |
173 | ||
174 | Configuration values with sensitive information are stored in the | |
175 | `$CARGO_HOME/credentials` file. This file is automatically created and updated | |
176 | by [`cargo login`]. It follows the same format as Cargo config files. | |
177 | ||
178 | ```toml | |
179 | [registry] | |
dd8f7d8d | 180 | token = "…" # Access token for crates.io |
737382d7 | 181 | |
dd8f7d8d EH |
182 | [registries.<name>] |
183 | token = "…" # Access token for the named registry | |
737382d7 EH |
184 | ``` |
185 | ||
186 | Tokens are used by some Cargo commands such as [`cargo publish`] for | |
187 | authenticating with remote registries. Care should be taken to protect the | |
188 | tokens and to keep them secret. | |
189 | ||
190 | As with most other config values, tokens may be specified with environment | |
dd8f7d8d | 191 | variables. The token for [crates.io] may be specified with the |
737382d7 EH |
192 | `CARGO_REGISTRY_TOKEN` environment variable. Tokens for other registries may |
193 | be specified with environment variables of the form | |
dd8f7d8d EH |
194 | `CARGO_REGISTRIES_<name>_TOKEN` where `<name>` is the name of the registry in |
195 | all capital letters. | |
196 | ||
197 | ### Configuration keys | |
198 | ||
199 | This section documents all configuration keys. The description for keys with | |
200 | variable parts are annotated with angled brackets like `target.<triple>` where | |
201 | the `<triple>` part can be any target triple like | |
202 | `target.x86_64-pc-windows-msvc`. | |
203 | ||
204 | #### `paths` | |
205 | * Type: array of strings (paths) | |
206 | * Default: none | |
207 | * Environment: not supported | |
208 | ||
209 | An array of paths to local packages which are to be used as overrides for | |
d1d08378 EH |
210 | dependencies. For more information see the [Overriding Dependencies |
211 | guide](overriding-dependencies.md#paths-overrides). | |
dd8f7d8d EH |
212 | |
213 | #### `[alias]` | |
214 | * Type: string or array of strings | |
215 | * Default: see below | |
216 | * Environment: `CARGO_ALIAS_<name>` | |
217 | ||
218 | The `[alias]` table defines CLI command aliases. For example, running `cargo | |
219 | b` is an alias for running `cargo build`. Each key in the table is the | |
220 | subcommand, and the value is the actual command to run. The value may be an | |
221 | array of strings, where the first element is the command and the following are | |
222 | arguments. It may also be a string, which will be split on spaces into | |
223 | subcommand and arguments. The following aliases are built-in to Cargo: | |
224 | ||
225 | ```toml | |
226 | [alias] | |
227 | b = "build" | |
228 | c = "check" | |
229 | t = "test" | |
230 | r = "run" | |
231 | ``` | |
232 | ||
233 | Aliases are not allowed to redefine existing built-in commands. | |
234 | ||
235 | #### `[build]` | |
236 | ||
237 | The `[build]` table controls build-time operations and compiler settings. | |
238 | ||
239 | ##### `build.jobs` | |
240 | * Type: integer | |
241 | * Default: number of logical CPUs | |
242 | * Environment: `CARGO_BUILD_JOBS` | |
243 | ||
244 | Sets the maximum number of compiler processes to run in parallel. | |
245 | ||
246 | Can be overridden with the `--jobs` CLI option. | |
247 | ||
248 | ##### `build.rustc` | |
249 | * Type: string (program path) | |
250 | * Default: "rustc" | |
251 | * Environment: `CARGO_BUILD_RUSTC` or `RUSTC` | |
252 | ||
253 | Sets the executable to use for `rustc`. | |
254 | ||
255 | ##### `build.rustc-wrapper` | |
256 | * Type: string (program path) | |
257 | * Default: none | |
258 | * Environment: `CARGO_BUILD_RUSTC_WRAPPER` or `RUSTC_WRAPPER` | |
259 | ||
260 | Sets a wrapper to execute instead of `rustc`. The first argument passed to the | |
261 | wrapper is the path to the actual `rustc`. | |
262 | ||
263 | ##### `build.rustdoc` | |
264 | * Type: string (program path) | |
265 | * Default: "rustdoc" | |
266 | * Environment: `CARGO_BUILD_RUSTDOC` or `RUSTDOC` | |
267 | ||
268 | Sets the executable to use for `rustdoc`. | |
269 | ||
270 | ##### `build.target` | |
271 | * Type: string | |
272 | * Default: host platform | |
273 | * Environment: `CARGO_BUILD_TARGET` | |
274 | ||
275 | The default target platform triple to compile to. | |
276 | ||
277 | This may also be a relative path to a `.json` target spec file. | |
278 | ||
279 | Can be overridden with the `--target` CLI option. | |
280 | ||
281 | ##### `build.target-dir` | |
282 | * Type: string (path) | |
283 | * Default: "target" | |
284 | * Environment: `CARGO_BUILD_TARGET_DIR` or `CARGO_TARGET_DIR` | |
285 | ||
286 | The path to where all compiler output is placed. The default if not specified | |
287 | is a directory named `target` located at the root of the workspace. | |
288 | ||
289 | Can be overridden with the `--target-dir` CLI option. | |
290 | ||
291 | ##### `build.rustflags` | |
292 | * Type: string or array of strings | |
293 | * Default: none | |
294 | * Environment: `CARGO_BUILD_RUSTFLAGS` or `RUSTFLAGS` | |
295 | ||
296 | Extra command-line flags to pass to `rustc`. The value may be a array of | |
297 | strings or a space-separated string. | |
298 | ||
299 | There are three mutually exclusive sources of extra flags. They are checked in | |
300 | order, with the first one being used: | |
301 | ||
302 | 1. `RUSTFLAGS` environment variable. | |
303 | 2. All matching `target.<triple>.rustflags` and `target.<cfg>.rustflags` | |
304 | config entries joined together. | |
305 | 3. `build.rustflags` config value. | |
306 | ||
307 | Additional flags may also be passed with the [`cargo rustc`] command. | |
308 | ||
309 | If the `--target` flag (or [`build.target`](#buildtarget)) is used, then the | |
310 | flags will only be passed to the compiler for the target. Things being built | |
311 | for the host, such as build scripts or proc macros, will not receive the args. | |
312 | Without `--target`, the flags will be passed to all compiler invocations | |
313 | (including build scripts and proc macros) because dependencies are shared. If | |
314 | you have args that you do not want to pass to build scripts or proc macros and | |
315 | are building for the host, pass `--target` with the host triple. | |
316 | ||
317 | ##### `build.rustdocflags` | |
318 | * Type: string or array of strings | |
319 | * Default: none | |
320 | * Environment: `CARGO_BUILD_RUSTDOCFLAGS` or `RUSTDOCFLAGS` | |
321 | ||
322 | Extra command-line flags to pass to `rustdoc`. The value may be a array of | |
323 | strings or a space-separated string. | |
324 | ||
325 | There are two mutually exclusive sources of extra flags. They are checked in | |
326 | order, with the first one being used: | |
327 | ||
328 | 1. `RUSTDOCFLAGS` environment variable. | |
329 | 2. `build.rustdocflags` config value. | |
330 | ||
331 | Additional flags may also be passed with the [`cargo rustdoc`] command. | |
332 | ||
333 | ##### `build.incremental` | |
334 | * Type: bool | |
335 | * Default: from profile | |
336 | * Environment: `CARGO_BUILD_INCREMENTAL` or `CARGO_INCREMENTAL` | |
337 | ||
338 | Whether or not to perform [incremental compilation]. The default if not set is | |
339 | to use the value from the [profile]. Otherwise this overrides the setting of | |
340 | all profiles. | |
341 | ||
342 | The `CARGO_INCREMENTAL` environment variable can be set to `1` to force enable | |
343 | incremental compilation for all profiles, or `0` to disable it. This env var | |
344 | overrides the config setting. | |
345 | ||
346 | ##### `build.dep-info-basedir` | |
347 | * Type: string (path) | |
348 | * Default: none | |
349 | * Environment: `CARGO_BUILD_DEP_INFO_BASEDIR` | |
350 | ||
765c80da EH |
351 | Strips the given path prefix from [dep |
352 | info](../guide/build-cache.md#dep-info-files) file paths. This config setting | |
353 | is intended to convert absolute paths to relative paths for tools that require | |
354 | relative paths. | |
dd8f7d8d EH |
355 | |
356 | The setting itself is a config-relative path. So, for example, a value of | |
357 | `"."` would strip all paths starting with the parent directory of the `.cargo` | |
358 | directory. | |
359 | ||
360 | ##### `build.pipelining` | |
361 | * Type: boolean | |
362 | * Default: true | |
363 | * Environment: `CARGO_BUILD_PIPELINING` | |
364 | ||
365 | Controls whether or not build pipelining is used. This allows Cargo to | |
366 | schedule overlapping invocations of `rustc` in parallel when possible. | |
367 | ||
368 | #### `[cargo-new]` | |
369 | ||
370 | The `[cargo-new]` table defines defaults for the [`cargo new`] command. | |
371 | ||
372 | ##### `cargo-new.name` | |
373 | * Type: string | |
374 | * Default: from environment | |
375 | * Environment: `CARGO_NAME` or `CARGO_CARGO_NEW_NAME` | |
376 | ||
377 | Defines the name to use in the `authors` field when creating a new | |
378 | `Cargo.toml` file. If not specified in the config, Cargo searches the | |
379 | environment or your `git` configuration as described in the [`cargo new`] | |
380 | documentation. | |
381 | ||
382 | ##### `cargo-new.email` | |
383 | * Type: string | |
384 | * Default: from environment | |
385 | * Environment: `CARGO_EMAIL` or `CARGO_CARGO_NEW_EMAIL` | |
386 | ||
387 | Defines the email address used in the `authors` field when creating a new | |
388 | `Cargo.toml` file. If not specified in the config, Cargo searches the | |
389 | environment or your `git` configuration as described in the [`cargo new`] | |
390 | documentation. The `email` value may be set to an empty string to prevent | |
391 | Cargo from placing an address in the authors field. | |
392 | ||
393 | ##### `cargo-new.vcs` | |
394 | * Type: string | |
395 | * Default: "git" or "none" | |
396 | * Environment: `CARGO_CARGO_NEW_VCS` | |
397 | ||
398 | Specifies the source control system to use for initializing a new repository. | |
399 | Valid values are `git`, `hg` (for Mercurial), `pijul`, `fossil` or `none` to | |
400 | disable this behavior. Defaults to `git`, or `none` if already inside a VCS | |
401 | repository. Can be overridden with the `--vcs` CLI option. | |
402 | ||
403 | #### `[http]` | |
404 | ||
405 | The `[http]` table defines settings for HTTP behavior. This includes fetching | |
406 | crate dependencies and accessing remote git repositories. | |
407 | ||
408 | ##### `http.debug` | |
409 | * Type: boolean | |
410 | * Default: false | |
411 | * Environment: `CARGO_HTTP_DEBUG` | |
412 | ||
413 | If `true`, enables debugging of HTTP requests. The debug information can be | |
414 | seen by setting the `CARGO_LOG=cargo::ops::registry=debug` environment | |
415 | variable (or use `trace` for even more information). | |
416 | ||
417 | Be wary when posting logs from this output in a public location. The output | |
418 | may include headers with authentication tokens which you don't want to leak! | |
419 | Be sure to review logs before posting them. | |
737382d7 | 420 | |
dd8f7d8d EH |
421 | ##### `http.proxy` |
422 | * Type: string | |
423 | * Default: none | |
424 | * Environment: `CARGO_HTTP_PROXY` or `HTTPS_PROXY` or `https_proxy` or `http_proxy` | |
425 | ||
426 | Sets an HTTP and HTTPS proxy to use. The format is in [libcurl format] as in | |
427 | `[protocol://]host[:port]`. If not set, Cargo will also check the `http.proxy` | |
428 | setting in your global git configuration. If none of those are set, the | |
429 | `HTTPS_PROXY` or `https_proxy` environment variables set the proxy for HTTPS | |
430 | requests, and `http_proxy` sets it for HTTP requests. | |
431 | ||
432 | ##### `http.timeout` | |
433 | * Type: integer | |
434 | * Default: 30 | |
435 | * Environment: `CARGO_HTTP_TIMEOUT` or `HTTP_TIMEOUT` | |
436 | ||
437 | Sets the timeout for each HTTP request, in seconds. | |
438 | ||
439 | ##### `http.cainfo` | |
440 | * Type: string (path) | |
441 | * Default: none | |
442 | * Environment: `CARGO_HTTP_CAINFO` | |
443 | ||
444 | Path to a Certificate Authority (CA) bundle file, used to verify TLS | |
445 | certificates. If not specified, Cargo attempts to use the system certificates. | |
446 | ||
447 | ##### `http.check-revoke` | |
448 | * Type: boolean | |
449 | * Default: true (Windows) false (all others) | |
450 | * Environment: `CARGO_HTTP_CHECK_REVOKE` | |
451 | ||
452 | This determines whether or not TLS certificate revocation checks should be | |
453 | performed. This only works on Windows. | |
454 | ||
455 | ##### `http.ssl-version` | |
456 | * Type: string or min/max table | |
457 | * Default: none | |
458 | * Environment: `CARGO_HTTP_SSL_VERSION` | |
459 | ||
460 | This sets the minimum TLS version to use. It takes a string, with one of the | |
461 | possible values of "default", "tlsv1", "tlsv1.0", "tlsv1.1", "tlsv1.2", or | |
462 | "tlsv1.3". | |
463 | ||
464 | This may alternatively take a table with two keys, `min` and `max`, which each | |
465 | take a string value of the same kind that specifies the minimum and maximum | |
466 | range of TLS versions to use. | |
467 | ||
468 | The default is a minimum version of "tlsv1.0" and a max of the newest version | |
469 | supported on your platform, typically "tlsv1.3". | |
470 | ||
471 | ##### `http.low-speed-limit` | |
472 | * Type: integer | |
473 | * Default: 10 | |
474 | * Environment: `CARGO_HTTP_LOW_SPEED_LIMIT` | |
475 | ||
476 | This setting controls timeout behavior for slow connections. If the average | |
477 | transfer speed in bytes per second is below the given value for | |
478 | [`http.timeout`](#httptimeout) seconds (default 30 seconds), then the | |
479 | connection is considered too slow and Cargo will abort and retry. | |
480 | ||
481 | ##### `http.multiplexing` | |
482 | * Type: boolean | |
483 | * Default: true | |
484 | * Environment: `CARGO_HTTP_MULTIPLEXING` | |
485 | ||
486 | When `true`, Cargo will attempt to use the HTTP2 protocol with multiplexing. | |
487 | This allows multiple requests to use the same connection, usually improving | |
488 | performance when fetching multiple files. If `false`, Cargo will use HTTP 1.1 | |
489 | without pipelining. | |
490 | ||
491 | ##### `http.user-agent` | |
492 | * Type: string | |
493 | * Default: Cargo's version | |
494 | * Environment: `CARGO_HTTP_USER_AGENT` | |
495 | ||
496 | Specifies a custom user-agent header to use. The default if not specified is a | |
497 | string that includes Cargo's version. | |
498 | ||
499 | #### `[install]` | |
500 | ||
501 | The `[install]` table defines defaults for the [`cargo install`] command. | |
502 | ||
503 | ##### `install.root` | |
504 | * Type: string (path) | |
505 | * Default: Cargo's home directory | |
506 | * Environment: `CARGO_INSTALL_ROOT` | |
507 | ||
508 | Sets the path to the root directory for installing executables for [`cargo | |
509 | install`]. Executables go into a `bin` directory underneath the root. | |
510 | ||
511 | The default if not specified is Cargo's home directory (default `.cargo` in | |
512 | your home directory). | |
513 | ||
514 | Can be overridden with the `--root` command-line option. | |
515 | ||
516 | #### `[net]` | |
517 | ||
518 | The `[net]` table controls networking configuration. | |
519 | ||
520 | ##### `net.retry` | |
521 | * Type: integer | |
522 | * Default: 2 | |
523 | * Environment: `CARGO_NET_RETRY` | |
524 | ||
525 | Number of times to retry possibly spurious network errors. | |
526 | ||
527 | ##### `net.git-fetch-with-cli` | |
528 | * Type: boolean | |
529 | * Default: false | |
530 | * Environment: `CARGO_NET_GIT_FETCH_WITH_CLI` | |
531 | ||
532 | If this is `true`, then Cargo will use the `git` executable to fetch registry | |
533 | indexes and git dependencies. If `false`, then it uses a built-in `git` | |
534 | library. | |
535 | ||
536 | Setting this to `true` can be helpful if you have special authentication | |
5d9eff36 EH |
537 | requirements that Cargo does not support. See [Git |
538 | Authentication](../appendix/git-authentication.md) for more information about | |
539 | setting up git authentication. | |
dd8f7d8d EH |
540 | |
541 | ##### `net.offline` | |
542 | * Type: boolean | |
543 | * Default: false | |
544 | * Environment: `CARGO_NET_OFFLINE` | |
545 | ||
546 | If this is `true`, then Cargo will avoid accessing the network, and attempt to | |
547 | proceed with locally cached data. If `false`, Cargo will access the network as | |
548 | needed, and generate an error if it encounters a network error. | |
549 | ||
550 | Can be overridden with the `--offline` command-line option. | |
551 | ||
552 | #### `[registries]` | |
553 | ||
554 | The `[registries]` table is used for specifying additional [registries]. It | |
555 | consists of a sub-table for each named registry. | |
556 | ||
557 | ##### `registries.<name>.index` | |
558 | * Type: string (url) | |
559 | * Default: none | |
560 | * Environment: `CARGO_REGISTRIES_<name>_INDEX` | |
561 | ||
562 | Specifies the URL of the git index for the registry. | |
563 | ||
564 | ##### `registries.<name>.token` | |
565 | * Type: string | |
566 | * Default: none | |
567 | * Environment: `CARGO_REGISTRIES_<name>_TOKEN` | |
568 | ||
569 | Specifies the authentication token for the given registry. This value should | |
570 | only appear in the [credentials](#credentials) file. This is used for registry | |
571 | commands like [`cargo publish`] that require authentication. | |
572 | ||
573 | Can be overridden with the `--token` command-line option. | |
574 | ||
575 | #### `[registry]` | |
576 | ||
577 | The `[registry]` table controls the default registry used when one is not | |
578 | specified. | |
579 | ||
580 | ##### `registry.index` | |
581 | ||
582 | This value is deprecated and should not be used. | |
583 | ||
584 | ##### `registry.default` | |
585 | * Type: string | |
586 | * Default: `"crates-io"` | |
587 | * Environment: `CARGO_REGISTRY_DEFAULT` | |
588 | ||
589 | The name of the registry (from the [`registries` table](#registries)) to use | |
590 | by default for registry commands like [`cargo publish`]. | |
591 | ||
592 | Can be overridden with the `--registry` command-line option. | |
593 | ||
594 | ##### `registry.token` | |
595 | * Type: string | |
596 | * Default: none | |
597 | * Environment: `CARGO_REGISTRY_TOKEN` | |
598 | ||
599 | Specifies the authentication token for [crates.io]. This value should only | |
600 | appear in the [credentials](#credentials) file. This is used for registry | |
601 | commands like [`cargo publish`] that require authentication. | |
602 | ||
603 | Can be overridden with the `--token` command-line option. | |
604 | ||
605 | #### `[source]` | |
606 | ||
607 | The `[source]` table defines the registry sources available. See [Source | |
608 | Replacement] for more information. It consists of a sub-table for each named | |
609 | source. A source should only define one kind (directory, registry, | |
610 | local-registry, or git). | |
611 | ||
612 | ##### `source.<name>.replace-with` | |
613 | * Type: string | |
614 | * Default: none | |
615 | * Environment: not supported | |
616 | ||
617 | If set, replace this source with the given named source. | |
618 | ||
619 | ##### `source.<name>.directory` | |
620 | * Type: string (path) | |
621 | * Default: none | |
622 | * Environment: not supported | |
623 | ||
624 | Sets the path to a directory to use as a directory source. | |
625 | ||
626 | ##### `source.<name>.registry` | |
627 | * Type: string (url) | |
628 | * Default: none | |
629 | * Environment: not supported | |
630 | ||
631 | Sets the URL to use for a registry source. | |
632 | ||
633 | ##### `source.<name>.local-registry` | |
634 | * Type: string (path) | |
635 | * Default: none | |
636 | * Environment: not supported | |
637 | ||
638 | Sets the path to a directory to use as a local registry source. | |
639 | ||
640 | ##### `source.<name>.git` | |
641 | * Type: string (url) | |
642 | * Default: none | |
643 | * Environment: not supported | |
644 | ||
645 | Sets the URL to use for a git repository source. | |
646 | ||
647 | ##### `source.<name>.branch` | |
648 | * Type: string | |
649 | * Default: none | |
650 | * Environment: not supported | |
651 | ||
652 | Sets the branch name to use for a git repository. | |
653 | ||
654 | If none of `branch`, `tag`, or `rev` is set, defaults to the `master` branch. | |
655 | ||
656 | ##### `source.<name>.tag` | |
657 | * Type: string | |
658 | * Default: none | |
659 | * Environment: not supported | |
660 | ||
661 | Sets the tag name to use for a git repository. | |
662 | ||
663 | If none of `branch`, `tag`, or `rev` is set, defaults to the `master` branch. | |
664 | ||
665 | ##### `source.<name>.rev` | |
666 | * Type: string | |
667 | * Default: none | |
668 | * Environment: not supported | |
669 | ||
670 | Sets the [revision] to use for a git repository. | |
671 | ||
672 | If none of `branch`, `tag`, or `rev` is set, defaults to the `master` branch. | |
673 | ||
674 | ||
675 | #### `[target]` | |
676 | ||
677 | The `[target]` table is used for specifying settings for specific platform | |
678 | targets. It consists of a sub-table which is either a platform triple or a | |
679 | [`cfg()` expression]. The given values will be used if the target platform | |
680 | matches either the `<triple>` value or the `<cfg>` expression. | |
681 | ||
682 | ```toml | |
683 | [target.thumbv7m-none-eabi] | |
684 | linker = "arm-none-eabi-gcc" | |
685 | runner = "my-emulator" | |
686 | rustflags = ["…", "…"] | |
687 | ||
688 | [target.'cfg(all(target_arch = "arm", target_os = "none"))'] | |
689 | runner = "my-arm-wrapper" | |
690 | rustflags = ["…", "…"] | |
691 | ``` | |
692 | ||
693 | `cfg` values come from those built-in to the compiler (run `rustc --print=cfg` | |
694 | to view), values set by [build scripts], and extra `--cfg` flags passed to | |
695 | `rustc` (such as those defined in `RUSTFLAGS`). Do not try to match on | |
696 | `debug_assertions` or Cargo features like `feature="foo"`. | |
697 | ||
698 | If using a target spec JSON file, the `<triple>` value is the filename stem. | |
699 | For example `--target foo/bar.json` would match `[target.bar]`. | |
700 | ||
701 | ##### `target.<triple>.ar` | |
702 | ||
703 | This option is deprecated and unused. | |
704 | ||
705 | ##### `target.<triple>.linker` | |
706 | * Type: string (program path) | |
707 | * Default: none | |
708 | * Environment: `CARGO_TARGET_<triple>_LINKER` | |
709 | ||
710 | Specifies the linker which is passed to `rustc` (via [`-C linker`]) when the | |
711 | `<triple>` is being compiled for. By default, the linker is not overridden. | |
712 | ||
713 | ##### `target.<triple>.runner` | |
714 | * Type: string or array of strings (program path and args) | |
715 | * Default: none | |
716 | * Environment: `CARGO_TARGET_<triple>_RUNNER` | |
717 | ||
718 | If a runner is provided, executables for the target `<triple>` will be | |
719 | executed by invoking the specified runner with the actual executable passed as | |
720 | an argument. This applies to [`cargo run`], [`cargo test`] and [`cargo bench`] | |
721 | commands. By default, compiled executables are executed directly. | |
722 | ||
723 | The value may be an array of strings like `['/path/to/program', 'somearg']` or | |
724 | a space-separated string like `'/path/to/program somearg'`. The arguments will | |
725 | be passed to the runner with the executable to run as the last argument. If | |
726 | the runner program does not have path separators, it will search `PATH` for | |
727 | the runner executable. | |
728 | ||
729 | ##### `target.<cfg>.runner` | |
730 | ||
731 | This is similar to the [target runner](#targettriplerunner), but using | |
732 | a [`cfg()` expression]. If both a `<triple>` and `<cfg>` runner match, | |
733 | the `<triple>` will take precedence. It is an error if more than one | |
734 | `<cfg>` runner matches the current target. | |
735 | ||
736 | ##### `target.<triple>.rustflags` | |
737 | * Type: string or array of strings | |
738 | * Default: none | |
739 | * Environment: `CARGO_TARGET_<triple>_RUSTFLAGS` | |
740 | ||
741 | Passes a set of custom flags to the compiler for this `<triple>`. The value | |
742 | may be a array of strings or a space-separated string. | |
743 | ||
744 | See [`build.rustflags`](#buildrustflags) for more details on the different | |
745 | ways to specific extra flags. | |
746 | ||
747 | ##### `target.<cfg>.rustflags` | |
748 | ||
749 | This is similar to the [target rustflags](#targettriplerustflags), but | |
750 | using a [`cfg()` expression]. If several `<cfg>` and `<triple>` entries | |
751 | match the current target, the flags are joined together. | |
752 | ||
753 | ##### `target.<triple>.<links>` | |
754 | ||
755 | The links sub-table provides a way to [override a build script]. When | |
756 | specified, the build script for the given `links` library will not be | |
757 | run, and the given values will be used instead. | |
758 | ||
759 | ```toml | |
760 | [target.x86_64-unknown-linux-gnu.foo] | |
761 | rustc-link-lib = ["foo"] | |
762 | rustc-link-search = ["/path/to/foo"] | |
763 | rustc-flags = "-L /some/path" | |
764 | rustc-cfg = ['key="value"'] | |
765 | rustc-env = {key = "value"} | |
766 | rustc-cdylib-link-arg = ["…"] | |
767 | metadata_key1 = "value" | |
768 | metadata_key2 = "value" | |
769 | ``` | |
770 | ||
771 | #### `[term]` | |
772 | ||
773 | The `[term]` table controls terminal output and interaction. | |
774 | ||
775 | ##### `term.verbose` | |
776 | * Type: boolean | |
777 | * Default: false | |
778 | * Environment: `CARGO_TERM_VERBOSE` | |
779 | ||
780 | Controls whether or not extra detailed messages are displayed by Cargo. | |
781 | ||
782 | Specifying the `--quiet` flag will override and disable verbose output. | |
783 | Specifying the `--verbose` flag will override and force verbose output. | |
784 | ||
785 | ##### `term.color` | |
786 | * Type: string | |
787 | * Default: "auto" | |
788 | * Environment: `CARGO_TERM_COLOR` | |
789 | ||
790 | Controls whether or not colored output is used in the terminal. Possible values: | |
791 | ||
792 | * `auto` (default): Automatically detect if color support is available on the | |
793 | terminal. | |
794 | * `always`: Always display colors. | |
795 | * `never`: Never display colors. | |
796 | ||
797 | Can be overridden with the `--color` command-line option. | |
798 | ||
799 | ||
800 | [`cargo bench`]: ../commands/cargo-bench.md | |
b119b891 | 801 | [`cargo login`]: ../commands/cargo-login.md |
dd8f7d8d | 802 | [`cargo new`]: ../commands/cargo-new.md |
b119b891 | 803 | [`cargo publish`]: ../commands/cargo-publish.md |
dd8f7d8d EH |
804 | [`cargo run`]: ../commands/cargo-run.md |
805 | [`cargo rustc`]: ../commands/cargo-rustc.md | |
806 | [`cargo test`]: ../commands/cargo-test.md | |
807 | [`cargo rustdoc`]: ../commands/cargo-rustdoc.md | |
808 | [`cargo install`]: ../commands/cargo-install.md | |
b119b891 | 809 | [env]: environment-variables.md |
dd8f7d8d EH |
810 | [`cfg()` expression]: ../../reference/conditional-compilation.html |
811 | [build scripts]: build-scripts.md | |
812 | [`-C linker`]: ../../rustc/codegen-options/index.md#linker | |
813 | [override a build script]: build-scripts.md#overriding-build-scripts | |
814 | [toml]: https://github.com/toml-lang/toml | |
815 | [incremental compilation]: profiles.md#incremental | |
816 | [profile]: profiles.md | |
817 | [libcurl format]: https://ec.haxx.se/usingcurl-proxies.html | |
818 | [source replacement]: source-replacement.md | |
819 | [revision]: https://git-scm.com/docs/gitrevisions | |
820 | [registries]: registries.md | |
821 | [crates.io]: https://crates.io/ |