src/doc/book/src/ch14-03-cargo-workspaces.md

   1 ## Cargo Workspaces
   2
   3 In Chapter 12, we built a package that included a binary crate and a library
   4 crate. As your project develops, you might find that the library crate
   5 continues to get bigger and you want to split your package further into
   6 multiple library crates. Cargo offers a feature called *workspaces* that can
   7 help manage multiple related packages that are developed in tandem.
   8
   9 ### Creating a Workspace
  10
  11 A *workspace* is a set of packages that share the same *Cargo.lock* and output
  12 directory. Let’s make a project using a workspace—we’ll use trivial code so we
  13 can concentrate on the structure of the workspace. There are multiple ways to
  14 structure a workspace, so we'll just show one common way. We’ll have a
  15 workspace containing a binary and two libraries. The binary, which will provide
  16 the main functionality, will depend on the two libraries. One library will
  17 provide an `add_one` function, and a second library an `add_two` function.
  18 These three crates will be part of the same workspace. We’ll start by creating
  19 a new directory for the workspace:
  20
  21 ```console
  22 $ mkdir add
  23 $ cd add
  24 ```
  25
  26 Next, in the *add* directory, we create the *Cargo.toml* file that will
  27 configure the entire workspace. This file won’t have a `[package]` section.
  28 Instead, it will start with a `[workspace]` section that will allow us to add
  29 members to the workspace by specifying the path to the package with our binary
  30 crate; in this case, that path is *adder*:
  31
  32 <span class="filename">Filename: Cargo.toml</span>
  33
  34 ```toml
  35 {{#include ../listings/ch14-more-about-cargo/no-listing-01-workspace-with-adder-crate/add/Cargo.toml}}
  36 ```
  37
  38 Next, we’ll create the `adder` binary crate by running `cargo new` within the
  39 *add* directory:
  40
  41 <!-- manual-regeneration
  42 cd listings/ch14-more-about-cargo/output-only-01-adder-crate/add
  43 rm -rf adder
  44 cargo new adder
  45 copy output below
  46 -->
  47
  48 ```console
  49 $ cargo new adder
  50      Created binary (application) `adder` package
  51 ```
  52
  53 At this point, we can build the workspace by running `cargo build`. The files
  54 in your *add* directory should look like this:
  55
  56 ```text
  57 ├── Cargo.lock
  58 ├── Cargo.toml
  59 ├── adder
  60 │   ├── Cargo.toml
  61 │   └── src
  62 │       └── main.rs
  63 └── target
  64 ```
  65
  66 The workspace has one *target* directory at the top level that the compiled
  67 artifacts will be placed into; the `adder` package doesn’t have its own
  68 *target* directory. Even if we were to run `cargo build` from inside the
  69 *adder* directory, the compiled artifacts would still end up in *add/target*
  70 rather than *add/adder/target*. Cargo structures the *target* directory in a
  71 workspace like this because the crates in a workspace are meant to depend on
  72 each other. If each crate had its own *target* directory, each crate would have
  73 to recompile each of the other crates in the workspace to place the artifacts
  74 in its own *target* directory. By sharing one *target* directory, the crates
  75 can avoid unnecessary rebuilding.
  76
  77 ### Creating the Second Package in the Workspace
  78
  79 Next, let’s create another member package in the workspace and call it
  80 `add_one`. Change the top-level *Cargo.toml* to specify the *add_one* path in
  81 the `members` list:
  82
  83 <span class="filename">Filename: Cargo.toml</span>
  84
  85 ```toml
  86 {{#include ../listings/ch14-more-about-cargo/no-listing-02-workspace-with-two-crates/add/Cargo.toml}}
  87 ```
  88
  89 Then generate a new library crate named `add_one`:
  90
  91 <!-- manual-regeneration
  92 cd listings/ch14-more-about-cargo/output-only-02-add-one/add
  93 rm -rf add_one
  94 cargo new add_one --lib
  95 copy output below
  96 -->
  97
  98 ```console
  99 $ cargo new add_one --lib
 100      Created library `add_one` package
 101 ```
 102
 103 Your *add* directory should now have these directories and files:
 104
 105 ```text
 106 ├── Cargo.lock
 107 ├── Cargo.toml
 108 ├── add_one
 109 │   ├── Cargo.toml
 110 │   └── src
 111 │       └── lib.rs
 112 ├── adder
 113 │   ├── Cargo.toml
 114 │   └── src
 115 │       └── main.rs
 116 └── target
 117 ```
 118
 119 In the *add_one/src/lib.rs* file, let’s add an `add_one` function:
 120
 121 <span class="filename">Filename: add_one/src/lib.rs</span>
 122
 123 ```rust,noplayground
 124 {{#rustdoc_include ../listings/ch14-more-about-cargo/no-listing-02-workspace-with-two-crates/add/add_one/src/lib.rs}}
 125 ```
 126
 127 Now we can have the `adder` package with our binary depend on the `add_one`
 128 package that has our library. First, we’ll need to add a path dependency on
 129 `add_one` to *adder/Cargo.toml*.
 130
 131 <span class="filename">Filename: adder/Cargo.toml</span>
 132
 133 ```toml
 134 {{#include ../listings/ch14-more-about-cargo/no-listing-02-workspace-with-two-crates/add/adder/Cargo.toml:6:7}}
 135 ```
 136
 137 Cargo doesn’t assume that crates in a workspace will depend on each other, so
 138 we need to be explicit about the dependency relationships.
 139
 140 Next, let’s use the `add_one` function (from the `add_one` crate) in the
 141 `adder` crate. Open the *adder/src/main.rs* file and add a `use` line at the
 142 top to bring the new `add_one` library crate into scope. Then change the `main`
 143 function to call the `add_one` function, as in Listing 14-7.
 144
 145 <span class="filename">Filename: adder/src/main.rs</span>
 146
 147 ```rust,ignore
 148 {{#rustdoc_include ../listings/ch14-more-about-cargo/listing-14-07/add/adder/src/main.rs}}
 149 ```
 150
 151 <span class="caption">Listing 14-7: Using the `add_one` library crate from the
 152  `adder` crate</span>
 153
 154 Let’s build the workspace by running `cargo build` in the top-level *add*
 155 directory!
 156
 157 <!-- manual-regeneration
 158 cd listings/ch14-more-about-cargo/listing-14-07/add
 159 cargo build
 160 copy output below; the output updating script doesn't handle subdirectories in paths properly
 161 -->
 162
 163 ```console
 164 $ cargo build
 165    Compiling add_one v0.1.0 (file:///projects/add/add_one)
 166    Compiling adder v0.1.0 (file:///projects/add/adder)
 167     Finished dev [unoptimized + debuginfo] target(s) in 0.68s
 168 ```
 169
 170 To run the binary crate from the *add* directory, we can specify which
 171 package in the workspace we want to run by using the `-p` argument and the
 172 package name with `cargo run`:
 173
 174 <!-- manual-regeneration
 175 cd listings/ch14-more-about-cargo/listing-14-07/add
 176 cargo run -p adder
 177 copy output below; the output updating script doesn't handle subdirectories in paths properly
 178 -->
 179
 180 ```console
 181 $ cargo run -p adder
 182     Finished dev [unoptimized + debuginfo] target(s) in 0.0s
 183      Running `target/debug/adder`
 184 Hello, world! 10 plus one is 11!
 185 ```
 186
 187 This runs the code in *adder/src/main.rs*, which depends on the `add_one` crate.
 188
 189 #### Depending on an External Package in a Workspace
 190
 191 Notice that the workspace has only one *Cargo.lock* file at the top level,
 192 rather than having a *Cargo.lock* in each crate’s directory. This ensures that
 193 all crates are using the same version of all dependencies. If we add the `rand`
 194 package to the *adder/Cargo.toml* and *add_one/Cargo.toml* files, Cargo will
 195 resolve both of those to one version of `rand` and record that in the one
 196 *Cargo.lock*. Making all crates in the workspace use the same dependencies
 197 means the crates will always be compatible with each other. Let’s add the
 198 `rand` crate to the `[dependencies]` section in the *add_one/Cargo.toml* file
 199 so we can use the `rand` crate in the `add_one` crate:
 200
 201 <!-- When updating the version of `rand` used, also update the version of
 202 `rand` used in these files so they all match:
 203 * ch02-00-guessing-game-tutorial.md
 204 * ch07-04-bringing-paths-into-scope-with-the-use-keyword.md
 205 -->
 206
 207 <span class="filename">Filename: add_one/Cargo.toml</span>
 208
 209 ```toml
 210 {{#include ../listings/ch14-more-about-cargo/no-listing-03-workspace-with-external-dependency/add/add_one/Cargo.toml:6:7}}
 211 ```
 212
 213 We can now add `use rand;` to the *add_one/src/lib.rs* file, and building the
 214 whole workspace by running `cargo build` in the *add* directory will bring in
 215 and compile the `rand` crate. We will get one warning because we aren’t
 216 referring to the `rand` we brought into scope:
 217
 218 <!-- manual-regeneration
 219 cd listings/ch14-more-about-cargo/no-listing-03-workspace-with-external-dependency/add
 220 cargo build
 221 copy output below; the output updating script doesn't handle subdirectories in paths properly
 222 -->
 223
 224 ```console
 225 $ cargo build
 226     Updating crates.io index
 227   Downloaded rand v0.8.3
 228    --snip--
 229    Compiling rand v0.8.3
 230    Compiling add_one v0.1.0 (file:///projects/add/add_one)
 231 warning: unused import: `rand`
 232  --> add_one/src/lib.rs:1:5
 233   |
 234 1 | use rand;
 235   |     ^^^^
 236   |
 237   = note: `#[warn(unused_imports)]` on by default
 238
 239 warning: 1 warning emitted
 240
 241    Compiling adder v0.1.0 (file:///projects/add/adder)
 242     Finished dev [unoptimized + debuginfo] target(s) in 10.18s
 243 ```
 244
 245 The top-level *Cargo.lock* now contains information about the dependency of
 246 `add_one` on `rand`. However, even though `rand` is used somewhere in the
 247 workspace, we can’t use it in other crates in the workspace unless we add
 248 `rand` to their *Cargo.toml* files as well. For example, if we add `use rand;`
 249 to the *adder/src/main.rs* file for the `adder` package, we’ll get an error:
 250
 251 <!-- manual-regeneration
 252 cd listings/ch14-more-about-cargo/output-only-03-use-rand/add
 253 cargo build
 254 copy output below; the output updating script doesn't handle subdirectories in paths properly
 255 -->
 256
 257 ```console
 258 $ cargo build
 259   --snip--
 260    Compiling adder v0.1.0 (file:///projects/add/adder)
 261 error[E0432]: unresolved import `rand`
 262  --> adder/src/main.rs:2:5
 263   |
 264 2 | use rand;
 265   |     ^^^^ no external crate `rand`
 266 ```
 267
 268 To fix this, edit the *Cargo.toml* file for the `adder` package and indicate
 269 that `rand` is a dependency for it as well. Building the `adder` package will
 270 add `rand` to the list of dependencies for `adder` in *Cargo.lock*, but no
 271 additional copies of `rand` will be downloaded. Cargo has ensured that every
 272 crate in every package in the workspace using the `rand` package will be using
 273 the same version, saving us space and ensuring that the crates in the workspace
 274 will be compatible with each other.
 275
 276 #### Adding a Test to a Workspace
 277
 278 For another enhancement, let’s add a test of the `add_one::add_one` function
 279 within the `add_one` crate:
 280
 281 <span class="filename">Filename: add_one/src/lib.rs</span>
 282
 283 ```rust,noplayground
 284 {{#rustdoc_include ../listings/ch14-more-about-cargo/no-listing-04-workspace-with-tests/add/add_one/src/lib.rs}}
 285 ```
 286
 287 Now run `cargo test` in the top-level *add* directory. Running `cargo test` in
 288 a workspace structured like this one will run the tests for all the crates in
 289 the workspace:
 290
 291 <!-- manual-regeneration
 292 cd listings/ch14-more-about-cargo/no-listing-04-workspace-with-tests/add
 293 cargo test
 294 copy output below; the output updating script doesn't handle subdirectories in
 295 paths properly
 296 -->
 297
 298 ```console
 299 $ cargo test
 300    Compiling add_one v0.1.0 (file:///projects/add/add_one)
 301    Compiling adder v0.1.0 (file:///projects/add/adder)
 302     Finished test [unoptimized + debuginfo] target(s) in 0.27s
 303      Running target/debug/deps/add_one-f0253159197f7841
 304
 305 running 1 test
 306 test tests::it_works ... ok
 307
 308 test result: ok. 1 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s
 309
 310      Running target/debug/deps/adder-49979ff40686fa8e
 311
 312 running 0 tests
 313
 314 test result: ok. 0 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s
 315
 316    Doc-tests add_one
 317
 318 running 0 tests
 319
 320 test result: ok. 0 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s
 321 ```
 322
 323 The first section of the output shows that the `it_works` test in the `add_one`
 324 crate passed. The next section shows that zero tests were found in the `adder`
 325 crate, and then the last section shows zero documentation tests were found in
 326 the `add_one` crate.
 327
 328 We can also run tests for one particular crate in a workspace from the
 329 top-level directory by using the `-p` flag and specifying the name of the crate
 330 we want to test:
 331
 332 <!-- manual-regeneration
 333 cd listings/ch14-more-about-cargo/no-listing-04-workspace-with-tests/add
 334 cargo test -p add_one
 335 copy output below; the output updating script doesn't handle subdirectories in paths properly
 336 -->
 337
 338 ```console
 339 $ cargo test -p add_one
 340     Finished test [unoptimized + debuginfo] target(s) in 0.00s
 341      Running target/debug/deps/add_one-b3235fea9a156f74
 342
 343 running 1 test
 344 test tests::it_works ... ok
 345
 346 test result: ok. 1 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s
 347
 348    Doc-tests add_one
 349
 350 running 0 tests
 351
 352 test result: ok. 0 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s
 353 ```
 354
 355 This output shows `cargo test` only ran the tests for the `add_one` crate and
 356 didn’t run the `adder` crate tests.
 357
 358 If you publish the crates in the workspace to [crates.io](https://crates.io/),
 359 each crate in the workspace will need to be published separately. Like `cargo
 360 test`, we can publish a particular crate in our workspace by using the `-p`
 361 flag and specifying the name of the crate we want to publish.
 362
 363 For additional practice, add an `add_two` crate to this workspace in a similar
 364 way as the `add_one` crate!
 365
 366 As your project grows, consider using a workspace: it’s easier to understand
 367 smaller, individual components than one big blob of code. Furthermore, keeping
 368 the crates in a workspace can make coordination between crates easier if they
 369 are often changed at the same time.