<!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>Environment Variables</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">Environment Variables</h1> <p>Cargo sets and reads a number of environment variables which your code can detect or override. Here is a list of the variables Cargo sets, organized by when it interacts with them:</p> <h1 id='environment-variables-cargo-reads' class='section-header'><a href='#environment-variables-cargo-reads'>Environment variables Cargo reads</a></h1> <p>You can override these environment variables to change Cargo's behavior on your system:</p> <ul> <li><code>CARGO_HOME</code> - Cargo maintains a local cache of the registry index and of git checkouts of crates. By default these are stored under <code>$HOME/.cargo</code>, but this variable overrides the location of this directory. Once a crate is cached it is not removed by the clean command.</li> <li><code>CARGO_TARGET_DIR</code> - Location of where to place all generated artifacts, relative to the current working directory.</li> <li><code>RUSTC</code> - Instead of running <code>rustc</code>, Cargo will execute this specified compiler instead.</li> <li><code>RUSTC_WRAPPER</code> - Instead of simply running <code>rustc</code>, Cargo will execute this specified wrapper instead, passing as its commandline arguments the rustc invocation, with the first argument being rustc.</li> <li><code>RUSTDOC</code> - Instead of running <code>rustdoc</code>, Cargo will execute this specified <code>rustdoc</code> instance instead.</li> <li><code>RUSTDOCFLAGS</code> - A space-separated list of custom flags to pass to all <code>rustdoc</code> invocations that Cargo performs. In contrast with <code>cargo rustdoc</code>, this is useful for passing a flag to <em>all</em> <code>rustdoc</code> instances.</li> <li><code>RUSTFLAGS</code> - A space-separated list of custom flags to pass to all compiler invocations that Cargo performs. In contrast with <code>cargo rustc</code>, this is useful for passing a flag to <em>all</em> compiler instances.</li> </ul> <p>Note that Cargo will also read environment variables for <code>.cargo/config</code> configuration values, as described in <a href="config.html#environment-variables">that documentation</a></p> <h1 id='environment-variables-cargo-sets-for-crates' class='section-header'><a href='#environment-variables-cargo-sets-for-crates'>Environment variables Cargo sets for crates</a></h1> <p>Cargo exposes these environment variables to your crate when it is compiled. Note that this applies for test binaries as well. To get the value of any of these variables in a Rust program, do this:</p> <pre class="rust rust-example-rendered"> <span class="kw">let</span> <span class="ident">version</span> <span class="op">=</span> <span class="macro">env</span><span class="macro">!</span>(<span class="string">"CARGO_PKG_VERSION"</span>);</pre> <p><code>version</code> will now contain the value of <code>CARGO_PKG_VERSION</code>.</p> <ul> <li><code>CARGO</code> - Path to the <code>cargo</code> binary performing the build.</li> <li><code>CARGO_MANIFEST_DIR</code> - The directory containing the manifest of your package.</li> <li><code>CARGO_PKG_VERSION</code> - The full version of your package.</li> <li><code>CARGO_PKG_VERSION_MAJOR</code> - The major version of your package.</li> <li><code>CARGO_PKG_VERSION_MINOR</code> - The minor version of your package.</li> <li><code>CARGO_PKG_VERSION_PATCH</code> - The patch version of your package.</li> <li><code>CARGO_PKG_VERSION_PRE</code> - The pre-release version of your package.</li> <li><code>CARGO_PKG_AUTHORS</code> - Colon separated list of authors from the manifest of your package.</li> <li><code>CARGO_PKG_NAME</code> - The name of your package.</li> <li><code>CARGO_PKG_DESCRIPTION</code> - The description of your package.</li> <li><code>CARGO_PKG_HOMEPAGE</code> - The home page of your package.</li> <li><code>OUT_DIR</code> - If the package has a build script, this is set to the folder where the build script should place its output. See below for more information.</li> </ul> <h1 id='environment-variables-cargo-sets-for-build-scripts' class='section-header'><a href='#environment-variables-cargo-sets-for-build-scripts'>Environment variables Cargo sets for build scripts</a></h1> <p>Cargo sets several environment variables when build scripts are run. Because these variables are not yet set when the build script is compiled, the above example using <code>env!</code> won't work and instead you'll need to retrieve the values when the build script is run:</p> <pre class="rust rust-example-rendered"> <span class="kw">use</span> <span class="ident">std</span>::<span class="ident">env</span>; <span class="kw">let</span> <span class="ident">out_dir</span> <span class="op">=</span> <span class="ident">env</span>::<span class="ident">var</span>(<span class="string">"OUT_DIR"</span>).<span class="ident">unwrap</span>();</pre> <p><code>out_dir</code> will now contain the value of <code>OUT_DIR</code>.</p> <ul> <li><code>CARGO_MANIFEST_DIR</code> - The directory containing the manifest for the package being built (the package containing the build script). Also note that this is the value of the current working directory of the build script when it starts.</li> <li><code>CARGO_MANIFEST_LINKS</code> - the manifest <code>links</code> value.</li> <li><code>CARGO_FEATURE_<name></code> - For each activated feature of the package being built, this environment variable will be present where <code><name></code> is the name of the feature uppercased and having <code>-</code> translated to <code>_</code>.</li> <li><code>CARGO_CFG_<cfg></code> - For each <a href="https://doc.rust-lang.org/reference/attributes.html#conditional-compilation">configuration option</a> of the package being built, this environment variable will contain the value of the configuration, where <code><cfg></code> is the name of the configuration uppercased and having <code>-</code> translated to <code>_</code>. Boolean configurations are present if they are set, and not present otherwise. Configurations with multiple values are joined to a single variable with the values delimited by <code>,</code>.</li> <li><code>OUT_DIR</code> - the folder in which all output should be placed. This folder is inside the build directory for the package being built, and it is unique for the package in question.</li> <li><code>TARGET</code> - the target triple that is being compiled for. Native code should be compiled for this triple. Some more information about target triples can be found in <a href="http://clang.llvm.org/docs/CrossCompilation.html#target-triple">clang’s own documentation</a>.</li> <li><code>HOST</code> - the host triple of the rust compiler.</li> <li><code>NUM_JOBS</code> - the parallelism specified as the top-level parallelism. This can be useful to pass a <code>-j</code> parameter to a system like <code>make</code>. Note that care should be taken when interpreting this environment variable. For historical purposes this is still provided but recent versions of Cargo, for example, do not need to run <code>make -j</code> as it'll automatically happen. Cargo implements its own <a href="http://make.mad-scientist.net/papers/jobserver-implementation/">jobserver</a> and will allow build scripts to inherit this information, so programs compatible with GNU make jobservers will already have appropriately configured parallelism.</li> <li><code>OPT_LEVEL</code>, <code>DEBUG</code> - values of the corresponding variables for the profile currently being built.</li> <li><code>PROFILE</code> - <code>release</code> for release builds, <code>debug</code> for other builds.</li> <li><code>DEP_<name>_<key></code> - For more information about this set of environment variables, see build script documentation about <a href="build-script.html#the-links-manifest-key"><code>links</code></a>.</li> <li><code>RUSTC</code>, <code>RUSTDOC</code> - the compiler and documentation generator that Cargo has resolved to use, passed to the build script so it might use it as well.</li> </ul> <h1 id='environment-variables-cargo-sets-for-3rd-party-subcommands' class='section-header'><a href='#environment-variables-cargo-sets-for-3rd-party-subcommands'>Environment variables Cargo sets for 3rd party subcommands</a></h1> <p>Cargo exposes this environment variable to 3rd party subcommands (ie. programs named <code>cargo-foobar</code> placed in <code>$PATH</code>):</p> <ul> <li><code>CARGO</code> - Path to the <code>cargo</code> binary performing the build.</li> </ul> </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>