Help/cpack_gen/appimage.rst

CPack AppImage Generator
------------------------

.. versionadded:: 4.2

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 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 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

  install(CODE [[
      file(GET_RUNTIME_DEPENDENCIES
          EXECUTABLES $<TARGET_FILE:my_application_target>
          RESOLVED_DEPENDENCIES_VAR resolved_deps
      )

      foreach(dep ${resolved_deps})
          # copy the symlink
          file(COPY ${dep} DESTINATION ${CMAKE_INSTALL_PREFIX}/lib)

          # Resolve the real path of the dependency (follows symlinks)
          file(REAL_PATH ${dep} resolved_dep_path)

          # Copy the resolved file to the destination
          file(COPY ${resolved_dep_path} DESTINATION ${CMAKE_INSTALL_PREFIX}/lib)
      endforeach()
  ]])

The CPack AppImage generator will generate a default `AppRun`_ based on the
provided ``.desktop`` entry.  Alternatively, if a custom ``AppRun`` is
installed, e.g., via the :command:`install` command, it will be used instead
of the generated one.

.. _`AppRun`: https://docs.appimage.org/introduction/software-overview.html#apprun

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 the
Qt plugins.

You must also set :variable:`CPACK_PACKAGE_ICON` with the same value
listed in the Desktop file.

Variables Specific to CPack AppImage Generator
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. variable:: CPACK_APPIMAGE_TOOL_EXECUTABLE

  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_APPIMAGE_PATCHELF_EXECUTABLE

  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_DESKTOP_FILE

  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.

  :Default: Unset

.. variable:: CPACK_APPIMAGE_UPDATE_INFORMATION

  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: Unset

.. variable:: CPACK_APPIMAGE_GUESS_UPDATE_INFORMATION

  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: Unset

.. variable:: CPACK_APPIMAGE_COMPRESSOR

  Override the ``appimagetool``'s default type of squashfs compression (zstd).
  This corresponds to the ``appimagetool --comp`` option.

  :Default: Unset

.. variable:: CPACK_APPIMAGE_MKSQUASHFS_OPTIONS

  List of arguments to pass through to ``mksquashfs``.  Each of these will be
  preceded by ``--mksquashfs-opt`` on the ``appimagetool`` command line.

  :Default: Unset

.. variable:: CPACK_APPIMAGE_NO_APPSTREAM

  If set to true, do not check AppStream metadata.  This passes the
  ``--no-appstream`` option to ``appimagetool``.

  :Default: Unset

.. variable:: CPACK_APPIMAGE_EXCLUDE_FILE

  Use the specified file as an exclude file for ``mksquashfs``,
  in addition to ``.appimageignore``.  This uses the ``--exclude-file``
  option to ``appimagetool``.

  :Default: Unset

.. variable:: CPACK_APPIMAGE_RUNTIME_FILE

  Specify a runtime file to use instead of letting the ``appimagetool``
  download a runtime to embed in the generated AppImage.

  :Default: Unset

.. variable:: CPACK_APPIMAGE_SIGN

  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: Unset

.. variable:: CPACK_APPIMAGE_SIGN_KEY

  Key ID to use for gpg[2] signatures when signing is enabled with
  :variable:`CPACK_APPIMAGE_SIGN`.

  :Default: Unset