Proposal: Better shell completions
ehuss opened this issue · comments
This is a proposal to add better shell completion support to Cargo. The outline of the strategy is:
- Add a
cargo completionssubcommand to assist with completion support. cargo completions <shell>will output a completion script for the given shell (bash, zsh, etc.).- The completion script will execute
cargo completionsto implement the work of actually emitting completions. This can significantly simplify the work of supporting completions for different shells. The completion script is very small (seenpm completionfor an example). This also means all the logic can be written in one language (Rust) and can be more easily tested.
Benefits:
- Support richer completions (such as
--binor--examplecompleting the target name). - Maintain consistent completions across shells.
- Easier to test.
- (Maybe) easier to keep in sync with clap.
- More easily discoverable (who knows the completions even exist?).
- Completions automatically stay in sync with the release via rustup.
Drawbacks:
- More stuff to maintain.
- Minor performance drawback compared to native-shell code. Many of the existing completions already execute commands, so in many cases it is a wash. Cargo's launch speed isn't terrible (~50ms for me).
- Won't be backwards compatible with older versions of Cargo.
Please let me know if you have any thoughts or objections.
cargo completions <shell>will output a completion script for the given shell (bash, zsh, etc.)
I don't know how this works at all, but why do some tool's shell completions just work (e.g., Git) whereas the Rust tools seem to need some kind of opt-in step? Of course, I think it would be nice if we didn't need this opt-in step.
didn't need this opt-in step
It depends on how rust/cargo is installed. Some installers (like ubuntu) will automatically add the completion file to the global location (such as /usr/share/bash-completion/completions/) and it will "just work" assuming your shell is configured to load them. rustup does not do that, since it avoids touching files outside of the user's home directory. rustup could install them in the user's home directory ($XDG_DATA_HOME/bash-completion/completions, and probably something similar for other shells). That would need to be a decision for rustup to make, if it is acceptable to dump files in various locations.
FWIW, I just started learning Rust (cargo), using rustup, and this was pretty much the first thing I hit. 😄
If we want to keep stuff in the user's home directory (as opposed to e.g. /etc/bash_completion.d), one way to do this (for bash) is:
echo 'source <(cargo completion bash)' >> ~/.bashrc
I use said approach with kubectl: https://kubernetes.io/docs/tasks/tools/install-kubectl/#enabling-shell-autocompletion
@ehuss, had you considered looking at how to include something like this in clap (or as an add-on to clap) rather than directly in cargo?
@scooter-dangle In a sense, it will be a clap addon, because it will probably be looking at the (hidden) clap internals to infer the options. My impression is that clap development has stalled and v3 has a long ways to go, so I don't think it is something we can use in the foreseeable future, and there's no indication how new features like this would make progress. There is an issue for this (clap-rs/clap#810), but there's no sense from the issue if it will support custom extensions or how it will work.
I used rustup completions zsh cargo and it is not working. Thanks for the work on this.
Related issue: rust-lang/rustup#1821
See more:
Is it possible to reduce cargo start time or optionally use generated completions as it is faster only a one-time cost?
Is it possible to reduce cargo start time
I'm not sure what you mean here. Cargo should launch in about 25ms, depending on your system. I think that should be plenty fast for completion.
As a workaround, for now I just added a symlink to the installed completions for my current toolchain, in my local completions. On Linux, stable toolchain:
$ ln -s ~/.rustup/toolchains/stable-x86_64-unknown-linux-gnu/etc/bash_completion.d/cargo ~/.local/share/bash-completion/completions/cargo
This will work for a specific toolchain, but the file seems to be a copy of cargo.bashcomp.sh, so I guess it doesn't matter too much.
I would like to add an enhancement to the original feature request.
Interactive fuzzy completions
I got this idea after writing custom fzf wrappers over cmake like this one:
find all cmakelists in a project, grep all invocations of add_library and add_executable, pipe that to fzf, pipe the target selected by the user to cmake build.
Once I wrote this bash function, i could drop into any new cmake project, run my pt-build and have an interactive selector for the tests, libraries or executables that I might want to build.
since cargo already provides a uniform way to build any rust projects, I think it would be great to enable developers to interactively select the build target.
user story
cargo build --example <TAB><TAB>
# a fuzzy finder window appears with all buildable examples as defined in Cargo.toml or examples/
cargo build --bin i_already_know_the_name --features <TAB><TAB>
# a fuzzy finder window appears with all available features to complete
cargo bench <TAB><TAB>
# a fuzzy finder window with all benchmarks appearsRequired building blocks
2 components are required - quickly producing a list of relevant targets (filtered by type) and exposing a fuzzy interface to the user.
Query cargo for all targets to complete with
Bazel and buck build systems have query subcommands that can produce lists of targets filtered by labels like build, test, bench. Cargo should be able to analyze the workspace and list:
binary targets to pass to --bin
example targets to pass to --example
bench targets to pass to --bench
Add a fuzzy completion interface
The fzf-like rust crate is called skim and it provides us with the primitives to expose a fuzzy finder to the user.
https://github.com/lotabout/skim
Once this exists, the bash completion functions can call the corresponding cargo fuzzy-picker depending on the tokens already typed on the command line.
Prior Art/Other build systems
As i was writing this, I found this open feature request on the bazel repo. Great minds think alike!
bazelbuild/bazel#11644
Under-explored
Since cargo enables people to write their own plugins, like cargo fuzz, the target types defined by those need to be made available to original cargo, so they can be listed as completion options. I am not sure how that would work.
If cargo support this, it would be better.
ps: as a gopher, I have used https://github.com/spf13/cobra to build command line tools for a long time, which provides a basic support for generating completion script for bash, zsh, powershell, etc.
It works like ./myapp completion bash > .bash_myapp and add source ~/.bash_myapp into .bashrc.
If cargo support this, it would be better.
ps: as a gopher, I have used https://github.com/spf13/cobra to build command line too for a long time, which provides a basic support for generating completion script for bash, zsh, powershell, etc.
It works like
./myapp completion bash > .bash_myappand addsource ~/.bash_myappinto .bashrc.
FYI: Clap generates completions like that (App::gen_completions_to), but the application needs to expose it. E.g., here's how starship does that.
Relevant clap issues:
- clap-rs/clap#3166 for the core of completions to be in Rust instead of each shell language
- clap-rs/clap#1232 for extending the above with custom code for completing argument values
It seems weirdly inconsistent that rustup completions <bash/zsh/...> is a thing, but cargo completions bash isn't a thing.
For those arriving in the future, the work around to enable these manually (Tested Ubuntu 22.04/20.04) is:
cat $(rustc --print sysroot)/etc/bash_completion.d/cargo > ~/.local/share/bash-completion/completions/cargo
How will this handle security with respect to path specifications in rust-toolchain.toml? It would be pretty bad if doing a cargo command completion inside a malicious repo would cause arbitrary code execution. And even for a non-malicious repo have to wait for rustup to download the toolchain if it isn't already when trying to get completions is annoying. Will the shell completions ensure that they invoke the cargo from which they were generated without going through the rustup wrapper?
I don't think that will be a change from the status quo. The existing completions may call cargo or rustup, depending on the argument.