On packaging Ouch

This page is for 0.4.0, which has not been released yet, but it's about to.

Thanks for your interest in helping Ouch!

This page can be edited by anyone, feel free to add more details to it.

If necessary, you can start a discussion at https://github.com/ouch-org/ouch/discussions.

Breaking changes for packaging

Since 0.4.0 (November 2022)

• Ouch can now generate its own man pages (used to rely on help2man).
• ENV VAR for building artifacts has changed (see below).

Download binary or build manually

If you can choose, I recommend your package to download the tarball with everything so that the user does not have to download the nightly toolchain.

Runtime dependencies

If you're shipping this to Linux x86_64, then I strongly recommend downloading (or building) the musl static binary version of ouch, as it does not require any runtime dependencies (huge benefit IMHO).

Otherwise, you'll need runtime dependencies, check https://github.com/ouch-org/ouch#dependencies for a list.

How to build artifacts

Run cargo build with the OUCH_ARTIFACTS_FOLDER env var set.

OUCH_ARTIFACTS_FOLDER=artifacts cargo build

This tells the script at build.rs to:

• Generate shell completions.
• Generate man pages.

At the provided folder, in this case, we passed the folder name artifacts.

tree artifacts
├── ouch.1             # man page
├── ouch-compress.1    # man page - subcommand 'compress'
├── ouch-decompress.1  # man page - subcommand 'decompress'
├── ouch-list.1        # man page - subcommand 'list'
├── _ouch              # shell completions for Zsh
├── ouch.bash          # shell completions for Bash
├── ouch.elv           # shell completions for Elvish
├── ouch.fish          # shell completions for Fish
└── _ouch.ps1          # shell completions for PowerShell

Save time on compiling

If your package builds artifacts (manpage and completions) and then compiles Ouch with optimizations, it might compile the project twice.

# To generate manpage and completion artifacts
OUCH_ARTIFACTS_FOLDER=artifacts cargo build # Builds without optimizations

# To build the end binary
cargo build --release # Builds with optimization

Instead of this, run the first command with --release, this way, Ouch will run both builds in the same profile, as fast as the latter.

OUCH_ARTIFACTS_FOLDER=artifacts cargo build --release