<!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>