FlatImage

What is it?

FlatImage, is a hybrid of Flatpak sandboxing with AppImage portability.

FlatImage use case is twofold:

  • Flatimage is a package format, it includes a piece of software with all its dependencies for it work with across several linux distros (both Musl and GNU). Unlike AppImage, FlatImage runs the application in a container by default, which increases portability and compatibility at the cost of file size.

  • Flatimage is a portable container image that requires no superuser permissions to run.

The diverse GNU/Linux ecosystem includes a vast array of distributions, each with its own advantages and use cases. This can lead to cross-distribution software compatibility challenges. FlatImage addresses these issues by:

  • Utilizing its own root directory, enabling dynamic libraries with hard-coded paths to be packaged alongside the software without binary patching.
  • Running the application in its own gnu (or musl) environment, therefore, not using host libraries that might be outdated/incompatiblesystem with the application.

It simplifies the task of software packaging by enforcing the philosophy that it should be as simple as setting up a container. This is an effort for the end-user to not depend on the application developer to provide the portable binary (or to handle how to package the application, dependencies and create a runner script). It also increases the quality of life of the package developer, simplifying the packaging process of applications.

How to use

Get FlatImage

Download a flatimage package from the releases, your available options are:

  • arch.flatimage
  • alpine.flatimage
  • blueprint.flatimage

arch is a complete GNU archlinux subsystem with the pacman package manager.

alpine is a complete MUSL alpine subsystem with the apk package manager.

blueprint is a flatimage without a system to build a package with only the bare minimum for the application to work, making it lightweight in file size.

Execute The Container

With arch.flatimage as an example, you can enter the container simply by executing the binary file:

$ chmod +x ./arch.flatimage
$ ./arch.flatimage
[flatimage-arch] / →

To exit the container, just press CTRL+D. To download packages please enable the network permission with:

$ ./arch.flatimage fim-perms add network

Go to the fim-perms help page for more details.

How it works

A FlatImage uses a container where it executes its own commands apart from the host system. With that in mind, it is possible to package applications that run in different linux distributions without worrying about missing binaries or libraries.

Motivations

  1. The idea of this application sprung with the challenge to package software and dynamic libraries, such as wine, when there are hard-coded paths. The best solution is invasive https://github.com/AppImage/AppImageKit/wiki/Bundling-Windows-applications , which patches the binaries of wine directly to use a custom path for the 32-bit libraries (an implementation of this concept is available here), not only that, it requires to patch the 32-bit pre-loader ld-linux.so as well, however, sometimes it still fails to execute properly. This is an over exceeding complexity for the end-user, which should package applications with no effort; FlatImage changes the root filesystem the application runs in, to a minimal gnu subsystem, and with that, it solves the previous issues with dynamic libraries no workarounds required. No host libraries are used, which decreases issues of portable applications working on one machine and not in other.

  2. The fragmentation of the linux package management is considerable in modern times, e.g., apt, pip, npm, and more. To mitigate this issue FlatImage can perform the installation through the preferred package manager, and turn the program into an executable file, that can run in any linux distribution. E.g.: The user of FlatImage can create a binary of youtube-dl, from the pip package manager, without having either pip or python installed on the host operating system.

  3. Some applications are offered as pre-compiled compressed tar files (tarballs), which sometimes only work when installed on the root of the operating system. However, doing so could hinder the operating system integrity, to avoid this issue FlatImage can install tarballs into itself and turn them into a portable binary.

Related Projects