Packaging for Linux distros etc

Do you want to package chezmoi_modify_manager in your favourite package manager? Awesome! Here are some helpful notes for you.

  • Please tell me about your package (file a github issue): I will link to any suitable package from the README (with a written caveat that I don't maintain them and thus cannot guarantee that they are up-to-date or safe to use). I maintain the AUR package myself as of writing this (thus there is no disclaimer there).
  • If you need some inspiration for how to build and install properly, you might want to take a look at my AUR PKGBUILD. Arch Linux uses a relatively simply format (bash scripts), so it should be easy to decode and adapt.

How to build

  • When building, please export the environment variable CHEZMOI_MODIFY_MANAGER_BUILDER. This will be reported in chezmoi_modify_manager --doctor, and can be very helpful in bug reports. If you don't set this, --doctor will report it as a warning (assuming that it is an unknown local build on someone's computer).
    • Please set it to a short and truthful value (such as "debian", "homebrew", "aur" etc) that identifies the package ecosystem. If your package build the latest and greatest git version, please add a suffix indicating so (e.g. "aur-git")
    • Especially don't claim to be "github-ci" or "github-release" as those are used for the official binary releases. That would be Not Cool!
  • Build a release build (--release). Rust is really quite slow in debug builds, but very speedy in release builds. The difference between debug and release builds is much larger than for C/C++.
  • Build with --locked: This ensures that the versions of dependencies are exactly the same as upstream. Otherwise, you might get newer supposedly compatible versions. Those may or may not work.
  • Build with the stable Rust toolchain: Nightly or beta is not needed and is just asking for potential issues.
  • You likely want to exclude the built-in self updater (that downloads from Github releases), as your package manager should be used instead. This is easy: pass --no-default-features --features=keyring to cargo build. This will also avoid vendoring C dependencies (in particular libdbus) and instead link them dynamically. If you don't want that, add the vendored feature as well (i.e. --features=keyring,vendored).

And so we arrive at the final (reliable regardless of what environment the user might have) build command:

export CHEZMOI_MODIFY_MANAGER_BUILDER="<your package ecosystem name>"
export RUSTUP_TOOLCHAIN=stable
export CARGO_TARGET_DIR=target
cargo build --locked --release --no-default-features --features=keyring

If you need to download dependencies first (as is best practise for some build systems) this gets split into two phases:

# Download deps
export RUSTUP_TOOLCHAIN=stable
cargo fetch --locked --target "$(rustc -vV | sed -n 's/host: //p')"

# Build
export CHEZMOI_MODIFY_MANAGER_BUILDER=aur
export RUSTUP_TOOLCHAIN=stable
export CARGO_TARGET_DIR=target
cargo build --frozen --release --no-default-features --features=keyring

Note the change from --locked to --frozen in the second command here.

What to install

You should of course install the binary itself chezmoi_modify_manager. However, you might also want to install shell completion files relevant to your platform. These can be generated by executing the built binary with --bpaf-complete-style-<name of shell>. Here is the code from the AUR PKGBUILD to do the entire install:

local _cmd_name="target/release/${pkgname}"
install -Dm0755 -t "$pkgdir/usr/bin/" "$_cmd_name"
mkdir -p "$pkgdir/usr/share/bash-completion/completions/"
mkdir -p "$pkgdir/usr/share/zsh/site-functions/"
mkdir -p "$pkgdir/usr/share/fish/vendor_completions.d/"
"$_cmd_name" --bpaf-complete-style-zsh > "$pkgdir/usr/share/zsh/site-functions/_$pkgname"
"$_cmd_name" --bpaf-complete-style-bash > "$pkgdir/usr/share/bash-completion/completions/$pkgname"
"$_cmd_name" --bpaf-complete-style-fish > "$pkgdir/usr/share/fish/vendor_completions.d/${pkgname}.fish"
# No support to install distro completions in elvish.
# See https://github.com/elves/elvish/issues/1739
#"$_cmd_name" --bpaf-complete-style-elvish

For more info on supported shells, see the bpaf documentation, which is the library used by chezmoi_modify_manager to handle command line parsing.