From b8c9c656820af0953aaf3aa5276f3111d5b3ca8f Mon Sep 17 00:00:00 2001 From: Craig Scott Date: Sun, 21 Dec 2025 20:40:58 +1100 Subject: Help: Correct and expand AppImage CPack generator docs The help text for most variables were just copy-and-pasted from the minimal output from running `appimagetool --help`. That text lacked considerable important detail. The default values for most of the variables were also specified incorrectly. They listed themselves as the default, which is wrong. In most cases, the variables are unset by default. For those that actually have fallback values, update them to specify that. The CPACK_APPIMAGE_DESKTOP_FILE variable is not mandatory. The code does provide fallback behavior when it isn't set. What is mandatory though is that there is a .desktop file, either specified explicitly, or found within the installed files. There is also a close relationship with CPACK_PACKAGE_ICON that deserves explicitly drawing attention to. --- Help/cpack_gen/appimage.rst | 104 ++++++++++++++++++++++++++------------------ 1 file changed, 61 insertions(+), 43 deletions(-) diff --git a/Help/cpack_gen/appimage.rst b/Help/cpack_gen/appimage.rst index 0ed776e..03d02b8 100644 --- a/Help/cpack_gen/appimage.rst +++ b/Help/cpack_gen/appimage.rst @@ -3,23 +3,22 @@ CPack AppImage Generator .. versionadded:: 4.2 -CPack `AppImage`_ generator allows to bundle an application into -AppImage format. It uses ``appimagetool`` to pack the application, +The CPack `AppImage`_ generator enables bundling an application into the +AppImage format. It uses ``appimagetool`` to pack the application and ``patchelf`` to set the application ``RPATH`` to a relative path based on where the AppImage will be mounted. .. _`AppImage`: https://appimage.org -The ``appimagetool`` does not scan for libraries dependencies it only -packs the installed content and check if the provided ``.desktop`` file -was properly created. For best compatibility it's recommended to choose -some old LTS distro and built it there, as well as including most -dependencies on the generated file. +The ``appimagetool`` does not scan for libraries dependencies. It only +packs the installed content and checks if the provided ``.desktop`` file +was properly created. For best compatibility, it's recommended to build on +an old LTS distribution and to include any dependencies in the generated file. -The snipped below can be added to your ``CMakeLists.txt`` file -replacing ``my_application_target`` with your application target, -it will do a best effort to scan and copy the libraries your -application links to and copy to install location. +The snippet below can be added to your ``CMakeLists.txt`` file. +Replace ``my_application_target`` with your application target. +The example will do a best effort to identify the libraries your +application links to and copy them to the install location. .. code-block:: cmake @@ -41,10 +40,10 @@ application links to and copy to install location. endforeach() ]]) -For Qt based projects it's recommended to call +For Qt-based projects, it is recommended to call ``qt_generate_deploy_app_script()`` or ``qt_generate_deploy_qml_app_script()`` -and install the files generated by the script, this will install -Qt module's plugins. +and install the files generated by the script. This will install the +Qt plugins. You must also set :variable:`CPACK_PACKAGE_ICON` with the same value listed in the Desktop file. @@ -54,77 +53,96 @@ Variables Specific to CPack AppImage Generator .. variable:: CPACK_APPIMAGE_TOOL_EXECUTABLE - Name of the ``appimagetool`` executable, might be located in the build dir, - full path or reachable in ``PATH``. + Name of the ``appimagetool`` executable. If not given as an absolute path, + logic based on :command:`find_program` will be used internally with this + value to find the executable. - :Default: ``appimagetool`` :variable:`CPACK_PACKAGE_FILE_NAME` + :Default: ``appimagetool`` .. variable:: CPACK_APPIMAGE_PATCHELF_EXECUTABLE - Name of the ``patchelf`` executable, might be located in the build dir, - full path or reachable in ``PATH``. + Name of the ``patchelf`` executable. If not given as an absolute path, + logic based on :command:`find_program` will be used internally with this + value to find the executable. - :Default: ``patchelf`` :variable:`CPACK_APPIMAGE_PATCHELF_EXECUTABLE` + :Default: ``patchelf`` .. variable:: CPACK_APPIMAGE_DESKTOP_FILE - Name of freedesktop.org desktop file installed. + Name of the freedesktop.org desktop file to be installed. If not specified, + the first ``.desktop`` file found in the list of files to be installed will + be used. There must be a valid ``.desktop`` file for the package, and it + must include an ``Icon`` entry that matches :variable:`CPACK_PACKAGE_ICON` + without the file extension. The actual installed location of the icon + should follow the freedesktop.org specification. - :Mandatory: Yes - :Default: :variable:`CPACK_APPIMAGE_DESKTOP_FILE` + :Default: Unset .. variable:: CPACK_APPIMAGE_UPDATE_INFORMATION - Embed update information STRING; if zsyncmake is installed, - generate zsync file. + Embed the value of this variable as the update information. See the + ``appimagetool`` source code for the supported values and formats of the + ``--updateinformation`` option. It is highly recommended to have + the ``zsyncmake`` tool installed if using ``zsync`` update information. - :Default: :variable:`CPACK_APPIMAGE_UPDATE_INFORMATION` + :Default: Unset .. variable:: CPACK_APPIMAGE_GUESS_UPDATE_INFORMATION - Guess update information based on GitHub or GitLab environment variables. + When this variable is true, add the ``--guess`` option to the + ``appimagetool`` invocation. This directs the tool to try to guess + appropriate update information based on GitHub or GitLab environment + variables. - :Default: :variable:`CPACK_APPIMAGE_GUESS_UPDATE_INFORMATION` + :Default: Unset .. variable:: CPACK_APPIMAGE_COMPRESSOR - Squashfs compression. + Override the ``appimagetool``'s default type of squashfs compression (zstd). + This corresponds to the ``appimagetool --comp`` option. - :Default: :variable:`CPACK_APPIMAGE_COMPRESSOR` + :Default: Unset .. variable:: CPACK_APPIMAGE_MKSQUASHFS_OPTIONS - Arguments to pass through to mksquashfs. + List of arguments to pass through to ``mksquashfs``. Each of these will be + preceded by ``--mksquashfs-opt`` on the ``appimagetool`` command line. - :Default: :variable:`CPACK_APPIMAGE_MKSQUASHFS_OPTIONS` + :Default: Unset .. variable:: CPACK_APPIMAGE_NO_APPSTREAM - Do not check AppStream metadata. + If set to true, do not check AppStream metadata. This passes the + ``--no-appstream`` option to ``appimagetool``. - :Default: :variable:`CPACK_APPIMAGE_NO_APPSTREAM` + :Default: Unset .. variable:: CPACK_APPIMAGE_EXCLUDE_FILE - Uses given file as exclude file for mksquashfs, - in addition to .appimageignore. + Use the specified file as an exclude file for ``mksquashfs``, + in addition to ``.appimageignore``. This uses the ``--exclude-file`` + option to ``appimagetool``. - :Default: :variable:`CPACK_APPIMAGE_EXCLUDE_FILE` + :Default: Unset .. variable:: CPACK_APPIMAGE_RUNTIME_FILE - Runtime file to use, if not set a bash script will be generated. + Specify a runtime file to use instead of letting the ``appimagetool`` + download a runtime to embed in the generated AppImage. - :Default: :variable:`CPACK_APPIMAGE_RUNTIME_FILE` + :Default: Unset .. variable:: CPACK_APPIMAGE_SIGN - Sign with gpg[2]. + When set to true, sign the generated AppImage with gpg[2]. + :variable:`CPACK_APPIMAGE_SIGN_KEY` should also be specified if using this + option. - :Default: :variable:`CPACK_APPIMAGE_SIGN` + :Default: Unset .. variable:: CPACK_APPIMAGE_SIGN_KEY - Key ID to use for gpg[2] signatures. + Key ID to use for gpg[2] signatures when signing is enabled with + :variable:`CPACK_APPIMAGE_SIGN`. - :Default: :variable:`CPACK_APPIMAGE_SIGN_KEY` + :Default: Unset -- cgit v0.12