"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">

<refentry id="flatpak-builder">

    <refentryinfo>

        <title>flatpak builder</title>

        <productname>flatpak</productname>

        <authorgroup>

            <author>

                <contrib>Developer</contrib>

                <firstname>Alexander</firstname>

                <surname>Larsson</surname>

                <email>alexl@redhat.com</email>

            </author>

        </authorgroup>

    </refentryinfo>

    <refmeta>

        <refentrytitle>flatpak-builder</refentrytitle>

        <manvolnum>1</manvolnum>

    </refmeta>

    <refnamediv>

        <refname>flatpak-builder</refname>

        <refpurpose>Help build application dependencies</refpurpose>

    </refnamediv>

    <refsynopsisdiv>

            <cmdsynopsis>

                <command>flatpak-builder</command>

                <arg choice="opt" rep="repeat">OPTION</arg>

                <arg choice="plain">DIRECTORY</arg>

                <arg choice="plain">MANIFEST</arg>

            </cmdsynopsis>

            <cmdsynopsis>

                <command>flatpak-builder</command>

                <arg choice="plain">--run</arg>

                <arg choice="opt" rep="repeat">OPTION</arg>

                <arg choice="plain">DIRECTORY</arg>

                <arg choice="plain">MANIFEST</arg>

                <arg choice="plain">COMMAND</arg>

            </cmdsynopsis>

            <cmdsynopsis>

                <command>flatpak-builder</command>

                <arg choice="plain">--show-deps</arg>

                <arg choice="opt" rep="repeat">OPTION</arg>

                <arg choice="plain">MANIFEST</arg>

            </cmdsynopsis>

            <cmdsynopsis>

                <command>flatpak-builder</command>

                <arg choice="plain">--show-manifest</arg>

                <arg choice="opt" rep="repeat">OPTION</arg>

                <arg choice="plain">MANIFEST</arg>

            </cmdsynopsis>

    </refsynopsisdiv>

    <refsect1>

        <title>Description</title>

        <para>

            <command>flatpak-builder</command> is a wrapper around the <command>flatpak build</command> command

            that automates the building of applications and their dependencies. It is one option you can use

            to build applications.

        </para>

        <para>

            The goal of <command>flatpak-builder</command> 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 <command>./configure

            && make && make install</command> 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.

        </para>

        <para>

            An invocation of <command>flatpak-builder</command> proceeds in these stages, each being specified

            in detail in json format in <arg choice="plain">MANIFEST</arg>:

            <itemizedlist mark='bullet'>

                <listitem>

                    <para>Download all sources</para>

                </listitem>

                <listitem>

                    <para>Initialize the application directory with <command>flatpak build-init</command></para>

                </listitem>

                <listitem>

                    <para>Build and install each module with <command>flatpak build</command></para>

                </listitem>

                <listitem>

                    <para>Clean up the final build tree by removing unwanted files and e.g. stripping binaries</para>

                </listitem>

                <listitem>

                    <para>Finish the application directory with <command>flatpak build-finish</command></para>

                </listitem>

            </itemizedlist>

            After this you will end up with a build of the application in <arg choice="plain">DIRECTORY</arg>, which you can

            export to a repository with the <command>flatpak build-export</command> command. If you use the <option>--repo</option>

            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.

        </para>

        <para>

            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 <arg choice="plain">MANIFEST</arg> file caused

            the build environment to change. This makes flatpak-builder very efficient for incremental builds.

        </para>

        <para>

            When building a flatpak to be published to the internet,

            <option>--collection-id=COLLECTION-ID</option> 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.

        </para>

    </refsect1>

    <refsect1>

        <title>Manifest</title>

        <para>The manifest file is a json or yaml file whose format is described in detail in its own manual page.</para>

    </refsect1>

    <refsect1>

        <title>Options</title>

        <para>The following options are understood:</para>

        <variablelist>

            <varlistentry>

                <term><option>-h</option></term>

                <term><option>--help</option></term>

                <listitem><para>

                    Show help options and exit.

                </para></listitem>

            </varlistentry>

            <varlistentry>

                <term><option>-v</option></term>

                <term><option>--verbose</option></term>

                <listitem><para>

                    Print debug information during command processing.

                </para></listitem>

            </varlistentry>

            <varlistentry>

                <term><option>--version</option></term>

                <listitem><para>

                    Print version information and exit.

                </para></listitem>

            </varlistentry>

            <varlistentry>

                <term><option>--arch=ARCH</option></term>

                <listitem><para>

                    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.

                </para></listitem>

            </varlistentry>

            <varlistentry>

                <term><option>--default-branch=<replaceable>BRANCH</replaceable></option></term>

                <listitem><para>

                    Set the default branch to

                    <replaceable>BRANCH</replaceable>. This is used if

                    the manifest does not specify a branch. The default

                    is <literal>master</literal>.

                </para></listitem>

            </varlistentry>

            <varlistentry>

                <term><option>--disable-cache</option></term>

                <listitem><para>

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

                </para></listitem>

            </varlistentry>

            <varlistentry>

                <term><option>--disable-rofiles-fuse</option></term>

                <listitem><para>

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

                </para></listitem>

            </varlistentry>

            <varlistentry>

                <term><option>--disable-download</option></term>

                <listitem><para>

                     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.

                </para></listitem>

            </varlistentry>

            <varlistentry>

                <term><option>--disable-updates</option></term>

                <listitem><para>

                  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.

                </para></listitem>

            </varlistentry>

            <varlistentry>

                <term><option>--disable-tests</option></term>

                <listitem><para>

                    Don't run any of the tests.

                </para></listitem>

            </varlistentry>

            <varlistentry>

                <term><option>--run</option></term>

                <listitem><para>

                  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.

                  </para>

                  <para>

                  Only the

                  <option>--arch=</option><replaceable>ARCH</replaceable>,

                  <option>--ccache</option> and

                  <option>--verbose</option> options can be combined

                  with this option.

                  </para>

                </listitem>

            </varlistentry>

            <varlistentry>

                <term><option>--build-shell=MODULENAME</option></term>

                <listitem><para>

                  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.

                </para></listitem>

            </varlistentry>

            <varlistentry>

                <term><option>--show-deps</option></term>

                <listitem><para>

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

                  </para>

                  <para>

                  Only the <option>--verbose</option> option can be combined

                  with this option.

                  </para>

                </listitem>

            </varlistentry>

            <varlistentry>

                <term><option>--show-manifest</option></term>

                <listitem><para>

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

                  </para>

                  <para>

                  Only the <option>--verbose</option> option can be combined

                  with this option.

                  </para>

                </listitem>

            </varlistentry>

            <varlistentry>

                <term><option>--download-only</option></term>

                <listitem><para>

                     Exit successfully after downloading the required sources.

                </para></listitem>

            </varlistentry>

            <varlistentry>

                <term><option>--bundle-sources</option></term>

                <listitem><para>

                    Create an additional runtime with the source code for

                    this module. It will be named

                    <replaceable>app-id</replaceable><literal>.Sources</literal>,

                    for example

                    <literal>org.gnome.Maps.Sources</literal>.

                </para></listitem>

            </varlistentry>

            <varlistentry>

                <term><option>--build-only</option></term>

                <listitem><para>

                     Don't do the cleanup and finish stages, which is useful if you

                     want to build more things into the app.

                </para></listitem>

            </varlistentry>

            <varlistentry>

                <term><option>--finish-only</option></term>

                <listitem><para>

                     Only do the cleanup, finish and export stages, picking up

                     where a --build-only command left off.

                </para></listitem>

            </varlistentry>

            <varlistentry>

                <term><option>--export-only</option></term>

                <listitem><para>

                    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.

                </para></listitem>

            </varlistentry>

            <varlistentry>

                <term><option>--require-changes</option></term>

                <listitem><para>

                    Do nothing, leaving a non-existent <arg choice="plain">DIRECTORY</arg> if nothing changes since

                    last cached build. If this is not specified, the latest version from the cache will be put

                    into <arg choice="plain">DIRECTORY</arg>.

                </para></listitem>

            </varlistentry>

            <varlistentry>

                <term><option>--state-dir=PATH</option></term>

                <listitem><para>

                  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 <arg choice="plain">DIRECTORY</arg>.

                </para></listitem>

            </varlistentry>

            <varlistentry>

                <term><option>--keep-build-dirs</option></term>

                <listitem><para>

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

                </para></listitem>

            </varlistentry>

            <varlistentry>

                <term><option>--delete-build-dirs</option></term>

                <listitem><para>

                    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.

                </para></listitem>

            </varlistentry>

            <varlistentry>

                <term><option>--ccache</option></term>

                <listitem><para>

                     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.

                </para></listitem>

            </varlistentry>

            <varlistentry>

                <term><option>--stop-at=MODULENAME</option></term>

                <listitem><para>

                     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.

                </para></listitem>

            </varlistentry>

            <varlistentry>

                <term><option>--repo=DIR</option></term>

                <listitem><para>

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

                </para></listitem>

            </varlistentry>

            <varlistentry>

                <term><option>-s</option></term>

                <term><option>--subject=SUBJECT</option></term>

                <listitem><para>

                    One line subject for the commit message.

                    Used when exporting the build results.

                </para></listitem>

            </varlistentry>

            <varlistentry>

                <term><option>-b</option></term>

                <term><option>--body=BODY</option></term>

                <listitem><para>

                    Full description for the commit message.

                    Used when exporting the build results.

                </para></listitem>

            </varlistentry>

            <varlistentry>

                <term><option>--collection-id=COLLECTION-ID</option></term>

                <listitem><para>

                    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.

                </para></listitem>

            </varlistentry>

            <varlistentry>

                <term><option>--gpg-sign=KEYID</option></term>

                <listitem><para>

                    Sign the commit with this GPG key.

                    Used when exporting the build results.

                    This option can be used multiple times.

                </para></listitem>

            </varlistentry>

            <varlistentry>

                <term><option>--gpg-homedir=PATH</option></term>

                <listitem><para>

                    GPG Homedir to use when looking for keyrings.

                    Used when exporting the build results.

                </para></listitem>

            </varlistentry>

            <varlistentry>

                <term><option>--jobs=JOBS</option></term>

                <listitem><para>

                     Limit the number of parallel jobs during the build.

                     The default is the number of CPUs on the machine.

                </para></listitem>

            </varlistentry>

            <varlistentry>

                <term><option>--force-clean</option></term>

                <listitem><para>

                    Erase the previous contents of DIRECTORY if it is

                    not empty.

                </para></listitem>

            </varlistentry>

            <varlistentry>

                <term><option>--sandbox</option></term>

                <listitem><para>

                    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.

                </para></listitem>

            </varlistentry>

            <varlistentry>

                <term><option>--allow-missing-runtimes</option></term>

                <listitem><para>

                    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.

                </para></listitem>

            </varlistentry>

            <varlistentry>

                <term><option>--rebuild-on-sdk-change</option></term>

                <listitem><para>

                  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.

                </para></listitem>

            </varlistentry>

            <varlistentry>

                <term><option>--skip-if-unchanged</option></term>

                <listitem><para>

                  If the json is unchanged since the last build of this filename, then

                  do nothing, and return exit code 42.

                </para></listitem>

            </varlistentry>

            <varlistentry>

                <term><option>--mirror-screenshots-url=URL</option></term>

                <listitem><para>

                  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.

                </para></listitem>

            </varlistentry>

            <varlistentry>

                <term><option>--extra-sources=SOURCE-DIR</option></term>

                <listitem><para>

                  When downloading sources (archives, files, git, bzr, svn), look in this

                  directory for pre-existing copies and use them instead of downloading.

                </para></listitem>

            </varlistentry>

            <varlistentry>

                <term><option>--extra-sources-url=URL</option></term>

                <listitem><para>

                  When downloading sources (archives, files, git, bzr, svn), look at this url

                  for mirrored downloads before downloading from the original url.

                </para></listitem>

            </varlistentry>

            <varlistentry>

                <term><option>--from-git=GIT</option></term>

                <listitem><para>

                  Look for the manifest in the given git repository. If this option is

                  given, MANIFEST is interpreted as a relative path inside the repository.

                </para></listitem>

            </varlistentry>

            <varlistentry>

                <term><option>--from-git-branch=BRANCH</option></term>

                <listitem><para>

                  The branch to use with --from-git.

                </para></listitem>

            </varlistentry>

            <varlistentry>

                <term><option>--no-shallow-clone</option></term>

                <listitem><para>

                  Don't use shallow clones when mirroring git repos.

                </para></listitem>

            </varlistentry>

            <varlistentry>

                <term><option>--add-tag=TAG</option></term>

                <listitem><para>

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

                </para></listitem>

            </varlistentry>

            <varlistentry>

                <term><option>--remove-tag=TAG</option></term>

                <listitem><para>

                  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.

                </para></listitem>

            </varlistentry>

            <varlistentry>

                <term><option>--install-deps-from=REMOTE</option></term>

                <listitem><para>

                    Install/update build required dependencies from the specified remote.

                </para></listitem>

            </varlistentry>

            <varlistentry>

                <term><option>--install-deps-only</option></term>

                <listitem><para>

                    Stop after downloading dependencies.

                </para></listitem>

            </varlistentry>

            <varlistentry>

                <term><option>--install</option></term>

                <listitem><para>

                    When the build is finished, install the result locally.

                </para></listitem>

            </varlistentry>

            <varlistentry>

                <term><option>--user</option></term>

                <listitem><para>

                    Install the dependencies in a per-user installation.

                </para></listitem>

            </varlistentry>

            <varlistentry>

                <term><option>--system</option></term>

                <listitem><para>

                    Install the dependencies in the default system-wide installation.

                </para></listitem>

            </varlistentry>

            <varlistentry>

                <term><option>--installation=NAME</option></term>

                <listitem><para>

                    Install the dependencies in a system-wide installation

                    specified by <arg choice="plain">NAME</arg> among those defined in

                    <filename>/etc/flatpak/installations.d/</filename>. Using

                    <arg choice="plain">--installation=default</arg> is equivalent to using

                    <arg choice="plain">--system</arg>.

                </para></listitem>

            </varlistentry>

          </variablelist>

    </refsect1>

    <refsect1>

        <title>Caching</title>

        <para>

            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

            <option>--keep-build-dirs</option>, build directories for

            each module are also stored here.

        </para>

        <para>

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

        </para>

    </refsect1>

    <refsect1>

        <title>Examples</title>

        <para>

            <command>$ flatpak-builder my-app-dir manifest.json</command>

        </para>

        <para>

            Example manifest file:

        </para>

<programlisting>

{

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

                }

            ]

        }

    ]

}

</programlisting>

    </refsect1>

    <refsect1>

        <title>See also</title>

        <para>

            <citerefentry><refentrytitle>flatpak</refentrytitle><manvolnum>1</manvolnum></citerefentry>,

            <citerefentry><refentrytitle>flatpak-manifest</refentrytitle><manvolnum>5</manvolnum></citerefentry>,

            <citerefentry><refentrytitle>flatpak-build-init</refentrytitle><manvolnum>1</manvolnum></citerefentry>,

            <citerefentry><refentrytitle>flatpak-build</refentrytitle><manvolnum>1</manvolnum></citerefentry>,

            <citerefentry><refentrytitle>flatpak-build-finish</refentrytitle><manvolnum>1</manvolnum></citerefentry>,

            <citerefentry><refentrytitle>flatpak-build-export</refentrytitle><manvolnum>1</manvolnum></citerefentry>

        </para>

    </refsect1>

</refentry>