# 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.
+dependencies and ensure that you’ll always get a repeatable build.
To accomplish this goal, Cargo does four things:
1 directory, 2 files
```
-If we had just used `cargo new hello_world` without the `--bin` flag, then the
+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`:
class="s1"> Running</span> `target/debug/hello_world`
Hello, world!</code></pre>
-To pass some arguments to your program, use `cargo run first_arg second_arg`.
+To pass some arguments to your program, use `cargo run first_arg second_arg`.
If flags are being passed, use a “--” separator to tell Cargo which flags go where, like `cargo run -- --foo -b bar`.
You’ll now notice a new file, `Cargo.lock`. It contains information about our
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
+Now, if `regex` gets updated, we will still build with the same revision until
we choose to `cargo update`.
# Project Layout
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. `bjz` could update `color-rs` in the meantime, and my build would
-include this commit, while yours would not. Therefore, we would get different
-builds. This would be bad, because we want reproducible builds.
+include this commit 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`:
color = { git = "https://github.com/bjz/color-rs.git", rev = "bf739419" }
```
-Now, our builds will be the same. But, there’s a big drawback: now we have to
+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.
color = { git = "https://github.com/bjz/color-rs.git" }
```
-Cargo will take the latest commit, and write that information out into our
+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
```
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,
+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:
+re-calculate the dependencies and update things for us:
```shell
$ cargo update # updates all dependencies
# Overriding Dependencies
-Sometimes, you may want to override one of Cargo’s dependencies. For example,
+Sometimes you may want to override one of Cargo’s dependencies. For example,
let’s say you’re working on a project, `conduit-static`, which depends on
the package `conduit`. You find a bug in `conduit`, and you want to write a
patch. Here’s what `conduit-static`’s `Cargo.toml` looks like:
* `/`
This allows you to specify your overrides in a parent directory that
-includes commonly used packages that you work on locally, and share them
+includes commonly used packages that you work on locally and share them
with all projects.
To specify overrides, create a `.cargo/config` file in some ancestor of
# Tests
Cargo can run your tests with the `cargo test` command. Cargo runs tests in two
-places: in each of your `src` files, and any tests in `tests/`. Tests
+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`.
test result: ok. 0 passed; 0 failed; 0 ignored; 0 measured
</code></pre>
-Of course, if your project has tests, you’ll see more output, with the
+Of course, if your project has tests, you’ll see more output with the
correct number of tests.
You can also run a specific test by passing a filter:
This will run any test with `foo` in its name.
`cargo test` runs additional tests as well. For example, it will compile any
-examples, you’ve included, and will also test the examples in your
+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.
And that’s it! The next `cargo build` will automatically build `hello_utils` and
all of its own dependencies, and others can also start using the crate as well.
-However, dependencies with only a path are not permitted on crates.io so if we
-wanted to publish our `hello_world` crate we would need to publish a version of
+However, dependencies with only a path are not permitted on crates.io. If we
+wanted to publish our `hello_world` crate, we would need to publish a version of
`hello_utils` to crates.io (or specify a git repository location) and specify it
in the dependencies line:
projects / cargo.git / commitdiff