<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<meta name="generator" content="rustdoc">
<title>Configuration</title>
<link rel="stylesheet" type="text/css" href="stylesheets/normalize.css">
<link rel="stylesheet" type="text/css" href="stylesheets/all.css">
<link rel="stylesheet" type="text/css" href="stylesheets/prism.css">
<script src="https://code.jquery.com/jquery-2.1.1.min.js"></script>
<link rel="icon" type="image/x-icon" href="favicon.ico">
</head>
<body class="rustdoc">
<!--[if lte IE 8]>
<div class="warning">
This old browser is unsupported and will most likely display funky
things.
</div>
<![endif]-->
<a href='https://github.com/rust-lang/cargo' class='fork-me'>
<img src='images/forkme.png'/>
</a>
<div id="header">
<a href='https://crates.io' class='logo'>
<img id="logo" height=100 width=100 src='images/Cargo-Logo-Small.png'/>
</a>
<a href="index.html">
<h1>CARGO</h1>
</a>
<div class="search">
<form action="https://crates.io/search"
method="GET">
<input name="q" class="search" placeholder="Search crates" type="text"/>
</form>
</div>
<div class="nav">
<a href='https://crates.io/crates'>Browse All Crates</a>
<span class='sep'>|</span>
<div class="dropdown-container">
<button class="dropdown">
Docs
<span class="arrow"></span>
</button>
<!-- Sync this list with
https://github.com/rust-lang/crates.io/blob/master/app/templates/application.hbs
and with Makefile.in in this repository -->
<ul id="current-user-links" class="dropdown" data-bindattr-503="503">
<li><a href='index.html'>Getting Started</a></li>
<li><a href='guide.html'>Guide</a></li>
<li><a href='specifying-dependencies.html'>Specifying Dependencies</a></li>
<li><a href='crates-io.html'>Publishing on crates.io</a></li>
<li><a href='faq.html'>FAQ</a></li>
<li><a href='manifest.html'>Cargo.toml Format</a></li>
<li><a href='build-script.html'>Build Scripts</a></li>
<li><a href='config.html'>Configuration</a></li>
<li><a href='pkgid-spec.html'>Package ID specs</a></li>
<li><a href='environment-variables.html'>Environment Variables</a></li>
<li><a href='source-replacement.html'>Source Replacement</a></li>
<li><a href='external-tools.html'>External Tools</a></li>
<li><a href='policies.html'>Policies</a></li>
</ul>
</div>
</div>
</div>
<main>
<h1 class="title">Configuration</h1>
<p>This document will explain how Cargo’s configuration system works, as well as
available keys or configuration. For configuration of a project through its
manifest, see the <a href="manifest.html">manifest format</a>.</p>
<h1 id='hierarchical-structure' class='section-header'><a href='#hierarchical-structure'>Hierarchical structure</a></h1>
<p>Cargo allows to have local configuration for a particular project or global
configuration (like git). Cargo also extends this ability to a hierarchical
strategy. If, for example, Cargo were invoked in <code>/home/foo/bar/baz</code>, then the
following configuration files would be probed for:</p>
<ul>
<li><code>/home/foo/bar/baz/.cargo/config</code></li>
<li><code>/home/foo/bar/.cargo/config</code></li>
<li><code>/home/foo/.cargo/config</code></li>
<li><code>/home/.cargo/config</code></li>
<li><code>/.cargo/config</code></li>
</ul>
<p>With this structure you can specify local configuration per-project, and even
possibly check it into version control. You can also specify personal default
with a configuration file in your home directory.</p>
<h1 id='configuration-format' class='section-header'><a href='#configuration-format'>Configuration format</a></h1>
<p>All configuration is currently in the <a href="https://github.com/toml-lang/toml">TOML format</a> (like the manifest),
with simple key-value pairs inside of sections (tables) which all get merged
together.</p>
<h1 id='configuration-keys' class='section-header'><a href='#configuration-keys'>Configuration keys</a></h1>
<p>All of the following keys are optional, and their defaults are listed as their
value unless otherwise noted.</p>
<p>Key values that specify a tool may be given as an absolute path, a relative path
or as a pathless tool name. Absolute paths and pathless tool names are used as
given. Relative paths are resolved relative to the parent directory of the
<code>.cargo</code> directory of the config file that the value resides within.</p>
<pre><code class="language-toml"># An array of paths to local repositories which are to be used as overrides for
# dependencies. For more information see the Specifying Dependencies guide.
paths = ["/path/to/override"]
[cargo-new]
# This is your name/email to place in the `authors` section of a new Cargo.toml
# that is generated. If not present, then `git` will be probed, and if that is
# not present then `$USER` and `$EMAIL` will be used.
name = "..."
email = "..."
# By default `cargo new` will initialize a new Git repository. This key can be
# set to `hg` to create a Mercurial repository, or `none` to disable this
# behavior.
vcs = "none"
# For the following sections, $triple refers to any valid target triple, not the
# literal string "$triple", and it will apply whenever that target triple is
# being compiled to. 'cfg(...)' refers to the Rust-like `#[cfg]` syntax for
# conditional compilation.
[target.$triple]
# This is the linker which is passed to rustc (via `-C linker=`) when the `$triple`
# is being compiled for. By default this flag is not passed to the compiler.
linker = ".."
# Same but for the library archiver which is passed to rustc via `-C ar=`.
ar = ".."
# If a runner is provided, compiled targets for the `$triple` will be executed
# by invoking the specified runner executable with actual target as first argument.
# This applies to `cargo run`, `cargo test` and `cargo bench` commands.
# By default compiled targets are executed directly.
runner = ".."
# custom flags to pass to all compiler invocations that target $triple
# this value overrides build.rustflags when both are present
rustflags = ["..", ".."]
[target.'cfg(...)']
# Similar for the $triple configuration, but using the `cfg` syntax.
# If several `cfg` and $triple targets are candidates, then the rustflags
# are concatenated. The `cfg` syntax only applies to rustflags, and not to
# linker.
rustflags = ["..", ".."]
# Configuration keys related to the registry
[registry]
index = "..." # URL of the registry index (defaults to the central repository)
token = "..." # Access token (found on the central repo’s website)
[http]
proxy = "host:port" # HTTP proxy to use for HTTP requests (defaults to none)
# in libcurl format, e.g. "socks5h://host:port"
timeout = 60000 # Timeout for each HTTP request, in milliseconds
cainfo = "cert.pem" # Path to Certificate Authority (CA) bundle (optional)
check-revoke = true # Indicates whether SSL certs are checked for revocation
[build]
jobs = 1 # number of parallel jobs, defaults to # of CPUs
rustc = "rustc" # the rust compiler tool
rustdoc = "rustdoc" # the doc generator tool
target = "triple" # build for the target triple
target-dir = "target" # path of where to place all generated artifacts
rustflags = ["..", ".."] # custom flags to pass to all compiler invocations
[term]
verbose = false # whether cargo provides verbose output
color = 'auto' # whether cargo colorizes output
# Network configuration
[net]
retry = 2 # number of times a network call will automatically retried
# Alias cargo commands. The first 3 aliases are built in. If your
# command requires grouped whitespace use the list format.
[alias]
b = "build"
t = "test"
r = "run"
rr = "run --release"
space_example = ["run", "--release", "--", "\"command list\""]
</code></pre>
<h1 id='environment-variables' class='section-header'><a href='#environment-variables'>Environment variables</a></h1>
<p>Cargo can also be configured through environment variables in addition to the
TOML syntax above. For each configuration key above of the form <code>foo.bar</code> the
environment variable <code>CARGO_FOO_BAR</code> can also be used to define the value. For
example the <code>build.jobs</code> key can also be defined by <code>CARGO_BUILD_JOBS</code>.</p>
<p>Environment variables will take precedent over TOML configuration, and currently
only integer, boolean, and string keys are supported to be defined by
environment variables.</p>
<p>In addition to the system above, Cargo recognizes a few other specific
<a href="environment-variables.html">environment variables</a>.</p>
</main>
<footer>
<a href='index.html'>Install</a>
<span class='sep'>|</span>
<a href='index.html'>Getting Started</a>
<span class='sep'>|</span>
<a href='guide.html'>Guide</a>
</footer>
<script type='text/javascript' src='javascripts/prism.js'></script>
<script type='text/javascript' src='javascripts/all.js'></script>
</body>
</html>
