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. 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 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.
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 freshcargo build --timings --releaseon my development workstation, itsclap_builderdependency 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-dependenciescannot be conditional on crate features. Potentially using othercfghacks 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-xtaskconvention to define an auxiliary crate to move the manpage generation logic and dependencies to, which is not part of theoxipngcrate published oncrates.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
mangenxtask can be run at any time withcargo xtask mangen. The generated manpages are now available attarget/xtask/mangen/manpages. Existing deployment scripts were updated accordingly.