From 669db6df9a5a7510c75e1ea4a4fb1483ae3d60b2 Mon Sep 17 00:00:00 2001 From: Martino Ferrari Date: Wed, 14 Oct 2026 22:28:23 +0200 Subject: [PATCH] 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. --- CMakeLists.txt | 38 ++++++++++++++++++++++++++++++ README.md | 7 +++++- cmake/install_help_user.cmake | 44 +++++++++++++++++++++++++++++++++++ docs/claude/build-and-run.md | 22 ++++++++++++++++++ 4 files changed, 110 insertions(+), 1 deletion(-) create mode 100644 cmake/install_help_user.cmake diff --git a/CMakeLists.txt b/CMakeLists.txt index b9d2d8a..e13e79f 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -89,10 +89,48 @@ file(GLOB UDPSCOPE_HELP_FILES CONFIGURE_DEPENDS # so the set lands at `/share/help/C//`, 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 +# `/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 diff --git a/README.md b/README.md index 4c52a0a..bddd5b5 100644 --- a/README.md +++ b/README.md @@ -2467,7 +2467,12 @@ looks for the document under `$XDG_DATA_HOME/help//org.udpscope.app/` then `$XDG_DATA_DIRS/help//org.udpscope.app/`, so with the set installed the alert names the missing *viewer* (`yelp`), and without it the alert names the identifier, the expected installed path and the install command — `cmake --install build --prefix ~/.local`, which writes -`~/.local/share/help/C/org.udpscope.app/`. A build tree has neither the installed copy nor a +`~/.local/share/help/C/org.udpscope.app/`. Two opt-in targets install the manual *alone*, without a +whole `cmake --install`: `cmake --build build --target install-help-user` writes the same +`$XDG_DATA_HOME` (default `~/.local/share`) copy the alert describes and needs no root, while +`cmake --build build --target install-help` writes to the configured `CMAKE_INSTALL_PREFIX` for a +packager or a system-wide user to wrap in `sudo`; both print where they wrote. A build tree has +neither the installed copy nor a `help:` handler, and **either is enough to make `F1` do nothing**; that is the failure this names. `cmake --build build --target test-help` checks the set the way `test-ui` checks the `.ui` files: `yelp-check`'s offline subcommands (links, media, orphans, ids) and a `yelp-build html` render; diff --git a/cmake/install_help_user.cmake b/cmake/install_help_user.cmake new file mode 100644 index 0000000..722767d --- /dev/null +++ b/cmake/install_help_user.cmake @@ -0,0 +1,44 @@ +# SPDX-License-Identifier: MIT +# +# The `install-help-user` target's body. Copies the Mallard help set into the user's XDG data +# directory -- where `help:` resolves without root -- and prints every path it wrote. +# +# `$XDG_DATA_HOME` is honoured when it is set, and `$HOME/.local/share` is the fallback when it +# is not: that is the XDG Base Directory Specification's own stated default for the variable, and +# it is the default `help_installed_path()` falls back to as well, so the manual lands where the +# application and the desktop viewer look for it. The variable names a *data directory*, not a +# prefix -- its `share/` is not appended -- so the set goes to `/help/C//`. An +# arbitrary `$XDG_DATA_HOME` need not end in `share`, which is exactly why this copies the tree +# rather than deferring to `cmake --install --prefix`, whose datadir is always `/share`. +# +# Like the desktop-entry target, this runs only when it is named: `cmake --build build` never +# touches the user's data directory. +# +# Expects -DHELP_SRC= and -DHELP_NAME= on the command line. + +if(DEFINED ENV{XDG_DATA_HOME} AND NOT "$ENV{XDG_DATA_HOME}" STREQUAL "") + set(data_home "$ENV{XDG_DATA_HOME}") +elseif(DEFINED ENV{HOME} AND NOT "$ENV{HOME}" STREQUAL "") + set(data_home "$ENV{HOME}/.local/share") +else() + message(FATAL_ERROR + "XDG_DATA_HOME and HOME are both unset or empty; cannot determine the user data directory") +endif() + +if(NOT DEFINED HELP_SRC OR NOT DEFINED HELP_NAME) + message(FATAL_ERROR "HELP_SRC and HELP_NAME are both required") +endif() + +set(dest "${data_home}/help/C/${HELP_NAME}") + +# The same filter as the install() rule, so both destinations carry the same tree: the pages and +# the figures, and nothing an editor left behind. +file(COPY "${HELP_SRC}/" DESTINATION "${dest}" + FILES_MATCHING PATTERN "*.page" PATTERN "*.png" PATTERN "*.jpg") + +# Printed because there is no uninstall target: undoing this is these paths. +file(GLOB_RECURSE installed LIST_DIRECTORIES FALSE RELATIVE "${dest}" "${dest}/*") +list(SORT installed) +foreach(path IN LISTS installed) + message(STATUS "wrote ${dest}/${path}") +endforeach() diff --git a/docs/claude/build-and-run.md b/docs/claude/build-and-run.md index a825ae3..5c871c1 100644 --- a/docs/claude/build-and-run.md +++ b/docs/claude/build-and-run.md @@ -74,6 +74,28 @@ GApplication id and the install directory at once. The figures are regenerated b `tools/make-help-shots.sh`, which drives the app headlessly against the mock and draws the annotation boxes with ImageMagick; Mallard is translatable with `itstool`, but only the `C` set is authored. +Because the manual is the only thing udpscope installs, it can be installed *alone* — where `help:` +finds it, and without the `cmake --install` of a whole project — by either of two opt-in targets. +Neither is built by default and `cmake --build build` never touches either: + +```sh +cmake --build build --target install-help-user # /help/C//, no root +cmake --build build --target install-help # /share/help/C// +``` + +`install-help-user` writes to `$XDG_DATA_HOME` when it is set and to `$HOME/.local/share` when it is +not — the XDG Base Directory Specification's own default for the variable, and the fallback +`help_installed_path()` uses — so it needs no root and lands the set exactly +where `F1` and the alert look for it. `install-help` goes through the install machinery into the +configured `CMAKE_INSTALL_PREFIX`, so a packager or a system-wide user points it at `/usr` with +`-DCMAKE_INSTALL_PREFIX` at configure time. Neither target can install system-wide by itself: a build +target has no more privilege than the shell that ran it, so `install-help` writes to the configured +prefix and a system-wide caller wraps it in `sudo`. Both print where they wrote. Both land the same +tree the `install()` rule does — the user-local copy applies that rule's file filter, and the +prefix-wide target *is* that rule, reached through the `Help` component +(`cmake --install --component Help`) — and the ordinary `cmake --install` still installs every +component, so its behaviour is unchanged. + Options: `--server`, `--port`, `--multicast`, `--interface`, `--buffer-mb` (per buffer, default 200), `--max-window`, `--holdoff`, `--recv-buffer`, `--plots` (the row count to *start* with, 1..`RowSet::kMaxRows`; the layout editor owns it afterwards),