flatpak-builder

Build a Flatpak and export it to a new repository

$ flatpak-builder [path/to/build_directory] [path/to/manifest]

$ flatpak-builder --repo [repository_name] [path/to/build_directory] [path/to/manifest]

$ flatpak-builder --install [path/to/build_directory] [path/to/manifest]

$ flatpak-builder --gpg-sign [key_id] --repo [repository_name] [path/to/manifest]

$ flatpak-builder --run [path/to/build_directory] [path/to/manifest] [sh]

flatpak-builder [OPTION...] DIRECTORY MANIFEST
flatpak-builder [OPTION...] DIRECTORY --run COMMAND [ARG...]
flatpak-builder --build-shell [OPTION...] DIRECTORY

--repo=PATH
    Specifies the path to the Flatpak repository where the build artifacts will be committed.

--force-clean
    Removes the build directory and associated state before starting the build, ensuring a clean slate.

--disable-cache
    Prevents the use of cached build artifacts, forcing a full rebuild of all modules.

--install
    Installs the built application into the local Flatpak system after a successful build.

--arch=ARCH
    Overrides the architecture detected from the manifest, allowing cross-compilation.

--jobs=NUM
    Sets the number of parallel build jobs (similar to -j in Make), speeding up compilation.

--run COMMAND [ARG...]
    Executes a specified command inside the isolated build environment.

--build-shell
    Opens an interactive shell within the build environment, useful for debugging build issues.

--verbose
    Increases the verbosity of the output, showing more details about the build process.

DIRECTORY
    The path to the build directory where Flatpak-builder will perform its operations and store build artifacts.

MANIFEST
    The path to the Flatpak manifest file (YAML or JSON) that defines the application's build process.

flatpak-builder is the primary command-line tool used to create and manage Flatpak application builds. It reads a manifest file, which defines the application's metadata, sources, build instructions, and dependencies. The tool creates an isolated build environment (using sandboxing) where the application's sources are fetched, compiled, and installed. It supports incremental builds, caching intermediate build artifacts, and creating Flatpak repositories or directly installing the built applications. flatpak-builder is essential for developers packaging their applications for Flatpak and for users who want to build applications from source for Flatpak. It ensures reproducible and consistent builds by controlling the build environment and dependencies.

Building complex applications requires careful crafting of the Flatpak manifest, which can be intricate.
Debugging build failures within the sandboxed environment can be challenging, often requiring the use of --build-shell or --run.
Builds can consume significant disk space due to intermediate artifacts and cached data, especially for large projects.
Network access for fetching sources is typically required during the build process, which might conflict with strict network policies if not explicitly managed.

The typical workflow for building a Flatpak application involves creating a .json or .yaml manifest file first, defining the application's modules, sources, and build commands. Then, flatpak-builder is invoked with the build directory (where build artifacts will be stored) and the path to the manifest file. After a successful build, the application can be installed locally using the --install option or committed to a local Flatpak repository using --repo for distribution.

Flatpak, initially known as xdg-app, was conceived by Lennart Poettering and others as a next-generation application distribution framework for Linux. It was first publicly released in 2016. flatpak-builder has been a core component from its inception, designed to automate and standardize the process of creating Flatpak applications from source code and manifests. It has evolved alongside the Flatpak project, incorporating features like incremental builds, improved manifest parsing, and better integration with modern development workflows to enhance efficiency and reproducibility.

flatpak(1), flatpak-lint(1), flatpak-repo(1)