Provided by: flatpak-builder_0.10.9-1ubuntu1_amd64 bug

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

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.

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.

       --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 or bzr 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. 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 buildng 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.

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

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

       --mirror-screenshots-url=URL
           Mirror any screenshots in the appstream and rewrite the appstream xml as if they were
           on the specified URL. The resulting files will be stored in the "screenshots"
           subdirectory in the app directory and needs to be copied to the specified URL for the
           appdata to work.

       --extra-sources=SOURCE-DIR
           When downloading sources (archives, files, git, bzr), look in this directory for
           pre-existing copies and use them instead of downloading.

       --extra-sources-url=URL
           When downloading sources (archives, files, git, bzr), 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.

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