flatpak-builder man page

flatpak-builder — Help build application dependencies

Synopsis

flatpak-builder [OPTION...] DIRECTORY Manifest

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

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

Description

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:

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.

Manifest

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

Options

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.

--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 or bzr repositories from the remote repository.

--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. The command to run must be the last argument passed to flatpak-builder, after the directory and the manifest.

--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 buildng the module. This is useful to debug a module.

--show-deps

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

--download-only

Exit successfully after downloading the required 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.

--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.

--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").

--ccache

Enable use of ccache in the build (needs ccache in the sdk)

--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

When build is done, run export the result to this repository.

-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.

--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.

--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.

--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.

Caching

flatpak-builder caches sources and partial build results in 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 contents of the .flatpak-builder directory. This will force a full build the next time you build.

Examples

$ 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",
    "clean": [ "/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": "git://git.gnome.org/babl"
                }
            ]
        },
        {
            "name": "testapp",
            "sources": [
                {
                    "type": "bzr",
                    "url": "lp:testapp"
                }
            ]
        }
    ]
}

See Also

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

Referenced By

flatpak-manifest(5).

flatpak builder