Workspaces

Author: dumindu

content/en/docs/d5.workspaces.md

@@ -3,78 +3,154 @@ title: Workspaces
 slug: workspaces
 ---
 
-> [!caution]
-> This needs a refresh!
-
-When the code base is getting larger, you might need to work with **multiple crates on the same project**. Rust supports this via Workspaces. You can **analyze (`cargo check`), build, run tests or generate docs for all crates** at once by running `cargo` commands from the project root.
-
-⭐️ When working on multiple crates same time, there is a higher possibility of having shared dependencies on crates. To prevent downloading and compiling the same dependency multiple times, Rust uses a **shared build directory** under the project root, while running `cargo build` from the project root.
-
-Let's create a library crate with a simple hello world function and a binary crate which uses the library crate.
-
-Assume we run,
-```bash
-mkdir greetings
-touch greetings/Cargo.toml
-cargo new greetings/lib --lib
-cargo new greetings/examples/hello
+## Rust Workspaces
+
+- Rust workspaces provide a convenient way to manage multiple related crates together as a single project or monorepo.
+- A Rust workspace uses a shared `Cargo.lock` file and a common `target` directory to efficiently build and manage shared dependencies, reducing build times.
+- Cargo commands such as `cargo test`, `cargo build`, `cargo check`, `cargo fmt`, `cargo clippy`, and `cargo clean` can be run once from the workspace root to apply to all workspace members.
+
+## Simple
+
+Let's build a sample Rust workspace with two simple crates.
+
+> [!lab]
+> ```shell
+> mkdir my_project && cd my_project
+> echo -e "[workspace]\nresolver = \"3\"" > ./Cargo.toml
+> cargo new app_bar && cargo new app_buzz
+> cargo add uuid -F v7 -p app_bar && cargo add uuid -F v7 -p app_buzz
+> 
+> echo 'fn main() {
+> \tprintln!("Bar ID: {}", uuid::Uuid::now_v7());
+> }' > app_bar/src/main.rs
+> 
+> echo 'fn main() {
+> \tprintln!("Buzz ID: {}", uuid::Uuid::now_v7());
+> }' > app_buzz/src/main.rs
+> ```
+
+```shell {title="Folder Structure"}
+my_project
+├── app_bar
+│   ├── Cargo.toml
+│   └── src
+│       └── main.rs
+├── app_buzz
+│   ├── Cargo.toml
+│   └── src
+│       └── main.rs
+├── Cargo.lock
+└── Cargo.toml
 ```
 
-That generates,
-```bash
-greetings
- ├── Cargo.toml
- ├── examples
- │  └── hello
- │     ├── Cargo.toml
- │     └── src
- │        └── main.rs
- └── lib
-    ├── Cargo.toml
-    └── src
-       └── lib.rs
+{{< tabs count=3 label="Select File" >}}
+{{< tab label="app_bar → main.rs" >}}
+```rust {title="my_project/app_bar/src/main.rs"}
+fn main() {
+    println!("Bar ID: {}", uuid::Uuid::now_v7());
+}
 ```
-
-We have to modify the following files,
-```rust
-// 01. greetings/Cargo.toml to mark as a workspace and to add members
+{{< /tab >}}
+{{< tab label="app_buzz → main.rs" >}}
+```rust {title="my_project/app_buzz/src/main.rs"}
+fn main() {
+    println!("Buzz ID: {}", uuid::Uuid::now_v7());
+}
+```
+{{< /tab >}}
+{{< tab label="Cargo.toml" >}}
+```toml {title="my_project/Cargo.toml"}
 [workspace]
-members = [
-    "lib",
-    "examples/hello"
-]
+resolver = "3"
+members = ["app_bar", "app_buzz"]
+```
+{{< /tab >}}
+{{< /tabs >}}
+
+As you can see, 
+- Cargo commands can automatically add workspace members to the `Cargo.toml` file in the workspace root(`my_project`).
+- Try running `cargo build` and observe how each dependency is compiled only once through the shared `target` directory in the workspace root.
+
+> [!assignment]
+> - Examine the `Cargo.toml` files in the workspace root and in each crate, and identify the main tables(sections) they contain.
+> - Examine the `Cargo.lock` file in the workspace root and identify how the `app_buzz` and `app_bar` crates record their dependencies.
+> - Run `cargo run -p app_bar` and `cargo run -p app_buzz` commands from the workspace root.
+
+## Advanced
+
+> [!lab]
+> ```
+> mkdir my_project2 && cd my_project2
+> echo -e "[workspace]\nresolver = \"3\"\nmembers = [\"crates/*\"]" > ./Cargo.toml
+> cargo new crates/bar && cargo new crates/buzz
+> cargo new crates/common --lib
+> ```
+
+```shell {title="Folder Structure"}
+my_project
+├── crates
+│   ├── bar
+│   │   ├── Cargo.toml
+│   │   └── src
+│   │       └── main.rs
+│   ├── buzz
+│   │   ├── Cargo.toml
+│   │   └── src
+│   │       └── main.rs
+│   └── common
+│       ├── Cargo.toml
+│       └── src
+│           └── lib.rs
+├── Cargo.toml
+└── Cargo.lock
+```
 
-// 02.1 greetings/lib/Cargo.toml to change the package name to greetings
+- To use the `common` crate from `crates/bar` and `crates/buzz`,
+  - We have to add `common` crate as a dependency in both `crates/bar/Cargo.toml` and `crates/buzz/Cargo.toml`.
+    ```toml
+    [dependencies]
+    common = { path = "../common" }
+    ```
+  - Then, we can use the `common` crate like any other dependency in `crates/bar` and `crates/buzz`.
+    ```rust
+    fn main() {
+        let x = common::add(1, 1);
+        println!("{x}");
+    }
+    ```
+
+{{< tabs count=3 label="Select File" >}}
+{{< tab label="bar → Cargo.toml" >}}
+```toml {title="my_project2/crates/bar/Cargo.toml"}
 [package]
-name = "greetings"
+name = "bar"
 version = "0.1.0"
-authors = ["Dumindu Madunuwan"]
+edition = "2024"
 
 [dependencies]
-
-// 02.2 greetings/lib/src/lib.rs to add a simple hello world function
-pub fn hello() {
-    println!("Hello, world!");
-}
-
-// 03.1 greetings/examples/hello/Cargo.toml to add the `greetings` lib as a dependency
+common = { path = "../common" }
+```
+{{< /tab >}}
+{{< tab label="buzz → Cargo.toml" >}}
+```toml {title="my_project2/crates/buzz/Cargo.toml"}
 [package]
-name = "hello"
+name = "buzz"
 version = "0.1.0"
-authors = ["Dumindu Madunuwan"]
+edition = "2024"
 
 [dependencies]
-greetings = { path = "../../lib" }
-
-// 03.2 greetings/examples/hello/src/main.rs to import the `greetings` lib and call its hello world function
-extern crate greetings;
-
-fn main() {
-    greetings::hello();
-}
+common = { path = "../common" }
 ```
+{{< /tab >}}
+{{< tab label="my_project2 → Cargo.toml" >}}
+```toml {title="my_project/Cargo.toml"}
+[workspace]
+resolver = "3"
+members = ["crates/*"]
+```
+{{< /tab >}}
+{{< /tabs >}}
 
-💡 On Linux and Mac, you can run `cargo` commands on each crate without changing the working directory all the times via Subshells (A command list embedded between parentheses). For example, if you are in the `greetings` directory, even you run `(cd examples/hello && cargo run)` your working directory will be kept  as same in `greetings` folder.
+## 👨‍🏫 Before going to the next...
 
-> [!assignment]
-> [rust-lang/rust library folder](https://github.com/rust-lang/rust/tree/main/library) is a good example for a workspace.
+- [rust-lang/rust library folder](https://github.com/rust-lang/rust/tree/main/library) is a good example for a workspace. Explore and identify Rust library workspace structure.

docs/assets/js/docs.min.43f62ec3fea83ddf9f255731e2b5a0e9694fb8c3199634f3bfdafeefe9b720cc.js

@@ -417,4 +417,4 @@
 <svg height="20" viewBox="0 -960 960 960" width="20"><path d="M216-96q-29.7.0-50.85-21.5T144-168v-528q0-29 21.15-50.5T216-768h72v-60q0-15.3 10.29-25.65Q308.58-864 323.79-864t25.71 10.35Q360-843.3 360-828v60h240v-60q0-15.3 10.29-25.65Q620.58-864 635.79-864t25.71 10.35Q672-843.3 672-828v60h72q29.7.0 50.85 21.5T816-696v528q0 29-21.15 50.5T744-96H216zm0-72h528v-360H216v360zm0-432h528v-96H216v96zm0 0v-96 96z"/></svg>
 2016-2026
 <svg height="20" viewBox="0 -960 960 960" width="20"><path d="M319-521q14-28 30.5-54.5T384-628l-55-7-88 88 78 26zm455-270q-79 2-148 41t-125 96q-38 38-68 81t-54 91l102 102q48-24 91-54t81-68q57-57 97.5-129T791-775q0-3-1.5-6t-3.5-5q-2-3-5-4t-7-1zM528-6e2q0-30 21-51t51-21 51 21 21 51-21 51-51 21-51-21-21-51zm-7 281 26 78 88-88-7-55q-26 18-52.5 34.5T521-319zm340-504q13 104-31.5 198T710-456l-8.5 8.5Q698-444 694-439l12 101q2 17-3.5 33T685-278L552-145q-14 13-31.5 9.5T498-156l-51-155-135-136-156-53q-17-5-20-22.5t10-30.5l132-133q12-12 27.5-17.5T338-707l101 13q5-5 9.5-9t9.5-9q75-74 168-119t196-31q8 1 14.5 5t11.5 9 8.5 11 4.5 14zM178-331q31-32 75-30.5t76 33.5q31 31 32.5 74T332-181q-45 47-108.5 60.5T96-96q11-63 24-126.5T178-331zm45 57q-17 17-23 40l-12 46q23-6 45-12t39-23q13-11 14.5-27.5T277-278t-27-9.5T223-274z"/></svg>
-<a class="btn btn-primary" href=https://github.com/learning-rust/learning-rust.github.io target=_blank>GitHub</a></footer></div><div id=off-canvas-model></div><script src=/assets/js/docs.min.43f62ec3fea83ddf9f255731e2b5a0e9694fb8c3199634f3bfdafeefe9b720cc.js integrity></script><script src=https://learning-rust.github.io/pagefind/pagefind-component-ui.js type=module></script></body></html>
+<a class="btn btn-primary" href=https://github.com/learning-rust/learning-rust.github.io target=_blank>GitHub</a></footer></div><div id=off-canvas-model></div><script src=/assets/js/docs.min.e183be143fc7b87545ffa964089b780f9e8418abeaf311a1092975a438a6b1bb.js integrity></script><script src=https://learning-rust.github.io/pagefind/pagefind-component-ui.js type=module></script></body></html>