nomicon/development/tools/cargo-workspace2

cargo-workspace2 🔹

A better tool to manage complex cargo workspaces, by dynamically building a dependency graph of your project to query, and run commands on. This project is both a CLI and a library. A repl is on the roadmap.

Usage

When using cargo-ws2 you first provide it some query to find crates in your workspace, and then a command with it's specific parameters to execute for each crate selected in the query.

cargo ws2 <QUERY LANG> <COMMAND> [COMMAND OPTIONS]

Currently supported commands.

• print - echo the selected crate set
• publish - publish a set of crates

Additionally, there are special "bang commands", that take precedence over other argument line input, and don't have to be put in a particular position.

• !help [COMMAND] - show a help screen for the program, or a specific command
• !version - print the program, rustc version, etc
• !debug - enable debug printing, and parse the rest of the line as normal

cargo-ws2 provides a query system based on the ws2ql query expression language. Following are some examples.

• List crates between [ ]: [ foo bar baz ]
• Or query the dependency graph with a {} block: { foo < } (all crates that depend on foo)
• Include crates by path tree: [ ./foo/* ] (not implemented yet!)
• Even search via regex: [/crate-suffix\$/] (not implemented yet!)

See the full description of ws2ql in the docs!

Publishing crates

This tool was largely written to make publishing crates in a workspace easier. Let's look at an example.

[package]
name = "foo"
version = "0.1.0"
# ...

[dependencies]
bar = { version = "0.5.0", path = "../bar" }

[package]
name = "bar"
version = "0.5.0"

This is a common setup: pointing cargo at the path of bar means that changes to the sources on disk become available, before having to publish to crates.io. But having a version dependency is required when trying to publish, thus we add this too.

Unfortunately now, when we update bar to version 0.6.0 our workspace will stop building, because foo depends on a version of bar that's different from the one we're pointing it to.

What cargo-ws2 does when you run cargo ws2 [bar] publish minor is bump bar to 0.6.0, and also update the dependency line in foo to be { version = "0.6.0", path = "../bar" }, without touching the version of foo.

If you want all dependent crates to be bumped to the same version, prefix your publish level (major, minor, patch, or a semver string) with =.

cargo ws2 [bar] publish =minor will bump both foo, and bar to 0.6.0 (picking the highest version of the set if their starting versions are not yet the same.

License

cargo-workspace2 is free software, licensed under the GNU General Public License 3.0 (or later). See the LICENSE file for a full copy of the license.