Help/cpack_gen/appimage.rst

CPack AppImage generator
------------------------

.. versionadded:: 4.2

CPack `AppImage`_ generator allows to bundle an application into
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 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.

.. 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()
  ]])

For Qt based projects it's 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.

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, might be located in the build dir,
  full path or reachable in ``PATH``.

  :Default: ``appimagetool`` :variable:`CPACK_PACKAGE_FILE_NAME`

.. variable:: CPACK_APPIMAGE_PATCHELF_EXECUTABLE

  Name of the ``patchelf`` executable, might be located in the build dir,
  full path or reachable in ``PATH``.

  :Default: ``patchelf`` :variable:`CPACK_APPIMAGE_PATCHELF_EXECUTABLE`

.. variable:: CPACK_APPIMAGE_DESKTOP_FILE

  Name of freedesktop.org desktop file installed.

  :Mandatory: Yes
  :Default: :variable:`CPACK_APPIMAGE_DESKTOP_FILE`

.. variable:: CPACK_APPIMAGE_UPDATE_INFORMATION

  Embed update information STRING; if zsyncmake is installed,
  generate zsync file.

  :Default: :variable:`CPACK_APPIMAGE_UPDATE_INFORMATION`

.. variable:: CPACK_APPIMAGE_GUESS_UPDATE_INFORMATION

  Guess update information based on GitHub or GitLab environment variables.

  :Default: :variable:`CPACK_APPIMAGE_GUESS_UPDATE_INFORMATION`

.. variable:: CPACK_APPIMAGE_COMPRESSOR

  Squashfs compression.

  :Default: :variable:`CPACK_APPIMAGE_COMPRESSOR`

.. variable:: CPACK_APPIMAGE_MKSQUASHFS_OPTIONS

  Arguments to pass through to mksquashfs.

  :Default: :variable:`CPACK_APPIMAGE_MKSQUASHFS_OPTIONS`

.. variable:: CPACK_APPIMAGE_NO_APPSTREAM

  Do not check AppStream metadata.

  :Default: :variable:`CPACK_APPIMAGE_NO_APPSTREAM`

.. variable:: CPACK_APPIMAGE_EXCLUDE_FILE

  Uses given file as exclude file for mksquashfs,
  in addition to .appimageignore.

  :Default: :variable:`CPACK_APPIMAGE_EXCLUDE_FILE`

.. variable:: CPACK_APPIMAGE_RUNTIME_FILE

  Runtime file to use, if not set a bash script will be generated.

  :Default: :variable:`CPACK_APPIMAGE_RUNTIME_FILE`

.. variable:: CPACK_APPIMAGE_SIGN

  Sign with gpg[2].

  :Default: :variable:`CPACK_APPIMAGE_SIGN`

.. variable:: CPACK_APPIMAGE_SIGN_KEY

  Key ID to use for gpg[2] signatures.

  :Default: :variable:`CPACK_APPIMAGE_SIGN_KEY`