flatpak-builder - Man Page

• Build a Flatpak and export it to a new repository: flatpak-builder path/to/build_directory path/to/manifest
• Build a Flatpak and export it to the specified repository: flatpak-builder --repo repository_name path/to/build_directory path/to/manifest
• Build a Flatpak and install it locally: flatpak-builder --install path/to/build_directory path/to/manifest
• Build and sign a Flatpak and export it to the specified repository: flatpak-builder --gpg-sign key_id --repo repository_name path/to/manifest
• Run a shell inside of an application sandbox without installing it: flatpak-builder --run path/to/build_directory path/to/manifest sh

tldr.sh

flatpak-builder [OPTION...] DIRECTORY Manifest

flatpak-builder --run [OPTION...] DIRECTORY Manifest COMMAND

flatpak-builder --show-deps [OPTION...] Manifest

flatpak-builder --show-manifest [OPTION...] Manifest

flatpak-builder is a wrapper around the flatpak build command that automates the building of applications and their dependencies​. It is one option you can use to build applications​.

The goal of flatpak-builder is to push as much knowledge about how to build modules to the individual upstream projects​. It does this by assuming that the modules adhere to the Build API specified at https://github​.com/cgwalters/build-api​. This essentially means that it follows the ​./configure && make && make install scheme with an optional autogen script​. If the upstream does not adhere to the API you can make it do so by adding patches and extra files​.

An invocation of flatpak-builder proceeds in these stages, each being specified in detail in json format in Manifest:

• Download all sources
• Initialize the application directory with flatpak build-init
• Build and install each module with flatpak build
• Clean up the final build tree by removing unwanted files and e​.g​. stripping binaries
• Finish the application directory with flatpak build-finish

After this you will end up with a build of the application in DIRECTORY, which you can export to a repository with the flatpak build-export command​. If you use the --repo option, flatpak-builder will do the export for you at the end of the build process​. When flatpak-builder does the export, it also stores the manifest that was used for the build in /app/manifest​.json​. The manifest is 'resolved', i​.e​. git branch names are replaced by the actual commit IDs that were used in the build​.

At each of the above steps flatpak caches the result, and if you build the same file again, it will start at the first step where something changes​. For instance the first version controlled source that had new commits added, or the first module where some changes to the Manifest file caused the build environment to change​. This makes flatpak-builder very efficient for incremental builds​.

When building a flatpak to be published to the internet, --collection-id=COLLECTION-ID should be specified as a globally unique reverse DNS value to identify the collection of flatpaks this will be added to​. Setting a globally unique collection ID allows the apps in the repository to be shared over peer to peer systems without needing further configuration​.

The manifest file is a json or yaml file whose format is described in detail in its own manual page​.

The following options are understood:

-h,  --help

Show help options and exit​.

-v,  --verbose

Print debug information during command processing​.

--version

Print version information and exit​.

--arch=ARCH

Specify the machine architecture to build for​. If no architecture is specified, the host architecture will be automatically detected​. Only host compatible architectures can be specified​.

--default-branch=BRANCH

Set the default branch to BRANCH​. This is used if the manifest does not specify a branch​. The default is master​.

--disable-cache

Don't look at the existing cache for a previous build, instead always rebuild modules​.

--disable-rofiles-fuse

Disable the use of rofiles-fuse to optimize the cache use via hardlink checkouts​.

--disable-download

Don't download any sources​. This only works if some version of all sources are downloaded already​. This is useful if you want to guarantee that no network i/o is done​. However, the build will fail if some source is not locally available​.

--disable-updates

Download missing sources, but don't update local mirrors of version control repos​. This is useful to rebuild things but without updating git, bzr or svn repositories from the remote repository​.

--disable-tests

Don't run any of the tests​.

--run

Run a command in a sandbox based on the build dir​. This starts flatpak build, with some extra arguments to give the same environment as the build, and the same permissions the final app will have (except filesystem permissions)​. The command to run must be the last argument passed to flatpak-builder, after the directory and the manifest​.

Only the --arch=ARCH, --ccache, --verbose and --state-dirPATH (since 1​.4​.8) options can be combined with this option​.

--build-shell=MODULENAME

Extract and prepare the sources for the named module, and then start a shell in a sandbox identical to the one flatpak-builder would use for building the module​. This is useful to debug a module​.

--show-deps

List all the (local) files that the manifest depends on​.

Only the --verbose option can be combined with this option​.

--show-manifest

Loads the manifest, including any included files and prints it in a canonical json format​. This is useful for tools that want to handle manifest files to avoid having to support both yaml and json, as well as some non-standard json handling that is supported (for example comments and multiline strings)​.

Only the --verbose option can be combined with this option​.

--download-only

Exit successfully after downloading the required sources​.

--bundle-sources

Create an additional runtime with the source code for this module​. It will be named app-id​.Sources, for example org​.gnome​.Maps​.Sources​.

--build-only

Don't do the cleanup and finish stages, which is useful if you want to build more things into the app​.

--finish-only

Only do the cleanup, finish and export stages, picking up where a --build-only command left off​.

--export-only

Only do the export stages, picking up the build result from a previous build​. This can be used to split the build and export/signature into two calls by leaving out --repo in the first call​.

--require-changes

Do nothing, leaving a non-existent DIRECTORY if nothing changes since last cached build​. If this is not specified, the latest version from the cache will be put into DIRECTORY​.

--state-dir=PATH

Use this directory for storing state (downloads, build dirs, build cache, etc) rather than ​.flatpak-builder​. This can be an absolute or relative path, but must be on the same filesystem as the specified target DIRECTORY​.

--keep-build-dirs

Don't remove the sources and build after having built and installed each module​. This also creates a symlink to the build directory with a stable name ("build-modulename")​.

--delete-build-dirs

Always remove the sources and build after having built each module, even if the build failed​. The default is to keep failed build directories but remove successful ones​. This is useful in e​.g​. automatic build systems​.

--ccache

Enable use of ccache in the build (needs ccache in the sdk)​. The default ccache folder can be overridden by setting the environment variable CCACHE_DIR​.

--stop-at=MODULENAME

Stop at the specified module, ignoring it and all the following ones in both the "download" and "build" phases​. This is useful for debugging and development​. For instance, you can build all the dependencies, but stop at the main application so that you can then do a build from a pre-existing checkout​. Implies --build-only​.

--repo=DIR

After the build finishes, run flatpak build-export to export the result to the repository DIR​. If DIR exists, it must be an OSTree repository; otherwise a new one will be created​.

-s, --subject=SUBJECT

One line subject for the commit message​. Used when exporting the build results​.

-b, --body=BODY

Full description for the commit message​. Used when exporting the build results​.

--collection-id=COLLECTION-ID

Set as the collection ID of the repository​. Setting a globally unique collection ID allows the apps in the repository to be shared over peer to peer systems without needing further configuration​. If building in an existing repository, the collection ID must match the existing configured collection ID for that repository​.

--token-type=VAL

Set type of token needed to install this commit​. Setting this to a value greater than 0 implies that authentication will be needed to install the flatpak​. A token-type property set in the manifest takes precedence over this option​. Used when exporting the build results​.

--gpg-sign=KEYID

Sign the commit with this GPG key​. Used when exporting the build results​. This option can be used multiple times​.

--gpg-homedir=PATH

GPG Homedir to use when looking for keyrings​. Used when exporting the build results​.

--jobs=JOBS

Limit the number of parallel jobs during the build​. The default is the number of CPUs on the machine​.

--force-clean

Erase the previous contents of DIRECTORY if it is not empty​. Since 1​.4​.6, deletion will be refused if DIRECTORY is the current working directory, the state directory, or any of their parent directories​.

--sandbox

Disable the possibility to specify build-args that are passed to flatpak build​. This means the build process can't break out of its sandbox, and is useful when building less trusted software​.

--allow-missing-runtimes

Do not immediately fail if the sdk or platform runtimes are not installed on this system​. Attempting to build any manifest modules will still fail if the sdk is missing, but may be useful for apps that install files without a sandbox build​.

--rebuild-on-sdk-change

Record the exact version of the sdk in the cache, and rebuild everything if it changes​. This is useful if you're building against an API-unstable runtime, like a nightly build​.

--skip-if-unchanged

If the json is unchanged since the last build of this filename, then do nothing, and return exit code 42​.

--mirror-screenshots-url=URL

Mirror any media in the appstream and rewrite the media URLs in the appstream xml to the specified URL​. The resulting files will be stored in the "screenshots" subdirectory in the app directory for versions earlier than 1​.3​.4 and "files/share/app-info/media" subdirectory for newer versions​. Since version 1​.4​.5 this will also create a screenshot ref in the exported OSTree repo for each architecture containing the mirrored media​.

--extra-sources=SOURCE-DIR

When downloading sources (archives, files, git, bzr, svn), look in this directory for pre-existing copies and use them instead of downloading​. The directory must match the state directory structure:

• Files and archives must be inside the folder: downloads/<sha256>/
• Sources of type git, bzr and svn must be inside the folder: <type>/<converted-uri>/

The converted-uri is constructed from path or url (in case of git) and from url (in case of bzr and svn)​. :// is converted to a single underscore and every other / is replaced by an underscore​. For example, https://github​.com/user/repo​.git becomes https_github​.com_user_repo​.git​. In case of svn sources if revision is present, the folder name is svn/<converted-uri>__r<revision>/​. In case of git sources, it needs to be a mirrored clone​.

--extra-sources-url=URL

When downloading sources (archives, files, git, bzr, svn), look at this url for mirrored downloads before downloading from the original url​.

--from-git=GIT

Look for the manifest in the given git repository​. If this option is given, Manifest is interpreted as a relative path inside the repository​.

--from-git-branch=BRANCH

The branch to use with --from-git​.

--no-shallow-clone

Don't use shallow clones when mirroring git repos​.

--override-source-date-epoch

Set this timestamp as SOURCE_DATE_EPOCH to perform the build, instead of the last modification time of the manifest​. This is available since 1​.3​.1​.

--compose-url-policy=POLICY

Set the AppStream compose URL policy​. Accepted values are partial and full​. full requires AppStream version >= 0​.16​.3​. Defaults to partial if unspecified​. This policy only takes effect when used in conjunction with --mirror-screenshots-url=URL; otherwise the Appstream catalogue will preserve the source media URLs​.

--compose-image-format=FORMAT

Set the AppStream compose image format used for generated icons and screenshots​. Accepted values are png and jxl​. jxl requires AppStream version >= 1​.2​.0​. Defaults to png if unspecified​.

--add-tag=TAG

Add this tag to the tags list of the manifest before building​.

--remove-tag=TAG

Remove this tag to the tags list of the manifest before building​. The remove happen before processing the --add-tag option, so if both are specified, then --app-tag wins​.

--install-deps-from=REMOTE

Install/update build required dependencies from the specified remote​.

--install-deps-only

Stop after downloading dependencies​.

--install

When the build is finished, install the result locally​.

--user

Install the dependencies in a per-user installation​.

--system

Install the dependencies in the default system-wide installation​.

--installation=NAME

Install the dependencies in a system-wide installation specified by NAME among those defined in /etc/flatpak/installations​.d/​. Using --installation=default is equivalent to using --system​.

flatpak-builder caches sources and partial build results in the state directory (defaulting to the ​.flatpak-builder subdirectory of the current directory)​. If you use --keep-build-dirs, build directories for each module are also stored here​.

It is safe to remove the state directory​. This will force a full build the next time you build​.

$ flatpak-builder my-app-dir manifest​.json

Example manifest file:

{
    "id": "org​.test​.TestApp",
    "runtime": "org​.freedesktop​.Platform",
    "runtime-version": "1​.2",
    "sdk": "org​.freedesktop​.Sdk",
    "command": "test",
    "cleanup": [ "/include", "*​.la" ],
    "build-options" : {
        "cflags": "-O2 -g",
        "cxxflags": "-O2 -g",
        "env": {
            "V": "1"
        },
        "arch": {
            "x86_64": {
                "cflags": "-O3 -g",
            }
        }
    },
    "modules": [
        {
            "name": "pygobject",
            "config-opts": [ "--disable-introspection" ],
            "sources": [
                {
                    "type": "archive",
                    "url": "http://ftp​.gnome​.org/pub/GNOME/sources/pygobject/2​.28/pygobject-2​.28​.6​.tar​.xz",
                    "sha256": "fb8a1d4f665130a125011659bd347c7339c944232163dbb9a34fd0686577adb8"
                },
                {
                    "type": "patch",
                    "path": "required-pygobject-fix​.patch"
                },
                {
                    "type": "file",
                    "path": "pygobject-extra-file",
                    "dest-filename": "extra-file"
                }
            ]
        },
        {
            "name": "babl",
            "build-options" : { "cxxflags": "-O2 -g -std=c++11" },
            "cleanup": [ "/bin" ],
            "sources": [
                {
                    "type": "git",
                    "url": "https://gitlab​.gnome​.org/GNOME/babl​.git"
                }
            ]
        },
        {
            "name": "testapp",
            "sources": [
                {
                    "type": "bzr",
                    "url": "lp:testapp"
                }
            ]
        }
    ]
}

flatpak(1), flatpak-manifest(5), flatpak-build-init(1), flatpak-build(1), flatpak-build-finish(1), flatpak-build-export(1)