website/content/blog/appimage.md

title	date	draft	tags
Deploying Binaries to other Linux Distros using Appimage	2020-10-19T21:53:52-04:00	false	Packaging Linux

One way to distribute to different Linux distributions is to compile the source under each of them and distribute it separately. This can be a pain to manage if you target multiple distributions and multiple versions of those distributions. Instead, let's take a look at AppImage. This allows us to package up our binaries and shared libraries under one file which we can distribute.

Source: https://docs.appimage.org/reference/architecture.html

It works by packaging up the application in a SquashFS which is then mounted during runtime using FUSE. The project recommends that the AppImage is packaged on an older system, like an Ubuntu LTS or CentOS. Newer systems are often backwards compatible but not the other way around. Let's get started!

Setting up the AppImage

Let's create an AppImage based on the application Gqrx. The following structure will be common for all binary distribution packages:

gqrx.AppDir/
  AppRun
  icon.png
  gqrx.desktop
  usr/
    bin/
      gqrx
    etc/
      # Config files
    lib/
      # Shared libraries

The AppRun executable comes from the AppImage Releases Page. While you're there, you should also download appimagetool as we'll be using that soon.

The .desktop file needs to be a valid Linux Desktop Icon. Some things to take note about the desktop file:

• The icon is assumed to be a .png
• The executable is assumed to be located in /usr/bin/
• Make sure to define the Categories field, the appimagetool complained when I didn't.

Here is an example desktop file.

[Desktop Entry]
Type=Application
Name=Gqrx
Icon=icon
Exec=gqrx
Categories=Development;

Copy over gqrx executable over to the AppDir:

export gqrx_loc=$(which gqrx)
cp $gqrx_loc gqrx.AppDir/usr/bin/

Finding Needed Shared Libraries

This part is the most time consuming of this whole process. Most of the shared libraries that the application depends on needs to be added to the usr/lib folder. Except for the lowest level libraries.

Let's first take a look at all the libraries we need:

export all_libraries=$(ldd $gqrx_loc | awk '{ print $1 }')
echo $all_libraries

Then let's grab the excludelist from AppImage:

wget https://raw.githubusercontent.com/AppImage/pkg2appimage/master/excludelist

Now let's filter our library output to take away the lowest level libraries:

export filtered_libraries=$(echo $all_libraries | grep -vwf excludelist)
echo $filtered_libraries

If this filter doesn't work, then you might need to make sure each library is listed on its own line.

Finally, let's save the locations of these libraries to library_locations.txt

ldd $gqrx_loc | grep $filtered_libraries | awk '{ print $3 }' > library_locations.txt
cat library_locations.txt

Copy over all the libraries

xargs -a library_locations.txt -L 1 -I @ cp @ gqrx.AppDir/usr/lib/

If there are any libraries that you need get dynamically injected during runtime, you will have to copy those over as well.

For those using Qt plugins, those live within the /usr/bin directory. For example libqxcb.so lives in /usr/bin/platforms/libqxcb.so.

Creating the AppImage

Finally we can use the appimagetool command to create the AppImage:

./appimagetool-x86_64.AppImage gqrx.AppDir/

Which will generate a gqrx-appimage-x86_64.AppImage file.

Now for the moment of true, copy that file over to another Linux distribution and see if it executes appropriately. If it complains about shared libraries missing, then you should go back to the previous system and add that library in.

If it complains about Illegal instructions, then there is probably either a low level library that needs to be removed, or the CPU instruction set between the two computers differ.