<!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>Cargo Guide</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">Cargo Guide</h1>
<p>Welcome to the Cargo guide. This guide will give you all that you need to know
about how to use Cargo to develop Rust projects.</p>
<h1 id='why-cargo-exists' class='section-header'><a href='#why-cargo-exists'>Why Cargo exists</a></h1>
<p>Cargo is a tool that allows Rust projects to declare their various
dependencies and ensure that you’ll always get a repeatable build.</p>
<p>To accomplish this goal, Cargo does four things:</p>
<ul>
<li>Introduces two metadata files with various bits of project information.</li>
<li>Fetches and builds your project’s dependencies.</li>
<li>Invokes <code>rustc</code> or another build tool with the correct parameters to build
your project.</li>
<li>Introduces conventions to make working with Rust projects easier.</li>
</ul>
<h1 id='creating-a-new-project' class='section-header'><a href='#creating-a-new-project'>Creating a new project</a></h1>
<p>To start a new project with Cargo, use <code>cargo new</code>:</p>
<pre><code class="language-shell">$ cargo new hello_world --bin
</code></pre>
<p>We’re passing <code>--bin</code> because we’re making a binary program: if we
were making a library, we’d leave it off. This also initializes a new <code>git</code>
repository by default. If you don't want it to do that, pass <code>--vcs none</code>.</p>
<p>Let’s check out what Cargo has generated for us:</p>
<pre><code class="language-shell">$ cd hello_world
$ tree .
.
├── Cargo.toml
└── src
└── main.rs
1 directory, 2 files
</code></pre>
<p>If we had just used <code>cargo new hello_world</code> without the <code>--bin</code> flag, then
we would have a <code>lib.rs</code> instead of a <code>main.rs</code>. For now, however, this is all
we need to get started. First, let’s check out <code>Cargo.toml</code>:</p>
<pre><code class="language-toml">[package]
name = "hello_world"
version = "0.1.0"
authors = ["Your Name <you@example.com>"]
</code></pre>
<p>This is called a <strong>manifest</strong>, and it contains all of the metadata that Cargo
needs to compile your project.</p>
<p>Here’s what’s in <code>src/main.rs</code>:</p>
<pre class="rust rust-example-rendered">
<span class="kw">fn</span> <span class="ident">main</span>() {
<span class="macro">println</span><span class="macro">!</span>(<span class="string">"Hello, world!"</span>);
}</pre>
<p>Cargo generated a “hello world” for us. Let’s compile it:</p>
<pre><code class="language-shell"><span class="gp">$</span> cargo build
<span style="font-weight: bold"
class="s1"> Compiling</span> hello_world v0.1.0 (file:///path/to/project/hello_world)</code></pre>
<p>And then run it:</p>
<pre><code class="language-shell">$ ./target/debug/hello_world
Hello, world!
</code></pre>
<p>We can also use <code>cargo run</code> to compile and then run it, all in one step (You
won't see the <code>Compiling</code> line if you have not made any changes since you last
compiled):</p>
<pre><code class="language-shell"><span class="gp">$</span> cargo run
<span style="font-weight: bold"
class="s1"> Compiling</span> hello_world v0.1.0 (file:///path/to/project/hello_world)
<span style="font-weight: bold"
class="s1"> Running</span> `target/debug/hello_world`
Hello, world!</code></pre>
<p>You’ll now notice a new file, <code>Cargo.lock</code>. It contains information about our
dependencies. Since we don’t have any yet, it’s not very interesting.</p>
<p>Once you’re ready for release, you can use <code>cargo build --release</code> to compile
your files with optimizations turned on:</p>
<pre><code class="language-shell"><span class="gp">$</span> cargo build --release
<span style="font-weight: bold"
class="s1"> Compiling</span> hello_world v0.1.0 (file:///path/to/project/hello_world)</code></pre>
<p><code>cargo build --release</code> puts the resulting binary in
<code>target/release</code> instead of <code>target/debug</code>.</p>
<p>Compiling in debug mode is the default for development-- compilation time is
shorter since the compiler doesn't do optimizations, but the code will run
slower. Release mode takes longer to compile, but the code will run faster.</p>
<h1 id='working-on-an-existing-cargo-project' class='section-header'><a href='#working-on-an-existing-cargo-project'>Working on an existing Cargo project</a></h1>
<p>If you download an existing project that uses Cargo, it’s really easy
to get going.</p>
<p>First, get the project from somewhere. In this example, we’ll use <code>rand</code>
cloned from its repository on GitHub:</p>
<pre><code class="language-sh">$ git clone https://github.com/rust-lang-nursery/rand.git
$ cd rand
</code></pre>
<p>To build, use <code>cargo build</code>:</p>
<pre><code class="language-shell"><span class="gp">$</span> cargo build
<span style="font-weight: bold" class="s1"> Compiling</span> rand v0.1.0 (file:///path/to/project/rand)</code></pre>
<p>This will fetch all of the dependencies and then build them, along with the
project.</p>
<h1 id='adding-dependencies-from-cratesio' class='section-header'><a href='#adding-dependencies-from-cratesio'>Adding dependencies from crates.io</a></h1>
<p><a href="https://crates.io/">crates.io</a> is the Rust community's central repository that serves
as a location to discover and download packages. <code>cargo</code> is configured to use
it by default to find requested packages.</p>
<p>To depend on a library hosted on <a href="https://crates.io/">crates.io</a>, add it to your <code>Cargo.toml</code>.</p>
<h2 id='adding-a-dependency' class='section-header'><a href='#adding-a-dependency'>Adding a dependency</a></h2>
<p>If your <code>Cargo.toml</code> doesn't already have a <code>[dependencies]</code> section, add that,
then list the crate name and version that you would like to use. This example
adds a dependency of the <code>time</code> crate:</p>
<pre><code class="language-toml">[dependencies]
time = "0.1.12"
</code></pre>
<p>The version string is a <a href="https://github.com/steveklabnik/semver#requirements">semver</a> version requirement. The <a href="specifying-dependencies.html">specifying
dependencies</a> docs have more information about
the options you have here.</p>
<p>If we also wanted to add a dependency on the <code>regex</code> crate, we would not need
to add <code>[dependencies]</code> for each crate listed. Here's what your whole
<code>Cargo.toml</code> file would look like with dependencies on the <code>time</code> and <code>regex</code>
crates:</p>
<pre><code class="language-toml">[package]
name = "hello_world"
version = "0.1.0"
authors = ["Your Name <you@example.com>"]
[dependencies]
time = "0.1.12"
regex = "0.1.41"
</code></pre>
<p>Re-run <code>cargo build</code>, and Cargo will fetch the new dependencies and all of
their dependencies, compile them all, and update the <code>Cargo.lock</code>:</p>
<pre><code class="language-shell"><span class="gp">$</span> cargo build
<span style="font-weight: bold" class="s1"> Updating</span> registry `https://github.com/rust-lang/crates.io-index`
<span style="font-weight: bold" class="s1"> Downloading</span> memchr v0.1.5
<span style="font-weight: bold" class="s1"> Downloading</span> libc v0.1.10
<span style="font-weight: bold" class="s1"> Downloading</span> regex-syntax v0.2.1
<span style="font-weight: bold" class="s1"> Downloading</span> memchr v0.1.5
<span style="font-weight: bold" class="s1"> Downloading</span> aho-corasick v0.3.0
<span style="font-weight: bold" class="s1"> Downloading</span> regex v0.1.41
<span style="font-weight: bold" class="s1"> Compiling</span> memchr v0.1.5
<span style="font-weight: bold" class="s1"> Compiling</span> libc v0.1.10
<span style="font-weight: bold" class="s1"> Compiling</span> regex-syntax v0.2.1
<span style="font-weight: bold" class="s1"> Compiling</span> memchr v0.1.5
<span style="font-weight: bold" class="s1"> Compiling</span> aho-corasick v0.3.0
<span style="font-weight: bold" class="s1"> Compiling</span> regex v0.1.41
<span style="font-weight: bold" class="s1"> Compiling</span> hello_world v0.1.0 (file:///path/to/project/hello_world)</code></pre>
<p>Our <code>Cargo.lock</code> contains the exact information about which revision of all of
these dependencies we used.</p>
<p>Now, if <code>regex</code> gets updated, we will still build with the same revision until
we choose to <code>cargo update</code>.</p>
<p>You can now use the <code>regex</code> library using <code>extern crate</code> in <code>main.rs</code>.</p>
<pre class="rust rust-example-rendered">
<span class="kw">extern</span> <span class="kw">crate</span> <span class="ident">regex</span>;
<span class="kw">use</span> <span class="ident">regex</span>::<span class="ident">Regex</span>;
<span class="kw">fn</span> <span class="ident">main</span>() {
<span class="kw">let</span> <span class="ident">re</span> <span class="op">=</span> <span class="ident">Regex</span>::<span class="ident">new</span>(<span class="string">r"^\d{4}-\d{2}-\d{2}$"</span>).<span class="ident">unwrap</span>();
<span class="macro">println</span><span class="macro">!</span>(<span class="string">"Did our date match? {}"</span>, <span class="ident">re</span>.<span class="ident">is_match</span>(<span class="string">"2014-01-01"</span>));
}</pre>
<p>Running it will show:</p>
<pre><code class="language-shell"><span class="gp">$</span> cargo run
<span style="font-weight: bold" class="s1"> Running</span> `target/hello_world`
Did our date match? true</code></pre>
<h1 id='project-layout' class='section-header'><a href='#project-layout'>Project layout</a></h1>
<p>Cargo uses conventions for file placement to make it easy to dive into a new
Cargo project:</p>
<pre><code class="language-shell">.
├── Cargo.lock
├── Cargo.toml
├── benches
│ └── large-input.rs
├── examples
│ └── simple.rs
├── src
│ ├── bin
│ │ └── another_executable.rs
│ ├── lib.rs
│ └── main.rs
└── tests
└── some-integration-tests.rs
</code></pre>
<ul>
<li><code>Cargo.toml</code> and <code>Cargo.lock</code> are stored in the root of your project (<em>package
root</em>).</li>
<li>Source code goes in the <code>src</code> directory.</li>
<li>The default library file is <code>src/lib.rs</code>.</li>
<li>The default executable file is <code>src/main.rs</code>.</li>
<li>Other executables can be placed in <code>src/bin/*.rs</code>.</li>
<li>Integration tests go in the <code>tests</code> directory (unit tests go in each file
they're testing).</li>
<li>Examples go in the <code>examples</code> directory.</li>
<li>Benchmarks go in the <code>benches</code> directory.</li>
</ul>
<p>These are explained in more detail in the <a href="manifest.html#the-project-layout">manifest
description</a>.</p>
<h1 id='cargotoml-vs-cargolock' class='section-header'><a href='#cargotoml-vs-cargolock'>Cargo.toml vs Cargo.lock</a></h1>
<p><code>Cargo.toml</code> and <code>Cargo.lock</code> serve two different purposes. Before we talk
about them, here’s a summary:</p>
<ul>
<li><code>Cargo.toml</code> is about describing your dependencies in a broad sense, and is
written by you.</li>
<li><code>Cargo.lock</code> contains exact information about your dependencies. It is
maintained by Cargo and should not be manually edited.</li>
</ul>
<p>If you’re building a library that other projects will depend on, put
<code>Cargo.lock</code> in your <code>.gitignore</code>. If you’re building an executable like a
command-line tool or an application, check <code>Cargo.lock</code> into <code>git</code>. If you're
curious about why that is, see <a href="faq.html#why-do-binaries-have-cargolock-in-version-control-but-not-libraries">"Why do binaries have <code>Cargo.lock</code> in version
control, but not libraries?" in the
FAQ</a>.</p>
<p>Let’s dig in a little bit more.</p>
<p><code>Cargo.toml</code> is a <strong>manifest</strong> file in which we can specify a bunch of
different metadata about our project. For example, we can say that we depend
on another project:</p>
<pre><code class="language-toml">[package]
name = "hello_world"
version = "0.1.0"
authors = ["Your Name <you@example.com>"]
[dependencies]
rand = { git = "https://github.com/rust-lang-nursery/rand.git" }
</code></pre>
<p>This project has a single dependency, on the <code>rand</code> library. We’ve stated in
this case that we’re relying on a particular Git repository that lives on
GitHub. Since we haven’t specified any other information, Cargo assumes that
we intend to use the latest commit on the <code>master</code> branch to build our project.</p>
<p>Sound good? Well, there’s one problem: If you build this project today, and
then you send a copy to me, and I build this project tomorrow, something bad
could happen. There could be more commits to <code>rand</code> in the meantime, and my
build would include new commits while yours would not. Therefore, we would
get different builds. This would be bad because we want reproducible builds.</p>
<p>We could fix this problem by putting a <code>rev</code> line in our <code>Cargo.toml</code>:</p>
<pre><code class="language-toml">[dependencies]
rand = { git = "https://github.com/rust-lang-nursery/rand.git", rev = "9f35b8e" }
</code></pre>
<p>Now our builds will be the same. But there’s a big drawback: now we have to
manually think about SHA-1s every time we want to update our library. This is
both tedious and error prone.</p>
<p>Enter the <code>Cargo.lock</code>. Because of its existence, we don’t need to manually
keep track of the exact revisions: Cargo will do it for us. When we have a
manifest like this:</p>
<pre><code class="language-toml">[package]
name = "hello_world"
version = "0.1.0"
authors = ["Your Name <you@example.com>"]
[dependencies]
rand = { git = "https://github.com/rust-lang-nursery/rand.git" }
</code></pre>
<p>Cargo will take the latest commit and write that information out into our
<code>Cargo.lock</code> when we build for the first time. That file will look like this:</p>
<pre><code class="language-toml">[root]
name = "hello_world"
version = "0.1.0"
dependencies = [
"rand 0.1.0 (git+https://github.com/rust-lang-nursery/rand.git#9f35b8e439eeedd60b9414c58f389bdc6a3284f9)",
]
[[package]]
name = "rand"
version = "0.1.0"
source = "git+https://github.com/rust-lang-nursery/rand.git#9f35b8e439eeedd60b9414c58f389bdc6a3284f9"
</code></pre>
<p>You can see that there’s a lot more information here, including the exact
revision we used to build. Now when you give your project to someone else,
they’ll use the exact same SHA, even though we didn’t specify it in our
<code>Cargo.toml</code>.</p>
<p>When we’re ready to opt in to a new version of the library, Cargo can
re-calculate the dependencies and update things for us:</p>
<pre><code class="language-shell">$ cargo update # updates all dependencies
$ cargo update -p rand # updates just “rand”
</code></pre>
<p>This will write out a new <code>Cargo.lock</code> with the new version information. Note
that the argument to <code>cargo update</code> is actually a
<a href="pkgid-spec.html">Package ID Specification</a> and <code>rand</code> is just a short
specification.</p>
<h1 id='tests' class='section-header'><a href='#tests'>Tests</a></h1>
<p>Cargo can run your tests with the <code>cargo test</code> command. Cargo looks for tests
to run in two places: in each of your <code>src</code> files and any tests in <code>tests/</code>.
Tests in your <code>src</code> files should be unit tests, and tests in <code>tests/</code> should be
integration-style tests. As such, you’ll need to import your crates into
the files in <code>tests</code>.</p>
<p>Here's an example of running <code>cargo test</code> in our project, which currently has
no tests:</p>
<pre><code class="language-shell"><span class="gp">$</span> cargo test
<span style="font-weight: bold"
class="s1"> Compiling</span> rand v0.1.0 (https://github.com/rust-lang-nursery/rand.git#9f35b8e)
<span style="font-weight: bold"
class="s1"> Compiling</span> hello_world v0.1.0 (file:///path/to/project/hello_world)
<span style="font-weight: bold"
class="s1"> Running</span> target/test/hello_world-9c2b65bbb79eabce
running 0 tests
test result: ok. 0 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out
</code></pre>
<p>If our project had tests, we would see more output with the correct number of
tests.</p>
<p>You can also run a specific test by passing a filter:</p>
<pre><code class="language-shell"><span class="gp">$</span> cargo test foo
</code></pre>
<p>This will run any test with <code>foo</code> in its name.</p>
<p><code>cargo test</code> runs additional checks as well. For example, it will compile any
examples you’ve included and will also test the examples in your
documentation. Please see the <a href="https://doc.rust-lang.org/book/testing.html">testing guide</a> in the Rust
documentation for more details.</p>
<h2 id='travis-ci' class='section-header'><a href='#travis-ci'>Travis CI</a></h2>
<p>To test your project on Travis CI, here is a sample <code>.travis.yml</code> file:</p>
<pre class="rust rust-example-rendered">
<span class="ident">language</span>: <span class="ident">rust</span>
<span class="ident">rust</span>:
<span class="op">-</span> <span class="ident">stable</span>
<span class="op">-</span> <span class="ident">beta</span>
<span class="op">-</span> <span class="ident">nightly</span>
<span class="ident">matrix</span>:
<span class="ident">allow_failures</span>:
<span class="op">-</span> <span class="ident">rust</span>: <span class="ident">nightly</span></pre>
<p>This will test all three release channels, but any breakage in nightly
will not fail your overall build. Please see the <a href="https://docs.travis-ci.com/user/languages/rust/">Travis CI Rust
documentation</a> for more
information.</p>
<h1 id='further-reading' class='section-header'><a href='#further-reading'>Further reading</a></h1>
<p>Now that you have an overview of how to use cargo and have created your first
crate, you may be interested in:</p>
<ul>
<li><a href="crates-io.html">Publishing your crate on crates.io</a></li>
<li><a href="specifying-dependencies.html">Reading about all the possible ways of specifying dependencies</a></li>
<li><a href="manifest.html">Learning more details about what you can specify in your <code>Cargo.toml</code> manifest</a></li>
</ul>
<p>Even more topics are available in the Docs menu at the top!</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>
distrib
>
Mageia
>
6
>
x86_64
>
media
>
core-updates
>
by-pkgid
>
3dd7afb0e73ef085f903dd0db1dc8c8f
>
files
>
10
