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 [OPTIONS...] DIRECTORY MANIFEST

DIRECTORY
    The directory to use as the build environment. This should be an empty directory.

MANIFEST
    The path to the application manifest file (JSON or YAML).

--arch=ARCH
    The architecture to build for (e.g., x86_64, i386, arm). Defaults to the host architecture.

--repo=REPO
    The path to a local Flatpak repository to export the build to.

--bundle=BUNDLE
    The path to create a Flatpak bundle at.

--force-clean
    Force a clean build by removing the build directory before starting.

--no-cleanup
    Do not clean up the build directory after the build is finished.

--require-version=VERSION
    Require a specific version of Flatpak. Exit if the installed Flatpak is older.

--state-dir=DIRECTORY
    Override the state directory used by flatpak-builder.

--user-only
    Install user-only dependencies. Equivalent to passing --default-branch=app to flatpak install.

--verbose
    Show verbose output.

--ostree-verbose
    Show verbose ostree output.

--disable-updates
    Disable update checking during the build.

--download-only
    Only download the sources, do not build.

--build-only
    Do not download sources, just build.

--finish-args=ARGS
    Extra arguments to pass to flatpak build-finish.

--export-args=ARGS
    Extra arguments to pass to flatpak build-export.

--gpg-sign=KEYID
    GPG key ID to sign the commit with.

--timestamp=TIMESTAMP
    Timestamp to use for the commit (seconds since epoch).

--default-branch=BRANCH
    Override the default branch to use when installing dependencies.

flatpak-builder is a command-line tool used to build Flatpak applications from a declarative manifest file. It takes a manifest file (typically named org.example.YourApp.json or org.example.YourApp.yml) as input, which describes the application, its dependencies, and build instructions. flatpak-builder then executes these instructions in a sandboxed environment to produce a Flatpak bundle or repository.

It handles dependency resolution, build system integration (e.g., Autotools, Meson, CMake), and ensures reproducible builds. The primary goal is to provide a reliable and automated way to create Flatpak packages suitable for distribution. flatpak-builder is widely used by developers to package their applications for various Linux distributions through Flatpak.

The DIRECTORY provided must be an empty directory. flatpak-builder will create files and subdirectories within this directory. If the directory is not empty, the build may fail or produce unexpected results. Also building without internet connection can fail, if dependencies are not available locally.

The manifest file is the core of the flatpak-builder process. It specifies the application ID, runtime, SDK, sources, modules, and other build options. The format is typically JSON or YAML, offering a human-readable way to describe the build process. See the Flatpak documentation for detailed information on the manifest file format.

A Flatpak application is typically built from multiple modules, each representing a component of the application. Each module specifies its sources, build system, and build commands. This modular approach allows for better dependency management and reuse of build configurations.

flatpak-builder automatically resolves and installs dependencies specified in the manifest file. It uses the configured Flatpak remotes to download the necessary runtimes, SDKs, and libraries. It allows you to specify dependencies from the application itself, dependencies from other flatpak packages. This greatly simplifies the process of creating self-contained Flatpak applications.

flatpak-builder was created as part of the Flatpak project to simplify the process of building Flatpak applications. It provides a higher-level abstraction over the lower-level flatpak build command, handling much of the complexity of dependency resolution and build system integration. Over time, it has evolved to support a wider range of build systems, architectures, and build options. Its usage has grown substantially as Flatpak has become a popular way to distribute applications on Linux.

flatpak(1), flatpak-build(1)