src/doc/guide.md - rust-lang/cargo - Git at Google

 % Cargo Guide

 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.

 # Why Cargo exists

 Cargo is a tool that allows Rust projects to declare their various
 dependencies and ensure that you’ll always get a repeatable build.

 To accomplish this goal, Cargo does four things:

 * Introduces two metadata files with various bits of project information.
 * Fetches and builds your project’s dependencies.
 * Invokes `rustc` or another build tool with the correct parameters to build your project.
 * Introduces conventions to make working with Rust projects easier.

 # Creating a new project

 To start a new project with Cargo, use `cargo new`:

 ```shell
 $ cargo new hello_world --bin
 ```

 We’re passing `--bin` because we’re making a binary program: if we
 were making a library, we’d leave it off. This also initializes a new `git`
 repository by default. If you don't want it to do that, pass `--vcs none`.

 Let’s check out what Cargo has generated for us:

 ```shell
 $ cd hello_world
 $ tree .
 .
 ├── Cargo.toml
 └── src
     └── main.rs

 1 directory, 2 files
 ```

 If we had just used `cargo new hello_world` without the `--bin` flag, then
 we would have a `lib.rs` instead of a `main.rs`. For now, however, this is all
 we need to get started. First, let’s check out `Cargo.toml`:

 ```toml
 [package]
 name = "hello_world"
 version = "0.1.0"
 authors = ["Your Name <you@example.com>"]
 ```

 This is called a **manifest**, and it contains all of the metadata that Cargo
 needs to compile your project.

 Here’s what’s in `src/main.rs`:

 ```
 fn main() {
     println!("Hello, world!");
 }
 ```

 Cargo generated a “hello world” for us. Let’s compile it:

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

 And then run it:

 ```shell
 $ ./target/debug/hello_world
 Hello, world!
 ```

 We can also use `cargo run` to compile and then run it, all in one step (You
 won't see the `Compiling` line if you have not made any changes since you last
 compiled):

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

 You’ll now notice a new file, `Cargo.lock`. It contains information about our
 dependencies. Since we don’t have any yet, it’s not very interesting.

 Once you’re ready for release, you can use `cargo build --release` to compile your files with optimizations turned on:

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

 `cargo build --release` puts the resulting binary in
 `target/release` instead of `target/debug`.

 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.

 # Working on an existing Cargo project

 If you download an existing project that uses Cargo, it’s really easy
 to get going.

 First, get the project from somewhere. In this example, we’ll use `rand`
 cloned from its repository on GitHub:

 ```sh
 $ git clone https://github.com/rust-lang-nursery/rand.git
 $ cd rand
 ```

 To build, use `cargo build`:

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

 This will fetch all of the dependencies and then build them, along with the
 project.

 # Adding dependencies from crates.io

 [crates.io] is the Rust community's central repository that serves
 as a location to discover and download packages. `cargo` is configured to use
 it by default to find requested packages.

 To depend on a library hosted on [crates.io], add it to your `Cargo.toml`.

 [crates.io]: https://crates.io/

 ## Adding a dependency

 If your `Cargo.toml` doesn't already have a `[dependencies]` section, add that,
 then list the crate name and version that you would like to use. This example
 adds a dependency of the `time` crate:

 ```toml
 [dependencies]
 time = "0.1.12"
 ```

 The version string is a [semver] version requirement. The [specifying
 dependencies](specifying-dependencies.html) docs have more information about
 the options you have here.

 [semver]: https://github.com/steveklabnik/semver#requirements

 If we also wanted to add a dependency on the `regex` crate, we would not need
 to add `[dependencies]` for each crate listed. Here's what your whole
 `Cargo.toml` file would look like with dependencies on the `time` and `regex`
 crates:

 ```toml
 [package]
 name = "hello_world"
 version = "0.1.0"
 authors = ["Your Name <you@example.com>"]

 [dependencies]
 time = "0.1.12"
 regex = "0.1.41"
 ```

 Re-run `cargo build`, and Cargo will fetch the new dependencies and all of
 their dependencies, compile them all, and update the `Cargo.lock`:

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

 Our `Cargo.lock` contains the exact information about which revision of all of
 these dependencies we used.

 Now, if `regex` gets updated, we will still build with the same revision until
 we choose to `cargo update`.

 You can now use the `regex` library using `extern crate` in `main.rs`.

 ```
 extern crate regex;

 use regex::Regex;

 fn main() {
     let re = Regex::new(r"^\d{4}-\d{2}-\d{2}$").unwrap();
     println!("Did our date match? {}", re.is_match("2014-01-01"));
 }
 ```

 Running it will show:

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

 # Project layout

 Cargo uses conventions for file placement to make it easy to dive into a new
 Cargo project:

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

 * `Cargo.toml` and `Cargo.lock` are stored in the root of your project.
 * Source code goes in the `src` directory.
 * The default library file is `src/lib.rs`.
 * The default executable file is `src/main.rs`.
 * Other executables can be placed in `src/bin/*.rs`.
 * Integration tests go in the `tests` directory (unit tests go in each file they're testing).
 * Examples go in the `examples` directory.
 * Benchmarks go in the `benches` directory.

 These are explained in more detail in the [manifest
 description](manifest.html#the-project-layout).

 # Cargo.toml vs Cargo.lock

 `Cargo.toml` and `Cargo.lock` serve two different purposes. Before we talk
 about them, here’s a summary:

 * `Cargo.toml` is about describing your dependencies in a broad sense, and is written by you.
 * `Cargo.lock` contains exact information about your dependencies. It is maintained by Cargo and should not be manually edited.

 If you’re building a library that other projects will depend on, put
 `Cargo.lock` in your `.gitignore`. If you’re building an executable like a
 command-line tool or an application, check `Cargo.lock` into `git`. If you're
 curious about why that is, see ["Why do binaries have `Cargo.lock` in version
 control, but not libraries?" in the
 FAQ](faq.html#why-do-binaries-have-cargolock-in-version-control-but-not-libraries).

 Let’s dig in a little bit more.

 `Cargo.toml` is a **manifest** 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:

 ```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" }
 ```

 This project has a single dependency, on the `rand` 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 `master` branch to build our project.

 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 `rand` 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.

 We could fix this problem by putting a `rev` line in our `Cargo.toml`:

 ```toml
 [dependencies]
 rand = { git = "https://github.com/rust-lang-nursery/rand.git", rev = "9f35b8e" }
 ```

 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.

 Enter the `Cargo.lock`. 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:

 ```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" }
 ```

 Cargo will take the latest commit and write that information out into our
 `Cargo.lock` when we build for the first time. That file will look like this:

 ```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"

 ```

 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
 `Cargo.toml`.

 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:

 ```shell
 $ cargo update           # updates all dependencies
 $ cargo update -p rand  # updates just “rand”
 ```

 This will write out a new `Cargo.lock` with the new version information. Note
 that the argument to `cargo update` is actually a
 [Package ID Specification](pkgid-spec.html) and `rand` is just a short
 specification.

 # Tests

 Cargo can run your tests with the `cargo test` command. Cargo looks for tests
 to run in two places: in each of your `src` files and any tests in `tests/`.
 Tests in your `src` files should be unit tests, and tests in `tests/` should be
 integration-style tests. As such, you’ll need to import your crates into
 the files in `tests`.

 Here's an example of running `cargo test` in our project, which currently has
 no tests:

 <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
 </code></pre>

 If our project had tests, we would see more output with the correct number of
 tests.

 You can also run a specific test by passing a filter:

 <pre><code class="language-shell"><span class="gp">$</span> cargo test foo
 </code></pre>

 This will run any test with `foo` in its name.

 `cargo test` 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 [testing guide][testing] in the Rust
 documentation for more details.

 [testing]: https://doc.rust-lang.org/book/testing.html

 ## Travis CI

 To test your project on Travis CI, here is a sample `.travis.yml` file:

 ```
 language: rust
 rust:
   - stable
   - beta
   - nightly
 matrix:
   allow_failures:
     - rust: nightly
 ```

 This will test all three release channels, but any breakage in nightly
 will not fail your overall build. Please see the [Travis CI Rust
 documentation](https://docs.travis-ci.com/user/languages/rust/) for more
 information.

 # Further reading

 Now that you have an overview of how to use cargo and have created your first crate, you may be interested in:

 * [Publishing your crate on crates.io](crates-io.html)
 * [Reading about all the possible ways of specifying dependencies](specifying-dependencies.html)
 * [Learning more details about what you can specify in your `Cargo.toml` manifest](manifest.html)

 Even more topics are available in the Docs menu at the top!
	% Cargo Guide

	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.

	# Why Cargo exists

	Cargo is a tool that allows Rust projects to declare their various
	dependencies and ensure that you’ll always get a repeatable build.

	To accomplish this goal, Cargo does four things:

	* Introduces two metadata files with various bits of project information.
	* Fetches and builds your project’s dependencies.
	* Invokes `rustc` or another build tool with the correct parameters to build your project.
	* Introduces conventions to make working with Rust projects easier.

	# Creating a new project

	To start a new project with Cargo, use `cargo new`:

	```shell
	$ cargo new hello_world --bin
	```

	We’re passing `--bin` because we’re making a binary program: if we
	were making a library, we’d leave it off. This also initializes a new `git`
	repository by default. If you don't want it to do that, pass `--vcs none`.

	Let’s check out what Cargo has generated for us:

	```shell
	$ cd hello_world
	$ tree .
	.
	├── Cargo.toml
	└── src
	└── main.rs

	1 directory, 2 files
	```

	If we had just used `cargo new hello_world` without the `--bin` flag, then
	we would have a `lib.rs` instead of a `main.rs`. For now, however, this is all
	we need to get started. First, let’s check out `Cargo.toml`:

	```toml
	[package]
	name = "hello_world"
	version = "0.1.0"
	authors = ["Your Name <you@example.com>"]
	```

	This is called a manifest, and it contains all of the metadata that Cargo
	needs to compile your project.

	Here’s what’s in `src/main.rs`:

	```
	fn main() {
	println!("Hello, world!");
	}
	```

	Cargo generated a “hello world” for us. Let’s compile it:

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

	And then run it:

	```shell
	$ ./target/debug/hello_world
	Hello, world!
	```

	We can also use `cargo run` to compile and then run it, all in one step (You
	won't see the `Compiling` line if you have not made any changes since you last
	compiled):

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

	You’ll now notice a new file, `Cargo.lock`. It contains information about our
	dependencies. Since we don’t have any yet, it’s not very interesting.

	Once you’re ready for release, you can use `cargo build --release` to compile your files with optimizations turned on:

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

	`cargo build --release` puts the resulting binary in
	`target/release` instead of `target/debug`.

	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.

	# Working on an existing Cargo project

	If you download an existing project that uses Cargo, it’s really easy
	to get going.

	First, get the project from somewhere. In this example, we’ll use `rand`
	cloned from its repository on GitHub:

	```sh
	$ git clone https://github.com/rust-lang-nursery/rand.git
	$ cd rand
	```

	To build, use `cargo build`:

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

	This will fetch all of the dependencies and then build them, along with the
	project.

	# Adding dependencies from crates.io

	[crates.io] is the Rust community's central repository that serves
	as a location to discover and download packages. `cargo` is configured to use
	it by default to find requested packages.

	To depend on a library hosted on [crates.io], add it to your `Cargo.toml`.

	[crates.io]: https://crates.io/

	## Adding a dependency

	If your `Cargo.toml` doesn't already have a `[dependencies]` section, add that,
	then list the crate name and version that you would like to use. This example
	adds a dependency of the `time` crate:

	```toml
	[dependencies]
	time = "0.1.12"
	```

	The version string is a [semver] version requirement. The [specifying
	dependencies](specifying-dependencies.html) docs have more information about
	the options you have here.

	[semver]: https://github.com/steveklabnik/semver#requirements

	If we also wanted to add a dependency on the `regex` crate, we would not need
	to add `[dependencies]` for each crate listed. Here's what your whole
	`Cargo.toml` file would look like with dependencies on the `time` and `regex`
	crates:

	```toml
	[package]
	name = "hello_world"
	version = "0.1.0"
	authors = ["Your Name <you@example.com>"]

	[dependencies]
	time = "0.1.12"
	regex = "0.1.41"
	```

	Re-run `cargo build`, and Cargo will fetch the new dependencies and all of
	their dependencies, compile them all, and update the `Cargo.lock`:

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

	Our `Cargo.lock` contains the exact information about which revision of all of
	these dependencies we used.

	Now, if `regex` gets updated, we will still build with the same revision until
	we choose to `cargo update`.

	You can now use the `regex` library using `extern crate` in `main.rs`.

	```
	extern crate regex;

	use regex::Regex;

	fn main() {
	let re = Regex::new(r"^\d{4}-\d{2}-\d{2}$").unwrap();
	println!("Did our date match? {}", re.is_match("2014-01-01"));
	}
	```

	Running it will show:

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

	# Project layout

	Cargo uses conventions for file placement to make it easy to dive into a new
	Cargo project:

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

	* `Cargo.toml` and `Cargo.lock` are stored in the root of your project.
	* Source code goes in the `src` directory.
	* The default library file is `src/lib.rs`.
	* The default executable file is `src/main.rs`.
	* Other executables can be placed in `src/bin/*.rs`.
	* Integration tests go in the `tests` directory (unit tests go in each file they're testing).
	* Examples go in the `examples` directory.
	* Benchmarks go in the `benches` directory.

	These are explained in more detail in the [manifest
	description](manifest.html#the-project-layout).

	# Cargo.toml vs Cargo.lock

	`Cargo.toml` and `Cargo.lock` serve two different purposes. Before we talk
	about them, here’s a summary:

	* `Cargo.toml` is about describing your dependencies in a broad sense, and is written by you.
	* `Cargo.lock` contains exact information about your dependencies. It is maintained by Cargo and should not be manually edited.

	If you’re building a library that other projects will depend on, put
	`Cargo.lock` in your `.gitignore`. If you’re building an executable like a
	command-line tool or an application, check `Cargo.lock` into `git`. If you're
	curious about why that is, see ["Why do binaries have `Cargo.lock` in version
	control, but not libraries?" in the
	FAQ](faq.html#why-do-binaries-have-cargolock-in-version-control-but-not-libraries).

	Let’s dig in a little bit more.

	`Cargo.toml` is a manifest 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:

	```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" }
	```

	This project has a single dependency, on the `rand` 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 `master` branch to build our project.

	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 `rand` 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.

	We could fix this problem by putting a `rev` line in our `Cargo.toml`:

	```toml
	[dependencies]
	rand = { git = "https://github.com/rust-lang-nursery/rand.git", rev = "9f35b8e" }
	```

	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.

	Enter the `Cargo.lock`. 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:

	```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" }
	```

	Cargo will take the latest commit and write that information out into our
	`Cargo.lock` when we build for the first time. That file will look like this:

	```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"

	```

	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
	`Cargo.toml`.

	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:

	```shell
	$ cargo update # updates all dependencies
	$ cargo update -p rand # updates just “rand”
	```

	This will write out a new `Cargo.lock` with the new version information. Note
	that the argument to `cargo update` is actually a
	[Package ID Specification](pkgid-spec.html) and `rand` is just a short
	specification.

	# Tests

	Cargo can run your tests with the `cargo test` command. Cargo looks for tests
	to run in two places: in each of your `src` files and any tests in `tests/`.
	Tests in your `src` files should be unit tests, and tests in `tests/` should be
	integration-style tests. As such, you’ll need to import your crates into
	the files in `tests`.

	Here's an example of running `cargo test` in our project, which currently has
	no tests:

	<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
	</code></pre>

	If our project had tests, we would see more output with the correct number of
	tests.

	You can also run a specific test by passing a filter:

	<pre><code class="language-shell"><span class="gp">$</span> cargo test foo
	</code></pre>

	This will run any test with `foo` in its name.

	`cargo test` 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 [testing guide][testing] in the Rust
	documentation for more details.

	[testing]: https://doc.rust-lang.org/book/testing.html

	## Travis CI

	To test your project on Travis CI, here is a sample `.travis.yml` file:

	```
	language: rust
	rust:
	- stable
	- beta
	- nightly
	matrix:
	allow_failures:
	- rust: nightly
	```

	This will test all three release channels, but any breakage in nightly
	will not fail your overall build. Please see the [Travis CI Rust
	documentation](https://docs.travis-ci.com/user/languages/rust/) for more
	information.

	# Further reading

	Now that you have an overview of how to use cargo and have created your first crate, you may be interested in:

	* [Publishing your crate on crates.io](crates-io.html)
	* [Reading about all the possible ways of specifying dependencies](specifying-dependencies.html)
	* [Learning more details about what you can specify in your `Cargo.toml` manifest](manifest.html)

	Even more topics are available in the Docs menu at the top!