Rust Workspaces

While working on a Rust project involving multiple libraries and applications, I explored Rust workspaces to manage interconnected components. I found the process somewhat unintuitive and poorly documented, especially when it came to importing libraries into applications. To streamline future efforts, I’ve summarized the steps I followed here.

Why Use Workspaces?

For small projects, a single binary or library is sufficient, created with a simple command like:

cargo new app --bin

However, for larger projects involving multiple libraries and applications that need to interact with each other, Rust workspaces provide a convenient way to organize the structure.

Workspace Structure

Here’s an example structure I used for my project:

.
├── Cargo.lock
├── Cargo.toml
├── app/
│   ├── app1/
│   │   ├── Cargo.lock
│   │   ├── Cargo.toml
│   │   └── src/
│   │       └── main.rs
│   ├── app2/
│   │   ├── Cargo.lock
│   │   ├── Cargo.toml
│   │   └── src/
│           └── main.rs
├── lib/
│   ├── lib1/
│   │   ├── Cargo.lock
│   │   ├── Cargo.toml
│   │   └── src/
│   │       └── lib.rs
│   ├── lib2/
│   │   ├── Cargo.lock
│   │   ├── Cargo.toml
│   │   └── src/
│           └── lib.rs
└── tests/
    ├── some-integration-tests.rs
    └── multi-file-test/
        ├── main.rs
        └── test_module.rs

Setting Up a Workspace

1. Create the Workspace Root

   Start with an empty directory containing a Cargo.toml file:

   [workspace]
   members = []
   

   It would be nice to have a cargo new --workspace workspaceName command, but apparently, it is not implemented.

2. Create Applications and Libraries

   In the same folder, run the following commands to create your applications and libraries:

   cargo new app/app1 --vcs none --bin
   cargo new app/app2 --vcs none --bin
   cargo new lib/lib1 --vcs none --lib
   cargo new lib/lib2 --vcs none --lib
   

   The --vcs none flag prevents each subproject from initializing its own Git repository.

   These commands will automatically update the members section in the workspace’s ./Cargo.toml file, located in the root directory. The resulting file should look like this:

   [workspace]
   members = ["app/app1", "app/app2", "lib/lib1", "lib/lib2"]
   

3. Adding Dependencies in the Workspace

   To make library dependencies available to all applications, add them to the workspace’s ./Cargo.toml:

   [workspace.dependencies]
   lib1 = { path = "lib/lib1" }
   lib2 = { path = "lib/lib2" }
   

Adding Dependencies

To use lib1 in app1, add it as a dependency in ./app/app1/Cargo.toml:

[dependencies]
lib1 = { workspace = true }

Then, in ./app/app1/src/main.rs, you can reference it like this:

use lib1;

fn main() {
    println!("Hello, world!");
    println!("{}", lib1::add(1, 2));
}

Building and Running

To build the entire workspace, use:

cargo build

To execute a specific application (e.g., app1):

cargo run --bin app1

By following this structure, you can effectively manage complex Rust projects while maintaining a clear organization of your codebase.