brandtm / cargo-example Goto Github PK

You're maybe already aware of this, but I recently learned about cargo install --examples. I had looked for easy ways to run examples from crates without manually checking them out and had come across this project. It wasn't until much later that I realized that cargo could do the heavy lifting of getting the source code and building examples, and I put together this shell script based around it that approximates this crate:

cargo_example() (
  if test "$#" -lt 1; then
    echo "usage: cargo_example <crate> <example> [...]"
    return
  fi
  set -e
  crate="$1"; shift
  dir="$HOME/.cargo-examples/$crate"
  if ! test -d "$dir/bin"; then
    cargo install "$crate" --examples --root "$dir"
  fi
  if test "$#" -lt 1; then
    echo "Available examples for crate '$crate':"
    ls "$dir/bin"
    return
  fi  
  command="$1"; shift
  if ! test -x "$dir/bin/$command"; then
    echo "No example '$command' found for crate '$crate' (remove the $dir directory to force a rebuild)"
    return 1
  fi
  "$dir/bin/$command" "$@"
)

There are a few advantages to this approach:

• The source corresponds to the latest published crate version rather than whatever the HEAD of the git repository is; it will also work for crates without repositories, if those exist
  • It would be straightforward to extend to support specifying arbitrary crate versions
• The user's .cargo registry is reused for source caching and a full git clone can be avoided—downloading the crate source should be cheaper
• Intermediate build artifacts are automatically cleaned up by cargo after the build completes
• It depends on fewer details of cargo like the REST API

As a downside, cargo does print a warning about adding the custom root directory to your $PATH after installing, but that can probably be worked around.

I mostly wanted to open this issue to to share the knowledge because this project has good Google placement for queries related to running cargo examples. Given that this seems to mostly be a proof of concept I'm not sure whether you think it'd be worth reworking this crate to use cargo install --examples, but would you at least consider updating this sentence from the README to mention cargo install as an alternative?: "In order to run examples you'll always have to manually clone or download the repository of the crate whose examples you wish to run."

It has to be done this way due to the way that

From skimming the readme I still can't figure out what I need to type to run a crate's example. The readme mentions cargo example ...args but I don't know how to say which crate or which example to run. The readme also mentions cargo run example ...args and cargo --example, neither of which are real commands.

I would expect to see a complete screenshot or console codeblock showing the entire intended usage on some popular crate like rand, as in:

$ cargo example ??? ??? monte-carlo
    Compiling rand v0.7.0 (/git/rand)
    Finished dev [unoptimized + debuginfo] target(s) in 1.56s
    Running `target/debug/examples/monte-carlo`

  π is approximately 3.142296

After the example has finished running control is not returned to the shell. The output seems to freeze and you need to hit enter to be able to type again.
This is definitely caused by the run_command function in main.rs and a side-effect of how the command is invoked. Previously I tried getting the output of the command and just println!()ing it.
Doing that doesn't cause this bug but has one major downside:
You can't get output from cargo in real-time. This is much worse for usability I think because it will look like nothing is happening until the cargo build process has finished, which can take a while.