2015-11-16 15:23:23 +00:00
<?xml version='1.0'?> <!-- * - nxml - * -->
< !DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
2016-05-09 09:07:53 +00:00
<refentry id= "flatpak-builder" >
2015-11-16 15:23:23 +00:00
<refentryinfo >
2016-05-09 09:07:53 +00:00
<title > flatpak builder</title>
<productname > flatpak</productname>
2015-11-16 15:23:23 +00:00
<authorgroup >
<author >
<contrib > Developer</contrib>
<firstname > Alexander</firstname>
<surname > Larsson</surname>
<email > alexl@redhat.com</email>
</author>
</authorgroup>
</refentryinfo>
<refmeta >
2016-05-09 09:07:53 +00:00
<refentrytitle > flatpak-builder</refentrytitle>
2015-11-16 15:23:23 +00:00
<manvolnum > 1</manvolnum>
</refmeta>
<refnamediv >
2016-05-09 09:07:53 +00:00
<refname > flatpak-builder</refname>
2015-11-16 15:23:23 +00:00
<refpurpose > Help build application dependencies</refpurpose>
</refnamediv>
<refsynopsisdiv >
<cmdsynopsis >
2016-05-09 09:07:53 +00:00
<command > flatpak-builder</command>
2015-11-16 15:23:23 +00:00
<arg choice= "opt" rep= "repeat" > OPTION</arg>
<arg choice= "plain" > DIRECTORY</arg>
<arg choice= "plain" > MANIFEST</arg>
</cmdsynopsis>
2016-04-14 23:18:35 +00:00
<cmdsynopsis >
2016-05-09 09:07:53 +00:00
<command > flatpak-builder</command>
2016-04-14 23:18:35 +00:00
<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>
2015-11-16 15:23:23 +00:00
</refsynopsisdiv>
<refsect1 >
<title > Description</title>
<para >
2016-05-09 09:07:53 +00:00
<command > flatpak-builder</command> is a wrapper around the <command > flatpak build</command> command
2015-11-16 15:23:23 +00:00
that automates the building of applications and their dependencies. It is one option you can use
to build applications.
</para>
<para >
2016-05-09 09:07:53 +00:00
The goal of <command > flatpak-builder</command> is to push as much knowledge about how to build modules to
2015-11-16 15:23:23 +00:00
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 >
2016-05-09 09:07:53 +00:00
An invocation of <command > flatpak-builder</command> proceeds in these stages, each being specified
2015-11-16 15:23:23 +00:00
in detail in json format in <arg choice= "plain" > MANIFEST</arg> :
<itemizedlist mark= 'bullet' >
<listitem >
<para > Download all sources</para>
</listitem>
<listitem >
2016-05-09 09:07:53 +00:00
<para > Initialize the application directory with <command > flatpak build-init</command> </para>
2015-11-16 15:23:23 +00:00
</listitem>
<listitem >
2016-05-09 09:07:53 +00:00
<para > Build and install each module with <command > flatpak build</command> </para>
2015-11-16 15:23:23 +00:00
</listitem>
<listitem >
<para > Clean up the final build tree by removing unwanted files and e.g. stripping binaries</para>
</listitem>
<listitem >
2016-05-09 09:07:53 +00:00
<para > Finish the application directory with <command > flatpak build-finish</command> </para>
2015-11-16 15:23:23 +00:00
</listitem>
</itemizedlist>
After this you will end up with a build of the application in <arg choice= "plain" > DIRECTORY</arg> , which you can
2016-06-07 19:20:20 +00:00
export to a repository with the <command > flatpak build-export</command> command. If you use the <option > --repo</option>
option, flatpack-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.
2015-11-16 15:23:23 +00:00
</para>
<para >
2016-05-09 09:07:53 +00:00
At each of the above steps flatpak caches the result, and if you build the same file again, it will start
2015-11-16 15:23:23 +00:00
of 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
2016-05-09 09:07:53 +00:00
the build environment to change. This makes flatpak-builder very efficient for incremental builds.
2015-11-16 15:23:23 +00:00
</para>
</refsect1>
<refsect1 >
<title > Manifest format</title>
<refsect2 >
<title > Toplevel</title>
<para >
The top level of the json file describes global
attributes of the application, and how it can be
build, and the list of modules that need to be
built.
</para>
<para >
These are the properties that are accepted:
</para>
<variablelist >
<varlistentry >
2016-06-02 06:52:25 +00:00
<term > <option > id</option> or <option > app-id</option> (string)</term>
2015-11-16 15:23:23 +00:00
<listitem > <para > A string defining the application id.</para> </listitem>
</varlistentry>
<varlistentry >
2016-04-16 04:54:34 +00:00
<term > <option > branch</option> (string)</term>
2015-12-17 19:07:14 +00:00
<listitem > <para > The branch of the application, defaults to master.</para> </listitem>
2015-11-16 15:23:23 +00:00
</varlistentry>
<varlistentry >
2016-04-16 04:54:34 +00:00
<term > <option > runtime</option> (string)</term>
2015-11-16 15:23:23 +00:00
<listitem > <para > The name of the runtime that the application uses.</para> </listitem>
</varlistentry>
<varlistentry >
2016-04-16 04:54:34 +00:00
<term > <option > runtime-version</option> (string)</term>
2016-04-12 20:00:28 +00:00
<listitem > <para > The version of the runtime that the application uses, defaults to master.</para> </listitem>
2015-11-16 15:23:23 +00:00
</varlistentry>
<varlistentry >
2016-04-16 04:54:34 +00:00
<term > <option > sdk</option> (string)</term>
2015-11-16 15:23:23 +00:00
<listitem > <para > The name of the development runtime that the application builds with.</para> </listitem>
</varlistentry>
2016-06-04 22:01:10 +00:00
<varlistentry >
<term > <option > var</option> (string)</term>
<listitem > <para > Initialize the (otherwise empty) writable /var in the build with a copy of this runtime.</para> </listitem>
</varlistentry>
2016-01-18 10:43:02 +00:00
<varlistentry >
2016-04-16 04:54:34 +00:00
<term > <option > metadata</option> (string)</term>
2016-01-18 10:43:02 +00:00
<listitem > <para > Use this file as the base metadata file when finishing.</para> </listitem>
</varlistentry>
2015-11-16 15:23:23 +00:00
<varlistentry >
2016-04-16 04:54:34 +00:00
<term > <option > command</option> (string)</term>
2016-06-03 13:08:55 +00:00
<listitem > <para > The filename or path to the main binary of the application. Note that this is really just a single file, not a commandline. If you want to pass arguments, install a shell script wrapper and use that as the command.</para> </listitem>
2015-11-16 15:23:23 +00:00
</varlistentry>
2016-01-18 10:43:02 +00:00
<varlistentry >
2016-04-16 04:54:34 +00:00
<term > <option > build-runtime</option> (boolean)</term>
2016-01-18 10:43:02 +00:00
<listitem > <para > Build a new runtime instead of an application.</para> </listitem>
</varlistentry>
2016-02-18 18:22:34 +00:00
<varlistentry >
2016-04-16 04:54:34 +00:00
<term > <option > separate-locales</option> (boolean)</term>
<listitem > <para > Separate out locale files and translations to an extension runtime. Defaults to true.</para> </listitem>
2016-02-18 18:22:34 +00:00
</varlistentry>
2016-01-18 14:22:56 +00:00
<varlistentry >
2016-04-16 04:54:34 +00:00
<term > <option > id-platform</option> (string)</term>
2016-04-12 20:00:28 +00:00
<listitem > <para > When building a runtime sdk, also create a platform based on it with this id.</para> </listitem>
2016-01-18 14:22:56 +00:00
</varlistentry>
<varlistentry >
2016-04-16 04:54:34 +00:00
<term > <option > metadata-platform</option> (string)</term>
2016-01-18 14:22:56 +00:00
<listitem > <para > The metadata file to use for the platform we create.</para> </listitem>
</varlistentry>
2015-12-15 18:34:52 +00:00
<varlistentry >
2016-04-16 04:54:34 +00:00
<term > <option > writable-sdk</option> (boolean)</term>
2016-01-18 10:43:02 +00:00
<listitem > <para > If true, use a writable copy of the sdk for /usr.
2016-04-12 20:00:28 +00:00
Defaults to true if --build-runtime is specified.</para> </listitem>
2016-01-20 12:58:24 +00:00
</varlistentry>
2016-02-18 16:35:11 +00:00
<varlistentry >
2016-04-16 04:54:34 +00:00
<term > <option > appstream-compose</option> (boolean)</term>
2016-02-18 16:35:11 +00:00
<listitem > <para > Run appstream-compose during cleanup phase. Defaults to true.</para> </listitem>
</varlistentry>
2016-01-20 12:58:24 +00:00
<varlistentry >
2016-04-16 04:54:34 +00:00
<term > <option > sdk-extensions</option> (array of strings)</term>
2016-04-12 20:00:28 +00:00
<listitem > <para > Install these extra sdk extensions in /usr.</para> </listitem>
2015-12-15 18:34:52 +00:00
</varlistentry>
2016-01-20 13:40:02 +00:00
<varlistentry >
2016-04-16 04:54:34 +00:00
<term > <option > platform-extensions</option> (array of strings)</term>
2016-04-12 20:00:28 +00:00
<listitem > <para > Install these extra sdk extensions when creating the platform.</para> </listitem>
2016-01-20 13:40:02 +00:00
</varlistentry>
2016-02-17 13:54:16 +00:00
<varlistentry >
2016-04-16 04:54:34 +00:00
<term > <option > tags</option> (array of strings)</term>
2016-04-12 20:00:28 +00:00
<listitem > <para > Add these tags to the metadata file.</para> </listitem>
2016-02-17 13:54:16 +00:00
</varlistentry>
2015-11-16 15:23:23 +00:00
<varlistentry >
2016-04-16 04:54:34 +00:00
<term > <option > build-options</option> (object)</term>
2016-04-12 20:00:28 +00:00
<listitem > <para > Object specifying the build environment. See below for details.</para> </listitem>
2015-11-16 15:23:23 +00:00
</varlistentry>
<varlistentry >
2016-06-09 10:27:44 +00:00
<term > <option > modules</option> (array of objects or string)</term>
2016-07-22 19:05:15 +00:00
<listitem > <para > An array of objects specifying the modules to be built in order.
2016-06-09 10:27:44 +00:00
String members in the array are interpreted as the name of a separate json file that contains a module.
2015-11-16 15:23:23 +00:00
See below for details.</para> </listitem>
</varlistentry>
<varlistentry >
2016-04-16 04:54:34 +00:00
<term > <option > cleanup</option> (array of strings)</term>
2015-11-16 15:23:23 +00:00
<listitem > <para > An array of file patterns that should be removed at the end.
2016-04-13 11:49:25 +00:00
Patterns starting with / are taken to be full pathnames (without the /app prefix), otherwise they just match
2015-11-16 15:23:23 +00:00
the basename.</para> </listitem>
</varlistentry>
2015-12-16 13:43:12 +00:00
<varlistentry >
2016-04-16 04:54:34 +00:00
<term > <option > cleanup-commands</option> (array of strings)</term>
2015-12-16 13:43:12 +00:00
<listitem > <para > An array of commandlines that are run during the cleanup phase.</para> </listitem>
</varlistentry>
2016-01-18 14:22:56 +00:00
<varlistentry >
2016-04-16 04:54:34 +00:00
<term > <option > cleanup-platform</option> (array of strings)</term>
2016-01-18 14:22:56 +00:00
<listitem > <para > Extra files to clean up in the platform.</para> </listitem>
</varlistentry>
2015-11-16 15:23:23 +00:00
<varlistentry >
2016-04-16 04:54:34 +00:00
<term > <option > finish-args</option> (array of strings)</term>
2016-05-09 09:07:53 +00:00
<listitem > <para > An array of arguments passed to the <command > flatpak build-finish</command> command.</para> </listitem>
2015-11-16 15:23:23 +00:00
</varlistentry>
<varlistentry >
2016-04-16 04:54:34 +00:00
<term > <option > rename-desktop-file</option> (string)</term>
2016-04-12 20:00:28 +00:00
<listitem > <para > Any desktop file with this name will be renamed to a name based on id during the cleanup phase.</para> </listitem>
2016-01-12 15:30:20 +00:00
</varlistentry>
<varlistentry >
2016-04-16 04:54:34 +00:00
<term > <option > rename-appdata-file</option> (string)</term>
2016-04-12 20:00:28 +00:00
<listitem > <para > Any appdata file with this name will be renamed to a name based on id during the cleanup phase.</para> </listitem>
2015-11-16 15:23:23 +00:00
</varlistentry>
<varlistentry >
2016-04-16 04:54:34 +00:00
<term > <option > rename-icon</option> (string)</term>
2016-04-12 20:00:28 +00:00
<listitem > <para > Any icon with this name will be renamed to a name based on id during the cleanup phase.</para> </listitem>
2015-11-16 15:23:23 +00:00
</varlistentry>
2015-12-02 07:47:43 +00:00
<varlistentry >
2016-04-16 04:54:34 +00:00
<term > <option > copy-icon</option> (boolean)</term>
2015-12-02 07:47:43 +00:00
<listitem > <para > If rename-icon is set, keep a copy of the old icon file.</para> </listitem>
</varlistentry>
2015-11-16 15:23:23 +00:00
<varlistentry >
2016-04-16 04:54:34 +00:00
<term > <option > desktop-file-name-prefix</option> (string)</term>
2015-11-16 15:23:23 +00:00
<listitem > <para > This string will be prefixed to the Name key in the main application desktop file.</para> </listitem>
</varlistentry>
<varlistentry >
2016-06-02 06:52:25 +00:00
<term > <option > desktop-file-name-suffix</option> (string)</term>
2015-11-16 15:23:23 +00:00
<listitem > <para > This string will be suffixed to the Name key in the main application desktop file.</para> </listitem>
</varlistentry>
</variablelist>
</refsect2>
<refsect2 >
<title > Build Options</title>
<para >
Build options specify the build environment of a module, and can be specified globally as
well as per-module. Options can also be specified on a per-architecture basis using the arch property.
</para>
<para >
These are the properties that are accepted:
</para>
<variablelist >
<varlistentry >
2016-04-16 04:54:34 +00:00
<term > <option > cflags</option> (string)</term>
2015-11-16 15:23:23 +00:00
<listitem > <para > This is set in the environment variable CFLAGS during the build.</para> </listitem>
</varlistentry>
<varlistentry >
2016-04-16 04:54:34 +00:00
<term > <option > cxxflags</option> (string)</term>
2015-11-16 15:23:23 +00:00
<listitem > <para > This is set in the environment variable CXXFLAGS during the build.</para> </listitem>
</varlistentry>
2015-12-15 18:28:14 +00:00
<varlistentry >
2016-04-16 04:54:34 +00:00
<term > <option > prefix</option> (string)</term>
2016-01-18 10:43:02 +00:00
<listitem > <para > The build prefix for the modules (defaults to <filename > /app</filename> for
applications and <filename > /usr</filename> for runtimes).</para> </listitem>
2015-12-15 18:28:14 +00:00
</varlistentry>
2015-11-16 15:23:23 +00:00
<varlistentry >
2016-04-16 04:54:34 +00:00
<term > <option > env</option> (object)</term>
2015-11-16 15:23:23 +00:00
<listitem > <para > This is a dictionary defining environment variables to be set during the build.</para> </listitem>
</varlistentry>
2016-04-12 23:04:30 +00:00
<varlistentry >
2016-04-16 04:54:34 +00:00
<term > <option > build-args</option> (array of strings)</term>
2016-05-09 09:07:53 +00:00
<listitem > <para > This is an array containing extra options to pass to flatpak build.</para> </listitem>
2016-04-12 23:04:30 +00:00
</varlistentry>
2015-11-16 15:23:23 +00:00
<varlistentry >
2016-04-16 04:54:34 +00:00
<term > <option > strip</option> (boolean)</term>
2016-01-08 17:01:35 +00:00
<listitem > <para > If this is true (the default is false) then all ELF files will be stripped after install.</para> </listitem>
</varlistentry>
<varlistentry >
2016-04-16 04:54:34 +00:00
<term > <option > no-debuginfo</option> (boolean)</term>
2016-01-08 17:01:35 +00:00
<listitem > <para > If this is true (the default is false) and strip is not set then all ELF files will have their debug info extracted to a separate file.</para> </listitem>
</varlistentry>
<varlistentry >
2016-04-16 04:54:34 +00:00
<term > <option > arch</option> (object)</term>
2016-04-12 20:00:28 +00:00
<listitem > <para > This is a dictionary defining for each arch a separate build options object that override the main one.</para> </listitem>
2015-11-16 15:23:23 +00:00
</varlistentry>
</variablelist>
</refsect2>
<refsect2 >
<title > Module</title>
<para >
Each module specifies a source that has to be separately built and installed. It contains
the build options and a list of sources to download and extract before building.
</para>
2016-06-09 10:27:44 +00:00
<para >
Modules can be nested, in order to turn related modules on and off with a single key.
</para>
2015-11-16 15:23:23 +00:00
<para >
These are the properties that are accepted:
</para>
<variablelist >
<varlistentry >
2016-04-16 04:54:34 +00:00
<term > <option > name</option> (string)</term>
2016-05-27 04:42:37 +00:00
<listitem > <para > The name of the module, used in e.g. build logs. The name is also used for constructing filenames and commandline arguments, therefore using spaces or '/' in this string is a bad idea.</para> </listitem>
2015-11-16 15:23:23 +00:00
</varlistentry>
2016-05-09 15:24:42 +00:00
<varlistentry >
<term > <option > disabled</option> (boolean)</term>
<listitem > <para > If true, skip this module</para> </listitem>
</varlistentry>
2015-11-16 15:23:23 +00:00
<varlistentry >
2016-04-16 04:54:34 +00:00
<term > <option > sources</option> (array of objects)</term>
2015-11-16 15:23:23 +00:00
<listitem > <para > An array of objects defining sources that will be downloaded and extracted in order</para> </listitem>
</varlistentry>
<varlistentry >
2016-04-16 04:54:34 +00:00
<term > <option > config-opts</option> (array of strings)</term>
2015-11-16 15:23:23 +00:00
<listitem > <para > An array of options that will be passed to configure</para> </listitem>
</varlistentry>
<varlistentry >
2016-04-16 04:54:34 +00:00
<term > <option > make-args</option> (array of strings)</term>
2015-11-16 15:23:23 +00:00
<listitem > <para > An array of arguments that will be passed to make</para> </listitem>
</varlistentry>
<varlistentry >
2016-04-16 04:54:34 +00:00
<term > <option > make-install-args</option> (array of strings)</term>
2015-11-16 15:23:23 +00:00
<listitem > <para > An array of arguments that will be passed to make install</para> </listitem>
</varlistentry>
<varlistentry >
2016-04-16 04:54:34 +00:00
<term > <option > rm-configure</option> (boolean)</term>
2015-11-16 15:23:23 +00:00
<listitem > <para > If true, remove the configure script before starting build</para> </listitem>
</varlistentry>
<varlistentry >
2016-04-16 04:54:34 +00:00
<term > <option > no-autogen</option> (boolean)</term>
2016-05-17 07:28:33 +00:00
<listitem > <para > Ignore the existence of an autogen script</para> </listitem>
2015-11-16 15:23:23 +00:00
</varlistentry>
2016-02-01 20:40:22 +00:00
<varlistentry >
2016-04-16 04:54:34 +00:00
<term > <option > no-parallel-make</option> (boolean)</term>
2016-02-01 20:40:22 +00:00
<listitem > <para > Don't call make with arguments to build in parallel</para> </listitem>
</varlistentry>
2016-06-08 11:28:27 +00:00
<varlistentry >
<term > <option > no-python-timestamp-fix</option> (boolean)</term>
<listitem > <para > Don't fix up the *.py[oc] header timestamps for ostree use.</para> </listitem>
</varlistentry>
2015-11-27 08:32:22 +00:00
<varlistentry >
2016-04-16 04:54:34 +00:00
<term > <option > cmake</option> (boolean)</term>
2015-11-27 08:32:22 +00:00
<listitem > <para > Use cmake instead of configure</para> </listitem>
</varlistentry>
<varlistentry >
2016-06-24 08:33:02 +00:00
<term > <option > builddir</option> (boolean)</term>
2016-04-12 20:00:28 +00:00
<listitem > <para > Use a build directory that is separate from the source directory</para> </listitem>
2015-11-27 08:32:22 +00:00
</varlistentry>
2015-12-01 11:12:41 +00:00
<varlistentry >
2016-04-16 04:54:34 +00:00
<term > <option > subdir</option> (string)</term>
2016-04-12 20:00:28 +00:00
<listitem > <para > Build inside this subdirectory of the extracted sources</para> </listitem>
2015-12-01 11:12:41 +00:00
</varlistentry>
2015-11-16 15:23:23 +00:00
<varlistentry >
2016-04-16 04:54:34 +00:00
<term > <option > build-options</option> (object)</term>
2015-11-16 15:23:23 +00:00
<listitem > <para > A build options object that can override global options</para> </listitem>
</varlistentry>
2015-12-01 09:46:55 +00:00
<varlistentry >
2016-04-16 04:54:34 +00:00
<term > <option > post-install</option> (array of strings)</term>
2016-07-22 19:05:15 +00:00
<listitem > <para > An array of shell commands that are run after the install phase. Can for example
2015-12-01 09:46:55 +00:00
clean up the install dir, or install extra files.
</para> </listitem>
</varlistentry>
2015-11-16 15:23:23 +00:00
<varlistentry >
2016-04-16 04:54:34 +00:00
<term > <option > cleanup</option> (array of strings)</term>
2015-11-16 15:23:23 +00:00
<listitem > <para > An array of file patterns that should be removed at the end.
2016-04-13 11:49:25 +00:00
Patterns starting with / are taken to be full pathnames (without the /app prefix), otherwise they just match
2015-11-16 15:23:23 +00:00
the basename. Note that any patterns will only match files installed by this module.
</para> </listitem>
</varlistentry>
2016-01-18 14:22:56 +00:00
<varlistentry >
2016-04-16 04:54:34 +00:00
<term > <option > cleanup-platform</option> (array of strings)</term>
2016-01-18 14:22:56 +00:00
<listitem > <para > Extra files to clean up in the platform.</para> </listitem>
</varlistentry>
2016-06-09 10:27:44 +00:00
<varlistentry >
<term > <option > modules</option> (array of objects or strings)</term>
2016-07-22 19:05:15 +00:00
<listitem > <para > An array of objects specifying nested modules to be built before this one.
2016-06-09 10:27:44 +00:00
String members in the array are interpreted as names of a separate json file that contains a module.</para> </listitem>
</varlistentry>
2015-11-16 15:23:23 +00:00
</variablelist>
</refsect2>
<refsect2 >
<title > Sources</title>
<para >
These contain a pointer to the source that will be extracted into the source directory before
2016-05-27 06:40:23 +00:00
the build starts. They can be of several types, distinguished by the type property.
2015-11-16 15:23:23 +00:00
</para>
<refsect3 >
<title > Archive sources (tar, zip)</title>
<variablelist >
<varlistentry >
<term > <option > type</option> </term>
<listitem > <para > "archive"</para> </listitem>
</varlistentry>
2016-02-17 13:50:01 +00:00
<varlistentry >
2016-04-16 04:54:34 +00:00
<term > <option > path</option> (string)</term>
2016-02-17 13:50:01 +00:00
<listitem > <para > The path of the archive</para> </listitem>
</varlistentry>
2015-11-16 15:23:23 +00:00
<varlistentry >
2016-04-16 04:54:34 +00:00
<term > <option > url</option> (string)</term>
2016-07-22 19:05:15 +00:00
<listitem > <para > The URL of a remote archive that will be downloaded. This overrides path if both are specified.</para> </listitem>
2015-11-16 15:23:23 +00:00
</varlistentry>
<varlistentry >
2016-04-16 04:54:34 +00:00
<term > <option > sha256</option> (string)</term>
2015-11-16 15:23:23 +00:00
<listitem > <para > The sha256 checksum of the file, verified after download</para> </listitem>
</varlistentry>
<varlistentry >
2016-04-16 04:54:34 +00:00
<term > <option > strip-components</option> (integer)</term>
2015-11-16 15:23:23 +00:00
<listitem > <para > The number of initial pathname components to strip during extraction. Defaults to 1.</para> </listitem>
</varlistentry>
<varlistentry >
2016-04-16 04:54:34 +00:00
<term > <option > dest</option> (string)</term>
2015-11-16 15:23:23 +00:00
<listitem > <para > Directory inside the source dir where the archive will be extracted.</para> </listitem>
</varlistentry>
</variablelist>
</refsect3>
<refsect3 >
<title > Git sources</title>
<variablelist >
<varlistentry >
<term > <option > type</option> </term>
<listitem > <para > "git"</para> </listitem>
</varlistentry>
2016-07-29 19:52:47 +00:00
<varlistentry >
<term > <option > path</option> (string)</term>
<listitem > <para > The path to a local checkout of the git repository. Due to how git-clone works, this will be much faster than specifying a URL of file:///...</para> </listitem>
</varlistentry>
2015-11-16 15:23:23 +00:00
<varlistentry >
2016-04-16 04:54:34 +00:00
<term > <option > url</option> (string)</term>
2016-07-29 19:52:47 +00:00
<listitem > <para > URL of the git repository. This overrides path if both are specified.</para> </listitem>
2015-11-16 15:23:23 +00:00
</varlistentry>
<varlistentry >
2016-04-16 04:54:34 +00:00
<term > <option > branch</option> (string)</term>
2016-05-27 06:45:53 +00:00
<listitem > <para > The branch/tag/commit to use from the git repository</para> </listitem>
2015-11-16 15:23:23 +00:00
</varlistentry>
<varlistentry >
2016-04-16 04:54:34 +00:00
<term > <option > dest</option> (string)</term>
2015-11-16 15:23:23 +00:00
<listitem > <para > Directory inside the source dir where the repository will be checked out.</para> </listitem>
</varlistentry>
</variablelist>
</refsect3>
<refsect3 >
<title > Bzr sources</title>
<variablelist >
<varlistentry >
<term > <option > type</option> </term>
<listitem > <para > "bzr"</para> </listitem>
</varlistentry>
<varlistentry >
2016-04-16 04:54:34 +00:00
<term > <option > url</option> (string)</term>
2016-05-27 06:45:53 +00:00
<listitem > <para > URL of the bzr repository</para> </listitem>
2015-11-16 15:23:23 +00:00
</varlistentry>
2015-12-09 13:06:59 +00:00
<varlistentry >
2016-04-16 04:54:34 +00:00
<term > <option > revision</option> (string)</term>
2015-12-09 13:06:59 +00:00
<listitem > <para > A specific revision to use in the branch</para> </listitem>
</varlistentry>
2015-11-16 15:23:23 +00:00
<varlistentry >
2016-04-16 04:54:34 +00:00
<term > <option > dest</option> (string)</term>
2015-11-16 15:23:23 +00:00
<listitem > <para > Directory inside the source dir where the repository will be checked out.</para> </listitem>
</varlistentry>
</variablelist>
</refsect3>
<refsect3 >
<title > File sources</title>
<variablelist >
<varlistentry >
<term > <option > type</option> </term>
<listitem > <para > "file"</para> </listitem>
</varlistentry>
<varlistentry >
2016-04-16 04:54:34 +00:00
<term > <option > path</option> (string)</term>
2015-11-16 15:23:23 +00:00
<listitem > <para > The path of a local file that will be copied into the source dir</para> </listitem>
</varlistentry>
2015-12-09 11:01:55 +00:00
<varlistentry >
2016-04-16 04:54:34 +00:00
<term > <option > url</option> (string)</term>
2016-07-22 19:05:15 +00:00
<listitem > <para > The URL of a remote file that will be downloaded and copied into the source dir. This overrides path if both are specified.</para> </listitem>
2015-12-09 11:01:55 +00:00
</varlistentry>
<varlistentry >
2016-04-16 04:54:34 +00:00
<term > <option > sha256</option> (string)</term>
2015-12-09 11:01:55 +00:00
<listitem > <para > The sha256 checksum of the file, verified after download. This is optional for local files.</para> </listitem>
</varlistentry>
2015-11-16 15:23:23 +00:00
<varlistentry >
2016-04-16 04:54:34 +00:00
<term > <option > dest-filename</option> (string)</term>
2015-12-01 10:08:30 +00:00
<listitem > <para > Filename to use inside the source dir, default to the basename of path.</para> </listitem>
</varlistentry>
<varlistentry >
2016-04-16 04:54:34 +00:00
<term > <option > dest</option> (string)</term>
2015-12-01 10:08:30 +00:00
<listitem > <para > Directory inside the source dir where the file will be copied.</para> </listitem>
</varlistentry>
</variablelist>
</refsect3>
<refsect3 >
<title > Script sources</title>
<para >
This is a way to create a shell (/bin/sh) script from an inline set of commands.
</para>
<variablelist >
<varlistentry >
<term > <option > type</option> </term>
<listitem > <para > "script"</para> </listitem>
</varlistentry>
<varlistentry >
2016-04-16 04:54:34 +00:00
<term > <option > commands</option> (array of strings)</term>
2015-12-01 10:08:30 +00:00
<listitem > <para > An array of shell commands that will be put in a shellscript file</para> </listitem>
</varlistentry>
<varlistentry >
2016-04-16 04:54:34 +00:00
<term > <option > dest-filename</option> (string)</term>
2015-11-16 15:23:23 +00:00
<listitem > <para > Filename to use inside the source dir, default to the basename of path.</para> </listitem>
</varlistentry>
<varlistentry >
2016-04-16 04:54:34 +00:00
<term > <option > dest</option> (string)</term>
2015-11-16 15:23:23 +00:00
<listitem > <para > Directory inside the source dir where the file will be copied.</para> </listitem>
</varlistentry>
</variablelist>
</refsect3>
2016-02-22 15:26:46 +00:00
<refsect3 >
<title > Shell sources</title>
<para >
2016-07-22 19:05:15 +00:00
This is a way to create/modify the sources by running shell commands.
2016-02-22 15:26:46 +00:00
</para>
<variablelist >
<varlistentry >
<term > <option > type</option> </term>
<listitem > <para > "shell"</para> </listitem>
</varlistentry>
<varlistentry >
2016-04-16 04:54:34 +00:00
<term > <option > commands</option> (array of strings)</term>
2016-02-22 15:26:46 +00:00
<listitem > <para > An array of shell commands that will be run during source extraction</para> </listitem>
</varlistentry>
</variablelist>
</refsect3>
2015-11-16 15:23:23 +00:00
<refsect3 >
<title > Patch sources</title>
<variablelist >
<varlistentry >
<term > <option > type</option> </term>
<listitem > <para > "patch"</para> </listitem>
</varlistentry>
<varlistentry >
2016-04-16 04:54:34 +00:00
<term > <option > path</option> (string)</term>
2015-11-16 15:23:23 +00:00
<listitem > <para > The path of a patch file that will be applied in the source dir</para> </listitem>
</varlistentry>
<varlistentry >
2016-04-16 04:54:34 +00:00
<term > <option > strip-components</option> (integer)</term>
2015-11-16 15:23:23 +00:00
<listitem > <para > The value of the -p argument to patch, defaults to 1.</para> </listitem>
</varlistentry>
<varlistentry >
2016-04-16 04:54:34 +00:00
<term > <option > dest</option> (string)</term>
2015-11-16 15:23:23 +00:00
<listitem > <para > Directory inside the source dir where the patch will be applied.</para> </listitem>
</varlistentry>
2016-06-28 10:44:21 +00:00
<varlistentry >
<term > <option > use-git</option> (boolean)</term>
<listitem > <para > Whether to use "git apply" rather than "patch" to apply the patch, required when the patch file contains binary diffs.</para> </listitem>
</varlistentry>
2015-11-16 15:23:23 +00:00
</variablelist>
</refsect3>
</refsect2>
</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>
2016-04-30 21:43:39 +00:00
<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>
2015-11-16 15:23:23 +00:00
<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-download</option> </term>
<listitem > <para >
Don't download any sources. This only works if some version of all sources are downloaded
2015-12-21 09:39:23 +00:00
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 or bzr repositories from the remote repository.
2015-11-16 15:23:23 +00:00
</para> </listitem>
</varlistentry>
2016-02-17 08:45:12 +00:00
<varlistentry >
<term > <option > --run</option> </term>
<listitem > <para >
2016-05-09 09:07:53 +00:00
Run a command in a sandbox based on the build dir. This starts flatpak build, with some extra
2016-02-17 08:45:12 +00:00
arguments to give the same environment as the build, and the same permissions the final app
2016-04-14 23:18:35 +00:00
will have. The command to run must be the last argument passed to
2016-05-09 09:07:53 +00:00
flatpak-builder, after the directory and the manifest.
2016-02-17 08:45:12 +00:00
</para> </listitem>
</varlistentry>
2015-11-16 15:23:23 +00:00
<varlistentry >
2015-11-26 13:42:56 +00:00
<term > <option > --download-only</option> </term>
2015-11-16 15:23:23 +00:00
<listitem > <para >
Exit successfully after downloading the required sources.
</para> </listitem>
</varlistentry>
2015-11-26 13:42:56 +00:00
<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 > --require-changes</option> </term>
<listitem > <para >
2016-04-26 08:34:53 +00:00
Do nothing, leaving a non-existent <arg choice= "plain" > DIRECTORY</arg> if nothing changes since
2015-11-26 13:42:56 +00:00
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>
2015-12-09 20:10:22 +00:00
<varlistentry >
<term > <option > --keep-build-dirs</option> </term>
<listitem > <para >
2016-04-13 13:36:19 +00:00
Don't remove the sources and build after having built and installed each module.
2015-12-09 20:10:22 +00:00
This also creates a symlink to the build directory with a stable name ("build-modulename").
</para> </listitem>
</varlistentry>
2016-01-12 11:09:09 +00:00
<varlistentry >
<term > <option > --ccache</option> </term>
<listitem > <para >
Enable use of ccache in the build (needs ccache in the sdk)
</para> </listitem>
</varlistentry>
2016-01-12 11:18:11 +00:00
<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 > --gpg-sign=KEYID</option> </term>
<listitem > <para >
2016-01-17 18:32:15 +00:00
Sign the commit with this GPG key.
2016-01-12 11:18:11 +00:00
Used when exporting the build results.
2016-07-22 17:32:45 +00:00
This option can be used multiple times.
2016-01-12 11:18:11 +00:00
</para> </listitem>
</varlistentry>
<varlistentry >
<term > <option > --gpg-homedir=PATH</option> </term>
<listitem > <para >
2016-01-17 18:32:15 +00:00
GPG Homedir to use when looking for keyrings.
2016-01-12 11:18:11 +00:00
Used when exporting the build results.
</para> </listitem>
</varlistentry>
2016-04-14 23:29:41 +00:00
<varlistentry >
<term > <option > --force-clean</option> </term>
<listitem > <para >
Erase the previous contents of DIRECTORY if it is
not empty.
</para> </listitem>
</varlistentry>
2016-01-12 11:18:11 +00:00
</variablelist>
2015-11-16 15:23:23 +00:00
</refsect1>
2016-04-13 13:26:59 +00:00
<refsect1 >
<title > Caching</title>
<para >
2016-05-09 09:07:53 +00:00
flatpak-builder caches sources and partial build results in
the .flatpak-builder subdirectory of the current directory. If you
2016-04-13 13:26:59 +00:00
use <option > --keep-build-dirs</option> , build directories for each
module are also stored here.
</para>
<para >
2016-05-09 09:07:53 +00:00
It is safe to remove the contents of the .flatpak-builder
2016-04-13 13:26:59 +00:00
directory. This will force a full build the next time you build.
</para>
</refsect1>
2015-11-16 15:23:23 +00:00
<refsect1 >
<title > Examples</title>
<para >
2016-05-09 09:07:53 +00:00
<command > $ flatpak-builder my-app-dir manifest.json</command>
2015-11-16 15:23:23 +00:00
</para>
<para >
Example manifest file:
</para>
<programlisting >
{
2016-04-12 20:00:28 +00:00
"id": "org.test.TestApp",
2015-11-16 15:23:23 +00:00
"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"
}
]
}
]
}
</programlisting>
</refsect1>
<refsect1 >
<title > See also</title>
<para >
2016-05-09 09:07:53 +00:00
<citerefentry > <refentrytitle > flatpak</refentrytitle> <manvolnum > 1</manvolnum> </citerefentry> ,
<citerefentry > <refentrytitle > flatpak-build-init</refentrytitle> <manvolnum > 1</manvolnum> </citerefentry> ,
2016-06-10 02:34:32 +00:00
<citerefentry > <refentrytitle > flatpak-build</refentrytitle> <manvolnum > 1</manvolnum> </citerefentry> ,
2016-05-09 09:07:53 +00:00
<citerefentry > <refentrytitle > flatpak-build-finish</refentrytitle> <manvolnum > 1</manvolnum> </citerefentry> ,
<citerefentry > <refentrytitle > flatpak-build-export</refentrytitle> <manvolnum > 1</manvolnum> </citerefentry>
2015-11-16 15:23:23 +00:00
</para>
</refsect1>
</refentry>