diff --git a/src/doc/src/guide/cargo-toml-vs-cargo-lock.md b/src/doc/src/guide/cargo-toml-vs-cargo-lock.md index 21f52dca119..138a7635bb0 100644 --- a/src/doc/src/guide/cargo-toml-vs-cargo-lock.md +++ b/src/doc/src/guide/cargo-toml-vs-cargo-lock.md @@ -16,8 +16,8 @@ We recommend pairing this with Let’s dig in a little bit more. -`Cargo.toml` is a [**manifest**][def-manifest] file in which we can specify a -bunch of different metadata about our package. For example, we can say that we +`Cargo.toml` is a [**manifest**][def-manifest] file in which you can specify a +bunch of different metadata about your package. For example, you can say that you depend on another package: ```toml @@ -29,10 +29,10 @@ version = "0.1.0" regex = { git = "https://github.com/rust-lang/regex.git" } ``` -This package has a single dependency, on the `regex` 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 default branch to build our package. +This package has a single dependency, on the `regex` library. It states in +this case to rely on a particular Git repository that lives on +GitHub. Since you haven’t specified any other information, Cargo assumes that +you intend to use the latest commit on the default branch to build our package. Sound good? Well, there’s one problem: If you build this package today, and then you send a copy to me, and I build this package tomorrow, something bad @@ -40,7 +40,7 @@ could happen. There could be more commits to `regex` 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 defining a specific `rev` value in our `Cargo.toml`, +You could fix this problem by defining a specific `rev` value in our `Cargo.toml`, so Cargo could know exactly which revision to use when building the package: ```toml @@ -48,12 +48,12 @@ so Cargo could know exactly which revision to use when building the package: regex = { git = "https://github.com/rust-lang/regex.git", rev = "9f9f693" } ``` -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 +Now our builds will be the same. But there’s a big drawback: now you have to +manually think about SHA-1s every time you 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 +Enter the `Cargo.lock`. Because of its existence, you don’t need to manually +keep track of the exact revisions: Cargo will do it for you. When you have a manifest like this: ```toml @@ -65,8 +65,8 @@ version = "0.1.0" regex = { git = "https://github.com/rust-lang/regex.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: +Cargo will take the latest commit and write that information out into your +`Cargo.lock` when you build for the first time. That file will look like this: ```toml [[package]] @@ -83,12 +83,12 @@ source = "git+https://github.com/rust-lang/regex.git#9f9f693768c584971a4d53bc3c5 ``` You can see that there’s a lot more information here, including the exact -revision we used to build. Now when you give your package to someone else, -they’ll use the exact same SHA, even though we didn’t specify it in our +revision you used to build. Now when you give your package to someone else, +they’ll use the exact same SHA, even though you didn’t specify it in your `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: +When you're ready to opt in to a new version of the library, Cargo can +re-calculate the dependencies and update things for you: ```console $ cargo update # updates all dependencies diff --git a/src/doc/src/guide/creating-a-new-project.md b/src/doc/src/guide/creating-a-new-project.md index 49fbc088032..f12fb865025 100644 --- a/src/doc/src/guide/creating-a-new-project.md +++ b/src/doc/src/guide/creating-a-new-project.md @@ -47,7 +47,7 @@ fn main() { } ``` -Cargo generated a “hello world” program for us, otherwise known as a +Cargo generated a “hello world” program for you, otherwise known as a [*binary crate*][def-crate]. Let’s compile it: ```console @@ -62,7 +62,7 @@ $ ./target/debug/hello_world Hello, world! ``` -We can also use `cargo run` to compile and then run it, all in one step (You +You 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): @@ -73,8 +73,8 @@ $ cargo run Hello, world! ``` -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. +You’ll now notice a new file, `Cargo.lock`. It contains information about your +dependencies. Since there are none 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: diff --git a/src/doc/src/guide/dependencies.md b/src/doc/src/guide/dependencies.md index 150b5f31d4f..531fe505b23 100644 --- a/src/doc/src/guide/dependencies.md +++ b/src/doc/src/guide/dependencies.md @@ -26,7 +26,7 @@ the options you have here. [SemVer]: https://semver.org -If we also wanted to add a dependency on the `regex` crate, we would not need +If you also wanted to add a dependency on the `regex` crate, you 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: @@ -63,11 +63,11 @@ $ cargo build Compiling hello_world v0.1.0 (file:///path/to/package/hello_world) ``` -Our `Cargo.lock` contains the exact information about which revision of all of -these dependencies we used. +`Cargo.lock` contains the exact information about which revision was used +for all of these dependencies. -Now, if `regex` gets updated, we will still build with the same revision until -we choose to run `cargo update`. +Now, if `regex` gets updated, you will still build with the same revision until +you choose to run `cargo update`. You can now use the `regex` library in `main.rs`. diff --git a/src/doc/src/guide/tests.md b/src/doc/src/guide/tests.md index 0148c912063..554f5be14f1 100644 --- a/src/doc/src/guide/tests.md +++ b/src/doc/src/guide/tests.md @@ -20,7 +20,7 @@ running 0 tests test result: ok. 0 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out ``` -If our package had tests, we would see more output with the correct number of +If your package had tests, you would see more output with the correct number of tests. You can also run a specific test by passing a filter: diff --git a/src/doc/src/guide/why-cargo-exists.md b/src/doc/src/guide/why-cargo-exists.md index b9532dc6136..1375cd8d24d 100644 --- a/src/doc/src/guide/why-cargo-exists.md +++ b/src/doc/src/guide/why-cargo-exists.md @@ -14,9 +14,9 @@ $ ./hello Hello, world! ``` -Note that the above command required that we specify the file name -explicitly. If we were to directly use `rustc` to compile a different program, -a different command line invocation would be required. If we needed to specify +Note that the above command required that you specify the file name +explicitly. If you were to directly use `rustc` to compile a different program, +a different command line invocation would be required. If you needed to specify any specific compiler flags or include external dependencies, then the needed command would be even more specific (and complex). @@ -26,7 +26,7 @@ dependencies. Obtaining the correct versions of all the necessary dependencies and keeping them up to date would be hard and error-prone if done by hand. -Rather than work only with crates and `rustc`, we can avoid the difficulties +Rather than work only with crates and `rustc`, you can avoid the difficulties involved with performing the above tasks by introducing a higher-level ["*package*"][def-package] abstraction and by using a [*package manager*][def-package-manager]. @@ -49,11 +49,11 @@ To a large extent, Cargo normalizes the commands needed to build a given program or library; this is one aspect to the above mentioned conventions. As we show later, the same command can be used to build different [*artifacts*][def-artifact], regardless of their names. Rather than invoke -`rustc` directly, we can instead invoke something generic such as `cargo +`rustc` directly, you can instead invoke something generic such as `cargo build` and let cargo worry about constructing the correct `rustc` invocation. Furthermore, Cargo will automatically fetch any dependencies -we have defined for our artifact from a [*registry*][def-registry], -and arrange for them to be added into our build as needed. +you have defined for your artifact from a [*registry*][def-registry], +and arrange for them to be added into your build as needed. It is only a slight exaggeration to say that once you know how to build one Cargo-based project, you know how to build *all* of them.