Support installing extra files (man, completions, etc.)

[joshka]

I'd like a solution for installing shell completion files during installation. Eventually this should be part of cargo install, but it's desirable to shortcut the RFC process by implementing this as a convention (to avoid letting perfect be the enemy of good).

In rust-lang/cargo#2729 (comment) (which covers man pages, but is just as relevant to completions), @matklad summarized one part of a possible solution:

rust-lang/cargo#2729 (comment) implement a custom cargo subcommand which take advantage of the above conventions to provide cargo install-like experience with manpages. With such a tool, a readme for hypothertical Rust cli utility called fabulous would look like this:

# You can use `cargo install` to install the binary
# Note: this won't install man pages or completions
$ cargo install fabulous

# To install with shell completions, use `cargo-install2`
$ cargo install cargo-install2 && cargo install2 fabulous

Existence of such cargo-install2 would make the experience of users of rust utilities better, and it would be a strong data point for eventual RFC and inclusion the functionality into cargo proper.

Action Item: implement cargo install2, advertise that.

As oftentimes manpages and completions are generated programmatically via a "post-build" script, documenting "suggested convention" for this is useful for all the same reasons. (to spitball, the convention might be "run cargo run --manifest-path ./build-dist/Cargo.toml to produce a ./dist folder, which would contain all the files to be packaged in a binary distribution")

(The entire comment is worth reading for more context, I've copied just the most relevant parts).

cargo-binstall seems like it might be a good place to do this experiment.

I propose that:

1. cargo-binstall defines a standard location in release artifacts for picking up man pages, and completions for {bash,fish,zsh} (and metadata for overrides)
2. cargo-binstall installs man pages to $CARGO_HOME/share/man, bash completions to $CARGO_HOME/share/bash-completions/completions (these are checked by man / bash automatically for most systems, fish and zsh completions will need some extra config)
3. ...
4. Profit ?

[NobodyXu]

Yes, if we have a standard for distributing man pages/completion then cargo-binstall can do it

It shouldn't be too difficult implementation wise.

I'd imagine we will have "bash-completion" and "command.man"?

And probably need to support overriding it in package.binstall

I think it's a good idea and I'd welcome any PR for it, I am a bit busy recently and don't have much time to implement features unfortunately.

[joshka]

So this is a little about front-running the standard, so long as you're ok with this existing as part of binstall in general terms, I'm happy to put in some work to make something that works.

[NobodyXu]

Yes I am definitely ok with that, it's just that nowadays I don't have much time myself doing new features.

[passcod]

I'm also going to say that the cargo-dist people probably have an opinion and they already have some kind of manifest which may already support some of this.

[joshka]

I'm also going to say that the cargo-dist people probably have an opinion and they already have some kind of manifest which may already support some of this.

What would be the best way to check that opinion? I'm not super familiar with cargo-dist as a tool.

[passcod]

Asking on their bugtracker or their discord.