PR #596 brought forward automatic generation of Linux manual pages for
Oxipng, which is executed every time Oxipng is built. However, while
building manpages on every build is convenient for Oxipng development
and doing so didn't catch my attention initially, it introduces
noticeable inefficiencies for crates using Oxipng as a library: during
their build, Oxipng manpages are also built, even though most dependent
crates won't use such artifacts, as they are not considered part of the
public Oxipng crate API or even appropriate for non-human consumption.
Moreover, generating manpages depends on `clap`, which is a heavyweight
dependency: according to a fresh `cargo build --timings --release` on my
development workstation, its `clap_builder` dependency is the third most
time consuming unit to build, totalling 1.5 s (out of 11.7 s, or 12.8%).
And there is no way for dependent crates to turn this off:
[`build-dependencies` cannot be conditional on crate
features](https://doc.rust-lang.org/cargo/reference/specifying-dependencies.html#platform-specific-dependencies).
Potentially using other `cfg` hacks to either enable or disable manpage
generation is unergonomic, if not outright disallowed. Besides reducing
their compilation time cost, dependent crates may also want to trim the
size of their dependency tree, avoiding unnecessary dependency downloads
in the process.
Therefore, a better solution to conditionally build manpages in a way
convenient for both Oxipng maintainers and downstream consumers is
needed. My proposal implemented in this PR is to leverage the
[`cargo-xtask`](https://github.com/matklad/cargo-xtask) convention to
define an auxiliary crate to move the manpage generation logic and
dependencies to, which is not part of the `oxipng` crate published on
`crates.io`. That way Oxipng maintainers and packagers can still
generate manpages at request with ease, without any automation being
noticeable to uninterested crate consumers. And as a side benefit,
Oxipng maintainers can also benefit from slightly faster iteration times
due to the lack of a build script for the main crate.
The new `mangen` xtask can be run at any time with `cargo xtask mangen`.
The generated manpages are now available at
`target/xtask/mangen/manpages`. Existing deployment scripts were updated
accordingly.
c81a863e69