linuxdeployqt

linuxdeployqt is a Linux deployment tool that takes an application as input and makes it self-contained by copying all required resources (libraries, graphics, plugins, etc.) into a bundle.

Key capabilities:

• Produces an AppDir or an AppImage for distribution.
• Enables cross-distribution packaging.
• Integrates with build systems like CMake, qmake, and make.
• For Qt-based applications, it bundles a minimal subset of Qt required for the application to run.

To ensure maximum compatibility across Linux distributions, follow these guidelines:

1. Target the oldest supported system: Build your application on the oldest still-supported Ubuntu LTS release. Binaries built this way should run on newer systems (Ubuntu and other distributions) but not older ones.
2. Build system restriction: linuxdeployqt is designed to refuse operation on build systems newer than the oldest currently still-supported Ubuntu LTS release to encourage developers to maintain compatibility.
3. Alternative for newer systems: If you must build on a newer system, use go-appimage with appimagetool -s deploy, which bundles all libraries.
4. Wayland: linuxdeployqt does not include workarounds for Wayland. For best results, use X11 instead of Wayland during the build process.

To install linuxdeployqt, download the pre-built AppImage and make it executable:

1. Download linuxdeployqt-x86_64.AppImage from the Releases page.
2. Make the file executable using chmod.

If you intend to use linuxdeployqt to generate AppImages, you must download appimagetool, rename it to appimagetool, and place it in your $PATH (e.g., /usr/local/bin).

sudo wget -c "https://github.com/AppImage/AppImageKit/releases/download/continuous/appimagetool-x86_64.AppImage" -O /usr/local/bin/appimagetool
sudo chmod a+x /usr/local/bin/appimagetool

The linuxdeployqt tool takes an application (binary or desktop file) and makes it self-contained by copying the necessary Qt libraries and plugins into a bundle (AppDir).

By default, it uses the qmake instance found in your $PATH. You can specify a specific qmake using the -qmake option.

Basic Syntax: linuxdeployqt <app-binary|desktop file> [options]

linuxdeployqt requires patchelf to modify the dynamic linker and RPATH of ELF executables. You can install it via your distribution's package manager (e.g., sudo apt install patchelf on Debian/Ubuntu) or build it from source.

wget https://nixos.org/releases/patchelf/patchelf-0.9/patchelf-0.9.tar.bz2
tar xf patchelf-0.9.tar.bz2
( cd patchelf-0.9/ && ./configure  && make && sudo make install )

linuxdeployqt uses the qmake on your $PATH to determine which Qt instance to bundle.

1. Verify current qmake: Run qmake -v to ensure it points to the correct Qt version and path.
2. Adjust PATH: If it is incorrect, update your $PATH to include the correct qmake.
3. Explicitly specify qmake: Use the -qmake flag to point directly to the desired executable.

When using build systems other than qmake, you must use DESTDIR or INSTALL_ROOT to install your application into the AppDir before running linuxdeployqt.

CMake: Use DESTDIR:

cmake . -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=/usr
make -j$(nproc)
make DESTDIR=appdir -j$(nproc) install

Autotools: Use DESTDIR with an absolute path (via readlink -f):

./configure --prefix=/usr
make -j$(nproc)
make install DESTDIR=$(readlink -f appdir)

Meson with Ninja:

meson --prefix /usr build
ninja -C build
DESTDIR=./appdir ninja -C build install

To compile linuxdeployqt from source (e.g., for non-x86_64 platforms like ARM or i686), install the necessary dependencies, clone the repository, and use qmake and make. If you are using a mounted Qt Creator instance, ensure its bin directory is in your PATH.

sudo apt-get -y install git g++ libgl1-mesa-dev
git clone https://github.com/probonopd/linuxdeployqt.git

# Ensure qmake is in your PATH (example for Qt Creator mount)
export PATH=$(readlink -f /tmp/.mount_QtCreator-*-x86_64/*/gcc_64/bin/):$PATH

cd linuxdeployqt
qmake
make

After building from source, you can optionally install linuxdeployqt directly into your Qt installation directory so it is available alongside other Qt tools like qmake.

sudo make install

If you have a custom Qt distribution built with the -qtlibinfix option (e.g., resulting in libraries like libQt5CoreCustom.so), you must pass the same infix to linuxdeployqt so it can correctly detect the libraries.

Example: If your infix is Custom: linuxdeployqt [...] -qtlibinfix "Custom" [...]