<!DOCTYPE HTML>
<html lang="en" class="sidebar-visible no-js">
<head>
<!-- Book generated using mdBook -->
<meta charset="UTF-8">
<title>Configuration - The Cargo Book</title>
<meta content="text/html; charset=utf-8" http-equiv="Content-Type">
<meta name="description" content="">
<meta name="viewport" content="width=device-width, initial-scale=1">
<meta name="theme-color" content="#ffffff" />
<base href="../">
<link rel="stylesheet" href="book.css">
<link href="https://fonts.googleapis.com/css?family=Open+Sans:300italic,400italic,600italic,700italic,800italic,400,300,600,700,800" rel="stylesheet" type="text/css">
<link href="https://fonts.googleapis.com/css?family=Source+Code+Pro:500" rel="stylesheet" type="text/css">
<link rel="shortcut icon" href="favicon.png">
<!-- Font Awesome -->
<link rel="stylesheet" href="_FontAwesome/css/font-awesome.css">
<link rel="stylesheet" href="highlight.css">
<link rel="stylesheet" href="tomorrow-night.css">
<link rel="stylesheet" href="ayu-highlight.css">
<!-- Custom theme stylesheets -->
</head>
<body class="light">
<!-- Work around some values being stored in localStorage wrapped in quotes -->
<script type="text/javascript">
try {
var theme = localStorage.getItem('mdbook-theme');
var sidebar = localStorage.getItem('mdbook-sidebar');
if (theme.startsWith('"') && theme.endsWith('"')) {
localStorage.setItem('mdbook-theme', theme.slice(1, theme.length - 1));
}
if (sidebar.startsWith('"') && sidebar.endsWith('"')) {
localStorage.setItem('mdbook-sidebar', sidebar.slice(1, sidebar.length - 1));
}
} catch (e) { }
</script>
<!-- Set the theme before any content is loaded, prevents flash -->
<script type="text/javascript">
var theme;
try { theme = localStorage.getItem('mdbook-theme'); } catch(e) { }
if (theme === null || theme === undefined) { theme = 'light'; }
document.body.className = theme;
document.querySelector('html').className = theme + ' js';
</script>
<!-- Hide / unhide sidebar before it is displayed -->
<script type="text/javascript">
var html = document.querySelector('html');
var sidebar = 'hidden';
if (document.body.clientWidth >= 1080) {
try { sidebar = localStorage.getItem('mdbook-sidebar'); } catch(e) { }
sidebar = sidebar || 'visible';
}
html.classList.remove('sidebar-visible');
html.classList.add("sidebar-" + sidebar);
</script>
<nav id="sidebar" class="sidebar" aria-label="Table of contents">
<ol class="chapter"><li class="affix"><a href="index.html">Introduction</a></li><li><a href="getting-started/index.html"><strong aria-hidden="true">1.</strong> Getting Started</a></li><li><ol class="section"><li><a href="getting-started/installation.html"><strong aria-hidden="true">1.1.</strong> Installation</a></li><li><a href="getting-started/first-steps.html"><strong aria-hidden="true">1.2.</strong> First Steps with Cargo</a></li></ol></li><li><a href="guide/index.html"><strong aria-hidden="true">2.</strong> Cargo Guide</a></li><li><ol class="section"><li><a href="guide/why-cargo-exists.html"><strong aria-hidden="true">2.1.</strong> Why Cargo Exists</a></li><li><a href="guide/creating-a-new-project.html"><strong aria-hidden="true">2.2.</strong> Creating a New Package</a></li><li><a href="guide/working-on-an-existing-project.html"><strong aria-hidden="true">2.3.</strong> Working on an Existing Package</a></li><li><a href="guide/dependencies.html"><strong aria-hidden="true">2.4.</strong> Dependencies</a></li><li><a href="guide/project-layout.html"><strong aria-hidden="true">2.5.</strong> Package Layout</a></li><li><a href="guide/cargo-toml-vs-cargo-lock.html"><strong aria-hidden="true">2.6.</strong> Cargo.toml vs Cargo.lock</a></li><li><a href="guide/tests.html"><strong aria-hidden="true">2.7.</strong> Tests</a></li><li><a href="guide/continuous-integration.html"><strong aria-hidden="true">2.8.</strong> Continuous Integration</a></li><li><a href="guide/build-cache.html"><strong aria-hidden="true">2.9.</strong> Build Cache</a></li></ol></li><li><a href="reference/index.html"><strong aria-hidden="true">3.</strong> Cargo Reference</a></li><li><ol class="section"><li><a href="reference/specifying-dependencies.html"><strong aria-hidden="true">3.1.</strong> Specifying Dependencies</a></li><li><a href="reference/manifest.html"><strong aria-hidden="true">3.2.</strong> The Manifest Format</a></li><li><a href="reference/config.html" class="active"><strong aria-hidden="true">3.3.</strong> Configuration</a></li><li><a href="reference/environment-variables.html"><strong aria-hidden="true">3.4.</strong> Environment Variables</a></li><li><a href="reference/build-scripts.html"><strong aria-hidden="true">3.5.</strong> Build Scripts</a></li><li><a href="reference/publishing.html"><strong aria-hidden="true">3.6.</strong> Publishing on crates.io</a></li><li><a href="reference/pkgid-spec.html"><strong aria-hidden="true">3.7.</strong> Package ID Specifications</a></li><li><a href="reference/source-replacement.html"><strong aria-hidden="true">3.8.</strong> Source Replacement</a></li><li><a href="reference/external-tools.html"><strong aria-hidden="true">3.9.</strong> External Tools</a></li><li><a href="reference/registries.html"><strong aria-hidden="true">3.10.</strong> Registries</a></li><li><a href="reference/unstable.html"><strong aria-hidden="true">3.11.</strong> Unstable Features</a></li></ol></li><li><a href="commands/index.html"><strong aria-hidden="true">4.</strong> Cargo Commands</a></li><li><ol class="section"><li><a href="commands/build-commands.html"><strong aria-hidden="true">4.1.</strong> Build Commands</a></li><li><ol class="section"><li><a href="commands/cargo-bench.html"><strong aria-hidden="true">4.1.1.</strong> bench</a></li><li><a href="commands/cargo-build.html"><strong aria-hidden="true">4.1.2.</strong> build</a></li><li><a href="commands/cargo-check.html"><strong aria-hidden="true">4.1.3.</strong> check</a></li><li><a href="commands/cargo-clean.html"><strong aria-hidden="true">4.1.4.</strong> clean</a></li><li><a href="commands/cargo-doc.html"><strong aria-hidden="true">4.1.5.</strong> doc</a></li><li><a href="commands/cargo-fetch.html"><strong aria-hidden="true">4.1.6.</strong> fetch</a></li><li><a href="commands/cargo-fix.html"><strong aria-hidden="true">4.1.7.</strong> fix</a></li><li><a href="commands/cargo-run.html"><strong aria-hidden="true">4.1.8.</strong> run</a></li><li><a href="commands/cargo-rustc.html"><strong aria-hidden="true">4.1.9.</strong> rustc</a></li><li><a href="commands/cargo-rustdoc.html"><strong aria-hidden="true">4.1.10.</strong> rustdoc</a></li><li><a href="commands/cargo-test.html"><strong aria-hidden="true">4.1.11.</strong> test</a></li></ol></li><li><a href="commands/manifest-commands.html"><strong aria-hidden="true">4.2.</strong> Manifest Commands</a></li><li><ol class="section"><li><a href="commands/cargo-generate-lockfile.html"><strong aria-hidden="true">4.2.1.</strong> generate-lockfile</a></li><li><a href="commands/cargo-locate-project.html"><strong aria-hidden="true">4.2.2.</strong> locate-project</a></li><li><a href="commands/cargo-metadata.html"><strong aria-hidden="true">4.2.3.</strong> metadata</a></li><li><a href="commands/cargo-pkgid.html"><strong aria-hidden="true">4.2.4.</strong> pkgid</a></li><li><a href="commands/cargo-update.html"><strong aria-hidden="true">4.2.5.</strong> update</a></li><li><a href="commands/cargo-verify-project.html"><strong aria-hidden="true">4.2.6.</strong> verify-project</a></li></ol></li><li><a href="commands/package-commands.html"><strong aria-hidden="true">4.3.</strong> Package Commands</a></li><li><ol class="section"><li><a href="commands/cargo-init.html"><strong aria-hidden="true">4.3.1.</strong> init</a></li><li><a href="commands/cargo-install.html"><strong aria-hidden="true">4.3.2.</strong> install</a></li><li><a href="commands/cargo-new.html"><strong aria-hidden="true">4.3.3.</strong> new</a></li><li><a href="commands/cargo-search.html"><strong aria-hidden="true">4.3.4.</strong> search</a></li><li><a href="commands/cargo-uninstall.html"><strong aria-hidden="true">4.3.5.</strong> uninstall</a></li></ol></li><li><a href="commands/publishing-commands.html"><strong aria-hidden="true">4.4.</strong> Publishing Commands</a></li><li><ol class="section"><li><a href="commands/cargo-login.html"><strong aria-hidden="true">4.4.1.</strong> login</a></li><li><a href="commands/cargo-owner.html"><strong aria-hidden="true">4.4.2.</strong> owner</a></li><li><a href="commands/cargo-package.html"><strong aria-hidden="true">4.4.3.</strong> package</a></li><li><a href="commands/cargo-publish.html"><strong aria-hidden="true">4.4.4.</strong> publish</a></li><li><a href="commands/cargo-yank.html"><strong aria-hidden="true">4.4.5.</strong> yank</a></li></ol></li><li><a href="commands/general-commands.html"><strong aria-hidden="true">4.5.</strong> General Commands</a></li><li><ol class="section"><li><a href="commands/cargo-help.html"><strong aria-hidden="true">4.5.1.</strong> help</a></li><li><a href="commands/cargo-version.html"><strong aria-hidden="true">4.5.2.</strong> version</a></li></ol></li></ol></li><li><a href="faq.html"><strong aria-hidden="true">5.</strong> FAQ</a></li><li><a href="appendix/glossary.html"><strong aria-hidden="true">6.</strong> Appendix: Glossary</a></li></ol>
</nav>
<div id="page-wrapper" class="page-wrapper">
<div class="page">
<div id="menu-bar" class="menu-bar">
<div id="menu-bar-sticky-container">
<div class="left-buttons">
<button id="sidebar-toggle" class="icon-button" type="button" title="Toggle Table of Contents" aria-label="Toggle Table of Contents" aria-controls="sidebar">
<i class="fa fa-bars"></i>
</button>
<button id="theme-toggle" class="icon-button" type="button" title="Change theme" aria-label="Change theme" aria-haspopup="true" aria-expanded="false" aria-controls="theme-list">
<i class="fa fa-paint-brush"></i>
</button>
<ul id="theme-list" class="theme-popup" aria-label="Themes" role="menu">
<li role="none"><button role="menuitem" class="theme" id="light">Light <span class="default">(default)</span></button></li>
<li role="none"><button role="menuitem" class="theme" id="rust">Rust</button></li>
<li role="none"><button role="menuitem" class="theme" id="coal">Coal</button></li>
<li role="none"><button role="menuitem" class="theme" id="navy">Navy</button></li>
<li role="none"><button role="menuitem" class="theme" id="ayu">Ayu</button></li>
</ul>
<button id="search-toggle" class="icon-button" type="button" title="Search. (Shortkey: s)" aria-label="Toggle Searchbar" aria-expanded="false" aria-keyshortcuts="S" aria-controls="searchbar">
<i class="fa fa-search"></i>
</button>
</div>
<h1 class="menu-title">The Cargo Book</h1>
<div class="right-buttons">
<a href="print.html" title="Print this book" aria-label="Print this book">
<i id="print-button" class="fa fa-print"></i>
</a>
</div>
</div>
</div>
<div id="search-wrapper" class="hidden">
<form id="searchbar-outer" class="searchbar-outer">
<input type="search" name="search" id="searchbar" name="searchbar" placeholder="Search this book ..." aria-controls="searchresults-outer" aria-describedby="searchresults-header">
</form>
<div id="searchresults-outer" class="searchresults-outer hidden">
<div id="searchresults-header" class="searchresults-header"></div>
<ul id="searchresults">
</ul>
</div>
</div>
<!-- Apply ARIA attributes after the sidebar and the sidebar toggle button are added to the DOM -->
<script type="text/javascript">
document.getElementById('sidebar-toggle').setAttribute('aria-expanded', sidebar === 'visible');
document.getElementById('sidebar').setAttribute('aria-hidden', sidebar !== 'visible');
Array.from(document.querySelectorAll('#sidebar a')).forEach(function(link) {
link.setAttribute('tabIndex', sidebar === 'visible' ? 0 : -1);
});
</script>
<div id="content" class="content">
<main>
<a class="header" href="reference/config.html#configuration" id="configuration"><h2>Configuration</h2></a>
<p>This document will explain how Cargo’s configuration system works, as well as
available keys or configuration. For configuration of a package through its
manifest, see the <a href="reference/manifest.html">manifest format</a>.</p>
<a class="header" href="reference/config.html#hierarchical-structure" id="hierarchical-structure"><h3>Hierarchical structure</h3></a>
<p>Cargo allows local configuration for a particular package as well as global
configuration, like git. Cargo extends this to a hierarchical strategy.
If, for example, Cargo were invoked in <code>/projects/foo/bar/baz</code>, then the
following configuration files would be probed for and unified in this order:</p>
<ul>
<li><code>/projects/foo/bar/baz/.cargo/config</code></li>
<li><code>/projects/foo/bar/.cargo/config</code></li>
<li><code>/projects/foo/.cargo/config</code></li>
<li><code>/projects/.cargo/config</code></li>
<li><code>/.cargo/config</code></li>
<li><code>$CARGO_HOME/config</code> (<code>$CARGO_HOME</code> defaults to <code>$HOME/.cargo</code>)</li>
</ul>
<p>With this structure, you can specify configuration per-package, and even
possibly check it into version control. You can also specify personal defaults
with a configuration file in your home directory.</p>
<a class="header" href="reference/config.html#configuration-format" id="configuration-format"><h3>Configuration format</h3></a>
<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>
<a class="header" href="reference/config.html#configuration-keys" id="configuration-keys"><h3>Configuration keys</h3></a>
<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 change the version control system used. Valid values are `git`,
# `hg` (for Mecurial), `pijul`, `fossil`, 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 = ["..", ".."]
# Similar for the $triple configuration, but using the `cfg` syntax.
# If one or more `cfg`s, and a $triple target are candidates, then the $triple
# will be used
# If several `cfg` are candidates, then the build will error
runner = ".."
# Configuration keys related to the registry
[registry]
index = "..." # URL of the registry index (defaults to the index of crates.io)
default = "..." # Name of the default registry to use (can be overridden with
# --registry)
# Configuration keys for registries other than crates.io.
# `$name` should be the name of the registry, which will be used for
# dependencies in `Cargo.toml` files and the `--registry` command-line flag.
# Registry names should only contain alphanumeric characters, `-`, or `_`.
[registries.$name]
index = "..." # URL of the registry index
[http]
proxy = "host:port" # HTTP proxy to use for HTTP requests (defaults to none)
# in libcurl format, e.g., "socks5h://host:port"
timeout = 30 # Timeout for each HTTP request, in seconds
cainfo = "cert.pem" # Path to Certificate Authority (CA) bundle (optional)
check-revoke = true # Indicates whether SSL certs are checked for revocation
low-speed-limit = 5 # Lower threshold for bytes/sec (10 = default, 0 = disabled)
multiplexing = true # whether or not to use HTTP/2 multiplexing where possible
# This setting can be used to help debug what's going on with HTTP requests made
# by Cargo. When set to `true` then Cargo's normal debug logging will be filled
# in with HTTP information, which you can extract with
# `RUST_LOG=cargo::ops::registry=debug` (and `trace` may print more).
#
# Be wary when posting these logs elsewhere though, it may be the case that a
# header has an authentication token in it you don't want leaked! Be sure to
# briefly review logs before posting them.
debug = false
[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 (ignored by `cargo install`)
target-dir = "target" # path of where to place all generated artifacts
rustflags = ["..", ".."] # custom flags to pass to all compiler invocations
rustdocflags = ["..", ".."] # custom flags to pass to rustdoc
incremental = true # whether or not to enable incremental compilation
# If `incremental` is not set, then the value from
# the profile is used.
dep-info-basedir = ".." # full path for the base directory for targets in depfiles
[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
git-fetch-with-cli = false # if `true` we'll use `git`-the-CLI to fetch git repos
# Alias cargo commands. The first 4 aliases are built in. If your
# command requires grouped whitespace use the list format.
[alias]
b = "build"
c = "check"
t = "test"
r = "run"
rr = "run --release"
space_example = ["run", "--release", "--", "\"command list\""]
</code></pre>
<a class="header" href="reference/config.html#environment-variables" id="environment-variables"><h3>Environment variables</h3></a>
<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. This means that <a href="reference/source-replacement.html">source replacement</a>, which is expressed by
tables, cannot be configured through environment variables.</p>
<p>In addition to the system above, Cargo recognizes a few other specific
<a href="reference/environment-variables.html">environment variables</a>.</p>
<a class="header" href="reference/config.html#credentials" id="credentials"><h3>Credentials</h3></a>
<p>Configuration values with sensitive information are stored in the
<code>$CARGO_HOME/credentials</code> file. This file is automatically created and updated
by <a href="commands/cargo-login.html"><code>cargo login</code></a>. It follows the same format as Cargo config files.</p>
<pre><code class="language-toml">[registry]
token = "..." # Access token for crates.io
# `$name` should be a registry name (see above for more information about
# configuring registries).
[registries.$name]
token = "..." # Access token for the named registry
</code></pre>
<p>Tokens are used by some Cargo commands such as <a href="commands/cargo-publish.html"><code>cargo publish</code></a> for
authenticating with remote registries. Care should be taken to protect the
tokens and to keep them secret.</p>
<p>As with most other config values, tokens may be specified with environment
variables. The token for crates.io may be specified with the
<code>CARGO_REGISTRY_TOKEN</code> environment variable. Tokens for other registries may
be specified with environment variables of the form
<code>CARGO_REGISTRIES_NAME_TOKEN</code> where <code>NAME</code> is the name of the registry in all
capital letters.</p>
</main>
<nav class="nav-wrapper" aria-label="Page navigation">
<!-- Mobile navigation buttons -->
<a rel="prev" href="reference/manifest.html" class="mobile-nav-chapters previous" title="Previous chapter" aria-label="Previous chapter" aria-keyshortcuts="Left">
<i class="fa fa-angle-left"></i>
</a>
<a rel="next" href="reference/environment-variables.html" class="mobile-nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right">
<i class="fa fa-angle-right"></i>
</a>
<div style="clear: both"></div>
</nav>
</div>
</div>
<nav class="nav-wide-wrapper" aria-label="Page navigation">
<a href="reference/manifest.html" class="nav-chapters previous" title="Previous chapter" aria-label="Previous chapter" aria-keyshortcuts="Left">
<i class="fa fa-angle-left"></i>
</a>
<a href="reference/environment-variables.html" class="nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right">
<i class="fa fa-angle-right"></i>
</a>
</nav>
</div>
<script src="searchindex.js" type="text/javascript" charset="utf-8"></script>
<script src="elasticlunr.min.js" type="text/javascript" charset="utf-8"></script>
<script src="mark.min.js" type="text/javascript" charset="utf-8"></script>
<script src="searcher.js" type="text/javascript" charset="utf-8"></script>
<script src="clipboard.min.js" type="text/javascript" charset="utf-8"></script>
<script src="highlight.js" type="text/javascript" charset="utf-8"></script>
<script src="book.js" type="text/javascript" charset="utf-8"></script>
<!-- Custom JS scripts -->
</body>
</html>
distrib
>
Mageia
>
7
>
armv7hl
>
media
>
core-release
>
by-pkgid
>
0c2243f8a1696816431e7210e991fa52
>
files
>
1117
