In this modern age of dockerized apps there are still times when it’s desirable to bundle an app, its dependencies and resources as a self contained installable bundle on Linux.

CMake supports the creation of RPMs and Debian packages through CPack however there’s an alternative bundle-like installer format not supported by CPack called AppImage that’s gaining traction (even though its been around since 2004).

AppImage is to Linux what the .app bundle is to mac. It produces self contained application bundles that on launch self mount, extract their contents into a temp directory and then run allowing you to install your app without polluting the wider system with dependencies.

CPack currently doesn’t support the AppImage format so I thought I’d write up a starter guide for the benefit of others.

Example

There’s a great project called linuxdeploy that supplies utilities to assist in the creation of AppImages.

My app contains a Qt-based GUI so there’s an added complication i.e. bundling the Qt platform libraries and plugins however linuxdeploy provides a plugin to take care of that.

Example (taken from my side project’s build shell script):

# variables pointing at my Qt install location
QTBASE=~/Qt5.10.1/5.10.1/gcc_64
QTDIR=$QTBASE/lib/cmake

# stick qmake and the Qt libs on the appropriate paths so they can be found by the AppImage Qt plugin below
export PATH=$QTBASE/bin:$PATH
export LD_LIBRARY_PATH=$QTBASE/lib

# your cmake project generator invocation and build here
# ...

# once built, rather than invoking cpack lets manually invoke the install target setting the DESTDIR
make install DESTDIR=AppDir

# now fetch the linuxdeploy AppImage utility
wget -cnv https://github.com/linuxdeploy/linuxdeploy/releases/download/continuous/linuxdeploy-x86_64.AppImage

# make it executable
chmod u+x ./linuxdeploy-x86_64.AppImage
    
# fetch the linuxdeploy qt plugin
wget -cnv https://github.com/linuxdeploy/linuxdeploy-plugin-qt/releases/download/continuous/linuxdeploy-plugin-qt-x86_64.AppImage

# make it executable
chmod u+x linuxdeploy-plugin-qt-x86_64.AppImage

# build our app as an AppImage (more on the .desktop file below)
./linuxdeploy-x86_64.AppImage --appdir AppDir --output appimage --plugin qt -d ../fireflyeditor.desktop -i ../fireflyeditor.png

The Desktop Entry file (.desktop)

The generated AppImage is informed by settings contained in a .desktop file. Here’s a minimal self-explanatory example from my project (for more details checkout the AppImage documentation):

[Desktop Entry]
Type=Application
Name=FireflySceneComposer
Comment=A simple scene editor
Exec=fireflyeditor
Icon=fireflyeditor
Categories=Graphics;

Best practices

See here for best practices to follow when building your AppImages.

Troubleshooting

You can easily extract and inspect your AppImage’s contents like so:

./MyApp.AppImage --appimage-extract

Publishing

Once ready you can consider publishing your AppImage to https://appimage.github.io/.