build: install the manual alone, into the prefix or the user datadir

The manual is the only thing udpscope installs, but the only way to get it
where `help:` resolves was a whole `cmake --install`. Two opt-in targets
now install just the set, each printing where it wrote:

- install-help goes through the install machinery into CMAKE_INSTALL_PREFIX
  (reachable via the new Help component), so a packager or a system-wide
  user points it at /usr and wraps it in sudo;
- install-help-user resolves the user data directory the way the app does
  ($XDG_DATA_HOME, else $HOME/.local/share) and copies there without root.

Neither is built by default and neither changes what `cmake --install`
does; the install() rule keeps its destination.
This commit is contained in:
Martino Ferrari committed 2026-10-14 22:28:23 +02:00
1 parent bb62b8178c
commit 669db6df9a
4 files changed
+110 -1

No files matched your search

+38
View File
@@ -89,10 +89,48 @@ file(GLOB UDPSCOPE_HELP_FILES CONFIGURE_DEPENDS
# so the set lands at `<prefix>/share/help/C/<document>/`, which is exactly where a viewer
# looks. There is no install step for the binary itself (see the desktop-entry target below),
# but the manual is *read from a datadir* by another process, so it has to be installable.
#
# `COMPONENT Help` is what lets the opt-in targets below install *only* the manual: it names this
# rule, and `cmake --install --component Help` runs it and nothing else. The ordinary
# `cmake --install` installs every component, so its behaviour is unchanged -- the component is a
# filter a caller may apply, not a change to the default.
install(DIRECTORY ${UDPSCOPE_HELP_SRC}/
DESTINATION ${CMAKE_INSTALL_DATADIR}/help/C/${UDPSCOPE_HELP_NAME}
COMPONENT Help
FILES_MATCHING PATTERN "*.page" PATTERN "*.png" PATTERN "*.jpg")
# --- installing the manual alone: prefix-wide and user-local, both opt-in -----
# A user who runs the binary out of a build tree wants *just* the manual where `help:` resolves,
# and not the `cmake --install` of a whole project. These two targets are that, one per
# destination; neither is built by default and neither is touched by `cmake --build build`.
#
# `install-help` honours `CMAKE_INSTALL_PREFIX`, so a packager or a system-wide user points it at
# `/usr` with -DCMAKE_INSTALL_PREFIX at configure time. It goes through the install machinery
# (`cmake --install`) rather than a hand-rolled copy, which is what makes DESTDIR and `--prefix`
# behave exactly as they do for the ordinary install. It cannot install system-wide on its own:
# `/usr` is root-owned, so the target writes to the configured prefix and a system-wide caller
# wraps it in `sudo` -- a build target has no more privilege than the shell that runs it.
add_custom_target(install-help
COMMAND ${CMAKE_COMMAND} --install ${CMAKE_BINARY_DIR} --component Help
COMMENT "Installing the manual into ${CMAKE_INSTALL_PREFIX}"
VERBATIM)
# `install-help-user` is the no-root case the launch-failure alert names. It resolves the user
# data directory the way `help_installed_path()` does -- `$XDG_DATA_HOME` when it is set,
# `$HOME/.local/share` otherwise, the XDG Base Directory Specification's own default -- and copies
# the set there. The copy is done by a script rather than by `cmake --install --prefix` because
# the destination is the *data directory*, not a prefix: `cmake --install`'s datadir is always
# `<prefix>/share`, so an arbitrary `$XDG_DATA_HOME` cannot be expressed as a prefix. The script
# prints every path it wrote; the copy uses the install rule's file filter, so both destinations
# carry the same tree.
add_custom_target(install-help-user
COMMAND ${CMAKE_COMMAND}
-DHELP_SRC=${UDPSCOPE_HELP_SRC}
-DHELP_NAME=${UDPSCOPE_HELP_NAME}
-P ${CMAKE_CURRENT_SOURCE_DIR}/cmake/install_help_user.cmake
COMMENT "Installing the manual into the user's XDG data directory"
VERBATIM)
# --- UI files: GtkBuilder XML in a GResource ----------------------------------
# The third bundle, for the same reason as the other two: `.ui` files are data, so they are compiled
# in rather than looked for at runtime -- and `preprocess="xml-stripblanks"` makes a malformed one a