If you’re working on a big Rust project, you might notice how slow it can take to compile. One way to make things faster is by breaking your project into smaller parts called workspaces. This technique helps manage complex code and speeds up build times. It’s especially handy when your project grows beyond a simple single-crate setup.

What Are Rust Workspaces and Why Use Them?

In Rust, small projects usually consist of just one crate, which is a package of code. But as projects grow, having all code in one crate can slow down compilation. Rust’s cargo tool lets you split your project into multiple crates within a workspace. Think of a workspace as a collection of smaller, manageable subprojects that work together.

Using workspaces isn’t just about organization. It also improves compile times. When you change code in one subcrate, only that part needs to be recompiled. The rest of the project stays cached, so subsequent builds are faster. This setup makes development smoother, especially for larger apps or when multiple developers are involved.

Setting Up a Rust Workspace

Starting a workspace involves a few steps. First, create a directory for your entire project. Inside it, create a special file called Cargo.lock with the line [workspace] resolver = “3”. This tells cargo that your directory is a workspace. The resolver version “3” is the latest, and it’s recommended for most new projects.

Next, go into the main directory and create your main crate with cargo new. For example, cargo new my_project. This creates a folder named my_project with its own Cargo.toml file and source code. The top-level Cargo.toml will automatically include a line like members = [“my_project”] under the [workspace] section. This registers your main crate as part of the workspace.

To add more parts, you create additional crates inside the workspace. Use cargo new –lib to make library crates for dependencies. For example, cargo new subcrate1 –lib and cargo new subcrate2 –lib. These subcrates are not standalone programs but modules that your main project can depend on.

Connecting the Dots: Dependencies and Code Sharing

Once your subcrates are set up, you need to tell your main crate how they relate. Open the main crate’s Cargo.toml and add dependencies for each subcrate, specifying their relative paths. For example:

[dependencies]
subcrate1 = { path = "../subcrate1" }
subcrate2 = { path = "../subcrate2" }

If one subcrate depends on another, you add that dependency in the same way. For instance, if subcrate1 needs subcrate3, you list subcrate3 in subcrate1’s dependencies.

Working with code inside a workspace is straightforward. The main crate’s src directory contains main.rs, which is the program’s entry point. Other crates have lib.rs files, where you put shared functions. You can call functions across crates by using their namespace, like subcrate1::fn1(). Your editor will usually help with suggestions and auto-completion.

Advantages of Using Workspaces in Rust

One of the biggest perks of splitting your project into workspaces is faster compilation. When you build the project with cargo build, only the changed crates are recompiled. The rest are cached, saving you time. This makes development more efficient, especially during iterative testing.

It’s important to keep the main entry point simple. The less code in main.rs, the quicker the project recompiles after changes. Also, you can compile individual crates directly with commands like cargo build -p subcrate1 if needed. Usually, cargo figures out what needs rebuilding automatically, but this command is handy for targeted work.

Remember that if you run cargo clean, all cached builds are wiped, and everything must be rebuilt from scratch. The benefits of caching are most noticeable when you keep your build profiles consistent. For example, working in debug mode will cache build artifacts, but switching to release mode requires a full rebuild.

Planning your project for a workspace can be tricky, especially if you’re converting an existing project. Think about how to logically split your code. For example, a program with a user interface can be separated into the main logic, the UI, and command-line handling. For new projects, planning this upfront makes setup easier. For existing projects, you can migrate functions gradually, moving parts into subcrates one at a time. This way, you can test and adjust your structure without overwhelming yourself.

Splitting projects into workspaces isn’t just about speeding up compile times. It also helps keep your code organized, manageable, and easier to maintain as it grows. With a bit of planning, workspaces can make your Rust development much smoother and more efficient.

Inspired by

• https://www.infoworld.com/article/4050654/organize-rust-projects-for-faster-compilation-with-cargo-workspaces.html

Sources

• gmpg.org
• siia.net
• podigee.com
• podigee.com