diff options
Diffstat (limited to 'development/tools/cargo-workspace2/README.md')
| -rw-r--r-- | development/tools/cargo-workspace2/README.md | 90 |
1 files changed, 90 insertions, 0 deletions
diff --git a/development/tools/cargo-workspace2/README.md b/development/tools/cargo-workspace2/README.md new file mode 100644 index 000000000000..c5ae6e7463bf --- /dev/null +++ b/development/tools/cargo-workspace2/README.md @@ -0,0 +1,90 @@ +# cargo-workspace2 🔹 [](https://git.open-communication.net/spacekookie/cargo-workspace2/-/commits/develop) + +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](./docs/ws2ql.md)! + + +### Publishing crates + +This tool was largely written to make publishing crates in a workspace +easier. Let's look at an example. + +```toml +[package] +name = "foo" +version = "0.1.0" +# ... + +[dependencies] +bar = { version = "0.5.0", path = "../bar" } +``` + +```toml +[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](https://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. |