FLATPAK-BUILDER(1)

NAME
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

flatpak-builder --show-manifest [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:

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

MANIFEST

The manifest file is a json or yaml 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.

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

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

CACHING

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.

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",
        "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"
                    }
                ]
            }
        ]
    }

SEE ALSO

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