Make it easy to list and run all examples

[robinmoussu]

Describe the problem you are trying to solve

Some project have a list of example, usually in the example folder. It would be nice if it was possible to:

1. list them all (so you can run them later with cargo run --example $name_of_the_example)
2. run all of them in one command (it may be useful in CI).
   • a bit like cargo test, this should count the number of panic/non 0 exit code
   • it should be possible to provide a list of arguments that would be passed to each the examples

Describe the solution you'd like

1. I think a new command cargo list that would output (in separate sections) the list of examples, the list of binaries, and the list of libraries provided by the current crate would be a nice addition. It should be possible to filter the output with flags like --example, --binaries or --libraries. Maybe the list of features available could also be listed?

2. I think a new subcommand of cargo run should be added: cargo run --examples. Like cargo run, all arguments after -- should be passed to the examples binaries. It would be equivalent to do:

for example in examples/*.rs
do
    cargo run --example "$(basename "$example")" -- $args
done

A flag --exclude $example may be added to run all examples but $example (and would only make sense if --examples is used). Similarly, cargo run --binaries could be added to run all binaries of a crate.

Notes

In some cases, like a 3d crate, or interactive example, it would not be wise to run all examples but I don't think it's an issue. The proposed cargo list and cargo run --examples would still be really useful for most cases.

[bitdivine]

A tweak, to make the above work for individual crates:

for example in examples/*.rs
do
    cargo run --example "$(basename "${example%.rs}")" -- $args
done

Anything more complicated, including workspaces, need twiddles on the twiddles.

Ah, this works for workspaces:

cargo run --example 2>&1 | grep -E '^ ' | xargs -n1 cargo run --example

And better:

cargo test --examples

[epage]

escargot wraps cargo for programmatic use so you can get all of the examples.

trycmd builds on top of escargot to allow basic testing of examples. You can specify the stdin, arguments, and an example directory to run in and it will match against a custom glob pattern for stdout, stderr, and an example directory as well as specifying what the exit code should be. You can specify these via toml or it can parse code fences in markdown so you can test your documentation. clap uses this to test examples.

[nielsle]

Cargo-examples allows you to run all examples

https://github.com/zxey/cargo-examples

[tgross35]

Came across a similar need today, trying to quickly see what paths in a workspace exist and are build/disabled by default. I can think of a few possible uses for a cargo list subcommand that would allow you to programatically extract some useful information about the crate/workspace:

# List members of a workspace, add `D` if they default-members
$ cargo list workspace
D foo-macros/
D foo/
  plugins/bar/
  plugins/baz/

# List examples
$ cargo list examples
examples/simple.rs
examples/full_crate/

# List all tests (for `cargo test`, condensed output from `cargo test -- --list`)
$ cargo list tests

# List only unit tests
$ cargo list tests:unit

# List only integration tests
$ cargo list tests:integration

# List benchmarks (for `cargo bench`)
$ cargo list benches

[dwbrite]

cargo build --example errors out with a list of the available examples. If you pipe stderr to stdout and skip the first two lines, you get a nice result you can use programmatically.

#!/bin/bash
output=$(cargo build --example 2>&1)
echo "$output" | tail -n +3 | sed 's/^[ \t]*//;s/[ \t]*$//' # sed to trim whitespace

[epage]

The output of cargo build --example is for humans and we do not guarantee compatibility on the format.

Also, cargo metadata --no-deps will list all targets for the workspace.