From 833e66318f0009768a0873baeaffad6992a849f1 Mon Sep 17 00:00:00 2001 From: Steve Klabnik Date: Sun, 14 Jun 2020 08:21:52 -0500 Subject: [PATCH] Clarify some package/crate distinctions in chapter 14 Fixes #2287 --- src/ch14-03-cargo-workspaces.md | 38 +++++++++++++++++---------------- 1 file changed, 20 insertions(+), 18 deletions(-) diff --git a/src/ch14-03-cargo-workspaces.md b/src/ch14-03-cargo-workspaces.md index aae75f9eaa..13ea37769c 100644 --- a/src/ch14-03-cargo-workspaces.md +++ b/src/ch14-03-cargo-workspaces.md @@ -28,7 +28,8 @@ Next, in the *add* directory, we create the *Cargo.toml* file that will configure the entire workspace. This file won’t have a `[package]` section or the metadata we’ve seen in other *Cargo.toml* files. Instead, it will start with a `[workspace]` section that will allow us to add members to the workspace -by specifying the path to our binary crate; in this case, that path is *adder*: +by specifying the path to the package with our binary crate; in this case, +that path is *adder*: Filename: Cargo.toml @@ -65,7 +66,7 @@ in your *add* directory should look like this: ``` The workspace has one *target* directory at the top level for the compiled -artifacts to be placed into; the `adder` crate doesn’t have its own *target* +artifacts to be placed into; the `adder` package doesn’t have its own *target* directory. Even if we were to run `cargo build` from inside the *adder* directory, the compiled artifacts would still end up in *add/target* rather than *add/adder/target*. Cargo structures the *target* directory in a workspace @@ -75,9 +76,9 @@ recompile each of the other crates in the workspace to have the artifacts in its own *target* directory. By sharing one *target* directory, the crates can avoid unnecessary rebuilding. -### Creating the Second Crate in the Workspace +### Creating the Second Package in the Workspace -Next, let’s create another member crate in the workspace and call it `add-one`. +Next, let’s create another member package in the workspace and call it `add-one`. Change the top-level *Cargo.toml* to specify the *add-one* path in the `members` list: @@ -125,9 +126,10 @@ In the *add-one/src/lib.rs* file, let’s add an `add_one` function: {{#rustdoc_include ../listings/ch14-more-about-cargo/no-listing-02-workspace-with-two-crates/add/add-one/src/lib.rs}} ``` -Now that we have a library crate in the workspace, we can have the binary crate -`adder` depend on the library crate `add-one`. First, we’ll need to add a path -dependency on `add-one` to *adder/Cargo.toml*. +Now that we have another package in the workspace, we can have the `adder` +package with our binary depend on the `add-one` package, that has our +library. First, we’ll need to add a path dependency on `add-one` to +*adder/Cargo.toml*. Filename: adder/Cargo.toml @@ -149,8 +151,8 @@ function to call the `add_one` function, as in Listing 14-7. {{#rustdoc_include ../listings/ch14-more-about-cargo/listing-14-07/add/adder/src/main.rs}} ``` -Listing 14-7: Using the `add-one` library crate from the -`adder` crate +Listing 14-7: Using the `add-one` library crate from the + `adder` crate Let’s build the workspace by running `cargo build` in the top-level *add* directory! @@ -187,12 +189,12 @@ Hello, world! 10 plus one is 11! This runs the code in *adder/src/main.rs*, which depends on the `add-one` crate. -#### Depending on an External Crate in a Workspace +#### Depending on an External Package in a Workspace Notice that the workspace has only one *Cargo.lock* file at the top level of the workspace rather than having a *Cargo.lock* in each crate’s directory. This ensures that all crates are using the same version of all dependencies. If we -add the `rand` crate to the *adder/Cargo.toml* and *add-one/Cargo.toml* +add the `rand` package to the *adder/Cargo.toml* and *add-one/Cargo.toml* files, Cargo will resolve both of those to one version of `rand` and record that in the one *Cargo.lock*. Making all crates in the workspace use the same dependencies means the crates in the workspace will always be compatible with @@ -237,7 +239,7 @@ The top-level *Cargo.lock* now contains information about the dependency of `add-one` on `rand`. However, even though `rand` is used somewhere in the workspace, we can’t use it in other crates in the workspace unless we add `rand` to their *Cargo.toml* files as well. For example, if we add `use rand;` -to the *adder/src/main.rs* file for the `adder` crate, we’ll get an error: +to the *adder/src/main.rs* file for the `adder` package, we’ll get an error: