How do I specify troff man page generation & installation using CMake?

Question

I'm trying to switch a Makefile-based build to using CMake. I'm ok with specifying the build of the app itself, but - there's also a man (manual) page, in TROFF format.

• How do I tell CMake to process it into an installable form (e.g. processing if necessary, compression), alongside the building of the executable?
• How do I get CMake to install it to an appropriate location?

Answer 1

If you want to compress something, use the file(ARCHIVE_CREATE ...) command.

To install something that's intended to be a manpage, use the install(FILES ...) command and use CMAKE_INSTALL_MANDIR in the DESTINATION argument.

Answer 2

Elaborating on @starball's answer:

There is currently no "hand-holding" specialty mechanism for handling manual files, so you need to take care of archive compression. No preliminary processing of the TROFF file is necessary.

Suppose your program name is foo and the TROFF file's relative path in the repository is doc/foo.1.

First, increase your CMake version dependency to 3.18, to have access to the file(ARCHIVE_CREATE) command variant.

Now, in your CMakeLists.txt, add the following lines:

include(GNUInstallDirs)
file(ARCHIVE_CREATE OUTPUT foo.1.gz PATHS doc/foo.1 FORMAT raw COMPRESSION GZip)
install(FILES foo.1.gz DESTINATION "${CMAKE_INSTALL_MANDIR}")

(the GNUINstallDirs module is what defines the _MANDIR install path.)