Merge topic 'doc-expand-appimage-generator' into release-4.2

b8c9c65682 Help: Correct and expand AppImage CPack generator docs

Acked-by: Kitware Robot <[email protected]>
Merge-request: !11545

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