Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/kevinmgranger/cargo-pando
Perform tasks concurrently over multiple copies of your repo.
https://github.com/kevinmgranger/cargo-pando
Last synced: 12 days ago
JSON representation
Perform tasks concurrently over multiple copies of your repo.
- Host: GitHub
- URL: https://github.com/kevinmgranger/cargo-pando
- Owner: KevinMGranger
- License: mpl-2.0
- Created: 2019-01-06T03:25:50.000Z (almost 6 years ago)
- Default Branch: master
- Last Pushed: 2020-02-14T01:04:28.000Z (almost 5 years ago)
- Last Synced: 2024-12-11T05:37:29.355Z (15 days ago)
- Language: Rust
- Homepage: https://crates.io/crates/cargo-pando
- Size: 74.2 KB
- Stars: 1
- Watchers: 3
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE-MPL-2.0
Awesome Lists containing this project
README
# cargo-pando [![Latest Version]][crates.io] [![Rustc Version 1.34.2+]][rustc] [![Build Status]][travis_ci]
[Latest Version]: https://img.shields.io/crates/v/cargo-pando.svg
[crates.io]: https://crates.io/crates/cargo-pando
[Rustc Version 1.34.2+]: https://img.shields.io/badge/rustc-1.34.2+-lightgray.svg
[rustc]: https://blog.rust-lang.org/2019/05/14/Rust-1.34.2.html
[Build Status]: https://travis-ci.com/KevinMGranger/cargo-pando.svg?branch=master
[travis_ci]: https://travis-ci.com/KevinMGranger/cargo-pando
Perform tasks concurrently over multiple copies of your repo.
- test your code against multiple rust releases in parallel with a snazzy progress bar
- test the index / stage of your repo to validate incremental changes
- do both of the above at the same time
- run some other custom command across any of the above checkouts
The name pando comes from the [clonal colony of "multiple" trees that are actually one single organism](https://en.wikipedia.org/wiki/Pando_(tree)). It is latin for "I spread out".
# Stability
HERE BE DRAGONS. This extension is in the early stages of development and may
cause data loss or worse. Only use if you're very comfortable with git and have backups.
There may also be backwards incompatible changes for each version.
# Installation
From crates.io:
```bash
cargo install cargo-pando
```
To upgrade:
```bash
cargo install cargo-pando --force
```
Or to install a development version from this repo, off of master:
```bash
git clone (repo url here)
cd cargo-pando
cargo install --path .
```
Upgrading:
```bash
git pull origin master
cargo install --path . --force
```
# How it Works
1. Figure out what toolchains to run against, either from the CLI, `.travis.yml`, or just using all the installed ones.
2. Create a copy of the repo's code in `target/pando` _per toolchain_, e.g. `target/pando/1.31.0`. __Note that this is destructive.__
_The configured target dir in your cargo config is respected._
3. Run `rustup run TOOLCHAIN_HERE cargo test` or some other action in each copy of the repo-- in parallel.
For example, `cargo +1.31.0 test` in `target/pando/1.31.0/working_dir`.
Output is logged to `target/pando/TOOLCHAIN_HERE/output`, and each line is printed next to the progress bar for the checkout.
## Caveats
If your tests rely on external resources, keep in mind they won't be in the expected location.
If there are exclusive resources, you'll have to synchronize access yourself.
More parallelism doesn't always make things faster, especially since compilation
can be IO intensive as well as CPU intensive.
# Examples
See `cargo pando help` for more details.
Test the working directory against the toolchains listed in `.travis.yml`:
```bash
cargo pando test
```
Test against every installed toolchain except the default,
limiting it to 2 `cargo test`s at any given time:
```bash
cargo pando --all test -j 2
```
Test each specified toolchain, but only doc tests:
```bash
cargo pando -t stable -t beta test -- --doc
```
If you want to run a single command across all of the checkouts at once,
use print, cut, and xargs:
```bash
cargo pando print | cut -f 2 | xargs ls
```
Run an arbitrary command against each checkout,
substituting the name of the toolchain where applicable:
```bash
cargo pando each echo the toolchain '{}' has been copied
```
If the command does not lend itself well to the single line given
by the progress bars, xargs can help again:
```bash
cargo pando print | cut -f 1 | xargs -L 1 -P 2 echo the toolchain is
```
Any long, frequently used commands can be added to your [cargo aliases](https://doc.rust-lang.org/cargo/reference/config.html). You can even do this per project!
```toml
[alias]
pbt = "pando -t stable -t beta test -- --doc" # pando doc tests
```
## Git
Test the given toolchain against the _index_ (stage) of your repo.
Useful if you're incrementally adding changes to a commit and you want to check that your work in progress still works.
```bash
cargo pando --index -t stable test
```
# Handy related commands
See how much space the pando directory is taking up:
```bash
du -sh target/pando
```
Get rid of it!
```bash
rm -rf target/pando
```
# Bugs / Open Questions
- How can we know what files need to be copied over?
- How can we know when / what files to delete from checkouts?
- How can we tell the canonical name of a toolchain, to not
duplicate between their travis representation
and the --all representation?
# TODO
## 0.3
- [x] get target from cargo metadata instead of assuming
- [x] add support for other exec targets
- [x] print
- [x] cargo
- [x] build
- [x] cmdeach ~~/ cmdall~~ (have it print and consume it via shell / xargs!)
- [x] document that
- [x] heck, document everything
- ~~[ ] document using cargo aliases to help with common sub-commands~~
- ~~[ ] document helpful env vars~~
~~(I can't remember what those last two were about. Oh well.)~~
The first was about literal cargo aliases. Unsure about env vars still.
## 0.4
- [ ] justfile and vagrant "integration" for multimachine (see branch multimachine)
- [ ] setting env var for scripts to communicate stage-based progress
- [ ] document use of `just`
- [ ] how do we abstract having multiple stages for provisioning as well as copying?
- [ ] start writing tests
- [ ] call for (and get) feedback
- [ ] figure out what the earliest compatible rust version is
- [ ] support allowing failures from travis.yml
## 1.0
- [ ] blog post
- [ ] pointing progress bars to stdout
- [ ] answer: would one ever need more than Cargo files, test, and src? (build.rs maybe, and then more?)
## Next
- [ ] invoke subtasks with --message-format=json for better output information?
- [ ] determine number of steps for task from dependency list?
- [ ] colorize / emojify output
## Maybe?
- [ ] tmux integration (might have to refactor when output is created, etc.)
- [ ] Other toolchain selection / isolation mechanisms?
- [ ] Docker?
- [ ] Can we arbitrarily support this? Might not be worth it.
- [ ] vastly cleaning up actions
- [ ] make print take args to select field deliniation (whitespace, null, ASCII tabular)