Pros and cons of new completion and man page generation mechanism

[wezm]

Just wanted to open a discussion about the new way that completions and man pages are generated, specifically in the context of cross-compiling. Previously when cross-compiling a Linux distribution (Chimera Linux in this case) package for ripgrep it was straightforward to copy the completions and man page as part of the build artefacts. Now the binary needs to be run, which isn't possible to do at build time in a cross-compilation scenario.

A possible workaround since the generated files are not architecture dependent is to build for the host architecture as well as the cross target and use the host build to generate the files. The drawback to this is that it potentially requires building twice. The obvious benefit of the original change is that a dependency on an external tool could be dropped. I'm not sure there is a definite best approach here but figured it was worth raising.

I suppose another workaround could be to extract the files from one of the published tar.gz files, which is what I'm doing now. The ideal scenario would probably be to publish source tarballs with these files pre-generated.

[BurntSushi]

Oh wow, sorry I missed this! This actually came up in another issue filed more recently, but I skipped over this. I responded there with some thoughts. In particular, ripgrep does cross compilation too for its releases, but I can generate man pages via qemu. Is that possible for your use case?

The ideal scenario would probably be to publish source tarballs with these files pre-generated.

Yeah I don't mind doing this, but I think some thought needs to go into what is actually contained in that source tarball. I'd basically like some target or goal for being able to decide what actually goes in the source tarball. It should be able to answer questions like, "Should the source tarball contain the results of running cargo vendor?"

[wezm]

I can generate man pages via qemu. Is that possible for your use case?

It’s possible but not really desirable since it would pull in a pretty significant dependency chain just for some static files. I’m currently just downloading one of the release tarballs in addition to the source tarball to get the man page and completions out of it, which is preferable to using qemu I think.

I think there is a pretty good precedent for what goes in source release tarballs from C projects that have generated files where a make dist or similar target is used to pre-generate things like configure scripts for inclusion in the published artefact. https://www.gnu.org/software/automake/manual/html_node/Preparing-Distributions.html

[wezm]

Another possibility that I've just seen in the wild: publish separate completion and man page tarballs:

E.g. https://github.com/ClementTsang/bottom/releases/tag/0.9.6

[blyxxyz]

This is my fish completion file:

rg --generate=complete-fish | source

I do this so that I don't have to replace it whenever I update ripgrep. It could help with this problem too.

I don't see a way to do that with the man page though.