Unclear how to handle man page generation

[julianandrews]

I use help2man to generate the man page for my project, and that needs to run post-build but before deb generation. Right now I generate the man page manually and add it to the repo. That works, but isn't ideal.

Since cargo build doesn't support post-build scripts, I was hoping there would be some way to tell cargo deb to run some post-build logic, but I'm not seeing a clean way to make that happen.

Is there a recommended way to generate the man page (or generally do post-build pre-cargo-deb logic)?

[ximon18]

Use --no-build and handle this youreelf?

[kornelski]

Cargo doesn't support generation of man pages:

rust-lang/cargo#545

and cargo-deb just wraps cargo build, so you need to create a workaround for this yourself.

[julianandrews]

I thought that might be the case, but wanted to check. Thanks!

I should be able to cobble something together using --no-build and some manual logic. For my purposes I can just write a shell script to generate the .deb. It won't be cross-platform, but then neither is help2man so that's no loss for me.

It would be really helpful if there were some documentation somewhere suggesting workarounds. Though, I recognize that as things stand there isn't an obvious best approach to recommend which makes that kind of tricky.

[AlexTMjugador]

I realize I'm probably a bit late to this party, but the cargo-xtask convention is probably what you're looking for to implement custom post-build steps like this.

[julianandrews]

I realize I'm probably a bit late to this party, but the cargo-xtask convention is probably what you're looking for to implement custom post-build steps like this.

Yeah, I looked at cargo-xtask. In the end I decided that for my use case, where I basically just want to call help2man that would add a lot of boilerplate for minimal benefit over just calling a shell script from CI. I definitely don't want to re-arrange my whole project layout for workspaces to enable man page building, and while that's not strictly required, the README explicitly recommends against doing xtasks without workspaces.

I can see how cargo-xtask could be useful when you need to do something complicated, or if you need cross platform compatibility, but it's hard to justify all that added complexity when what I want to do is just a few lines of bash.

[ppom0]

You can run help2man in your build.rs file, as done here (even if it's not the same manual system):
https://framagit.org/ppom/reaction/-/blob/1a57481110a456f2015f0c1039c10e8791465d83/build.rs
Then copy the man pages using the assets attribute, that will automatically get gzipped by cargo-deb.

[julianandrews]

You can run help2man in your build.rs file, as done here (even if it's not the same manual system): https://framagit.org/ppom/reaction/-/blob/1a57481110a456f2015f0c1039c10e8791465d83/build.rs Then copy the man pages using the assets attribute, that will automatically get gzipped by cargo-deb.

Huh, right. I really should have thought of that. I'll have to try that out.

I don't want to try to build the man page in every environment - help2man really isn't a build dependency of my project as a whole. But I could absolutely call it for cargo deb runs, and fail with a useful message if help2man isn't available.

Does anyone happen to know if there's an easy way to determine inside build.rs if the build was run with cargo deb?

[AlexTMjugador]

Does anyone happen to know if there's an easy way to determine inside build.rs if the build was run with cargo deb?

You could run cargo deb with a specific environment variable defined, and check for that variable on the build.rs script, which should inherit the environment from parent processes. You also could use the --cargo-build parameter to point cargo deb to a wrapper script that runs cargo build with such environment variable set.

That being said, the Cargo book explicitly recommends against writing artifacts such as manual pages outside of OUT_DIR in build scripts. And there are good reasons for that recommendation: when publishing to crates.io, package documentation is built in an environment where write access to the filesystem by build scripts is restricted. Build scripts are simply not meant to do this sort of workflow automation, so abusing them in this way can cause problems under environments that (rightly) assume build scripts produce compiler build artifacts and little else.

[julianandrews]

Build scripts are simply not meant to do this sort of workflow automation, so abusing them in this way can cause problems under environments that (rightly) assume build scripts produce compiler build artifacts and little else.

Yeah, you're probably right. In my particular case, where I'd only be doing it on explicit call to cargo deb it wouldn't likely be a problem, but it's still not great to hack something together. I think at this point, I'm going to just leave my project with a manual setup. At this point I haven't worked on the project in a while, and don't foresee needing to do new builds on a regular basis, so a little manual work is probably a better choice than hacking something together.

[kornelski]

The sad part is that cargo-xtask did not define any convention for what should be called at build time, and the way it works made it impossible to discover which tasks are available (since there's one binary and it parses whatever it wants. There's no way to query it programmatically, doesn't even guarantee to support --help). I've raised these concerns specifically with cargo-deb in mind when cargo-xtask was new, and they were dismissed. So cargo-xtask by design is not for cargo-deb.