forked from Mirrors/flatpak-builder
611 lines
28 KiB
XML
611 lines
28 KiB
XML
<?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">
|
|
|
|
<refentry id="xdg-app-builder">
|
|
|
|
<refentryinfo>
|
|
<title>xdg-app builder</title>
|
|
<productname>xdg-app</productname>
|
|
|
|
<authorgroup>
|
|
<author>
|
|
<contrib>Developer</contrib>
|
|
<firstname>Alexander</firstname>
|
|
<surname>Larsson</surname>
|
|
<email>alexl@redhat.com</email>
|
|
</author>
|
|
</authorgroup>
|
|
</refentryinfo>
|
|
|
|
<refmeta>
|
|
<refentrytitle>xdg-app-builder</refentrytitle>
|
|
<manvolnum>1</manvolnum>
|
|
</refmeta>
|
|
|
|
<refnamediv>
|
|
<refname>xdg-app-builder</refname>
|
|
<refpurpose>Help build application dependencies</refpurpose>
|
|
</refnamediv>
|
|
|
|
<refsynopsisdiv>
|
|
<cmdsynopsis>
|
|
<command>xdg-app-builder</command>
|
|
<arg choice="opt" rep="repeat">OPTION</arg>
|
|
<arg choice="plain">DIRECTORY</arg>
|
|
<arg choice="plain">MANIFEST</arg>
|
|
</cmdsynopsis>
|
|
</refsynopsisdiv>
|
|
|
|
<refsect1>
|
|
<title>Description</title>
|
|
|
|
<para>
|
|
<command>xdg-app-builder</command> is a wrapper around the <command>xdg-app 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>xdg-app-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>xdg-app-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>xdg-app build-init</command></para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>Build and install each module with <command>xdg-app 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>xdg-app 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>xdg-app build-export</command> command.
|
|
</para>
|
|
<para>
|
|
At each of the above steps xdg-app caches the result, and if you build the same file again, it will start
|
|
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
|
|
the build environment to change. This makes xdg-app-builder very efficient for incremental builds.
|
|
</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>
|
|
<term><option>app-id</option></term>
|
|
<listitem><para>A string defining the application id.</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>branch</option></term>
|
|
<listitem><para>The branch of the application, defaults to master.</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>runtime</option></term>
|
|
<listitem><para>The name of the runtime that the application uses.</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>runtime-version</option></term>
|
|
<listitem><para>The version of theruntime that the application uses, defaults to master.</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>sdk</option></term>
|
|
<listitem><para>The name of the development runtime that the application builds with.</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>command</option></term>
|
|
<listitem><para>The filename or path to the main binary of the application.</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>writable-sdk</option></term>
|
|
<listitem><para>If true, use a writable copy of the sdk for /usr.</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>build-options</option></term>
|
|
<listitem><para>object specifying the build environment. See below for details.</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>modules</option></term>
|
|
<listitem><para>An array of object specifying the modules to be built in order.
|
|
See below for details.</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>cleanup</option></term>
|
|
<listitem><para>An array of file patterns that should be removed at the end.
|
|
Patterns starting with / are taken to be full pathnames, otherwise they just match
|
|
the basename.</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>cleanup-commands</option></term>
|
|
<listitem><para>An array of commandlines that are run during the cleanup phase.</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>finish-args</option></term>
|
|
<listitem><para>An array of arguments passed to the <command>xdg-app build-finish</command> command</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>strip</option></term>
|
|
<listitem><para>If this is true (the default) then all ELF files will be stripped during the cleanup phase.</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>rename-desktop-file</option></term>
|
|
<listitem><para>Any desktop file with this name will be renamed to a name based on app-id during the cleanup phase.</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>rename-icon</option></term>
|
|
<listitem><para>Any icon with this name will be renamed to a name based on app-id during the cleanup phase.</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>copy-icon</option></term>
|
|
<listitem><para>If rename-icon is set, keep a copy of the old icon file.</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>desktop-file-name-prefix</option></term>
|
|
<listitem><para>This string will be prefixed to the Name key in the main application desktop file.</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>desktop-file-name-suffixed</option></term>
|
|
<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>
|
|
<term><option>cflags</option></term>
|
|
<listitem><para>This is set in the environment variable CFLAGS during the build.</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>cxxflags</option></term>
|
|
<listitem><para>This is set in the environment variable CXXFLAGS during the build.</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>prefix</option></term>
|
|
<listitem><para>The build prefix for the modules (defaults to <filename>/app</filename>).</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>env</option></term>
|
|
<listitem><para>This is a dictionary defining environment variables to be set during the build.</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>arch</option></term>
|
|
<listitem><para>This is a dictionary defining for each arch a separate build options object that override the main one</para></listitem>
|
|
</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>
|
|
<para>
|
|
These are the properties that are accepted:
|
|
</para>
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><option>name</option></term>
|
|
<listitem><para>The name of the module, used in e.g. build logs</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option></option>sources</term>
|
|
<listitem><para>An array of objects defining sources that will be downloaded and extracted in order</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>config-opts</option></term>
|
|
<listitem><para>An array of options that will be passed to configure</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>make-args</option></term>
|
|
<listitem><para>An array of arguments that will be passed to make</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>make-install-args</option></term>
|
|
<listitem><para>An array of arguments that will be passed to make install</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>rm-configure</option></term>
|
|
<listitem><para>If true, remove the configure script before starting build</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>no-autogen</option></term>
|
|
<listitem><para>Ignore the existance of an autogen script</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>cmake</option></term>
|
|
<listitem><para>Use cmake instead of configure</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>builddir</option></term>
|
|
<listitem><para>Force the use of a build dirrectory separated from the source directory.</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>subdir</option></term>
|
|
<listitem><para>Do building inside this subdirectory of the extracted sources.</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>build-options</option></term>
|
|
<listitem><para>A build options object that can override global options</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>post-install</option></term>
|
|
<listitem><para>An array of shell command that are run after the install phase. Can for example
|
|
clean up the install dir, or install extra files.
|
|
</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>cleanup</option></term>
|
|
<listitem><para>An array of file patterns that should be removed at the end.
|
|
Patterns starting with / are taken to be full pathnames, otherwise they just match
|
|
the basename. Note that any patterns will only match files installed by this module.
|
|
</para></listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</refsect2>
|
|
<refsect2>
|
|
<title>Sources</title>
|
|
<para>
|
|
These contain a pointer to the source that will be extracted into the source directory before
|
|
the build starts. They can be of several types, distiguished by the type property.
|
|
</para>
|
|
<refsect3>
|
|
<title>Archive sources (tar, zip)</title>
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><option>type</option></term>
|
|
<listitem><para>"archive"</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>url</option></term>
|
|
<listitem><para>URL of the archive</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>sha256</option></term>
|
|
<listitem><para>The sha256 checksum of the file, verified after download</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>strip-components</option></term>
|
|
<listitem><para>The number of initial pathname components to strip during extraction. Defaults to 1.</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>dest</option></term>
|
|
<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>
|
|
<varlistentry>
|
|
<term><option>url</option></term>
|
|
<listitem><para>URL of the git repostiory</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>branch</option></term>
|
|
<listitem><para>The branch/tag/commit to use from the git repostiory</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>dest</option></term>
|
|
<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>
|
|
<term><option>url</option></term>
|
|
<listitem><para>URL of the bzr repostiory</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>revision</option></term>
|
|
<listitem><para>A specific revision to use in the branch</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>dest</option></term>
|
|
<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>
|
|
<term><option>path</option></term>
|
|
<listitem><para>The path of a local file that will be copied into the source dir</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>url</option></term>
|
|
<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>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>sha256</option></term>
|
|
<listitem><para>The sha256 checksum of the file, verified after download. This is optional for local files.</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>dest-filename</option></term>
|
|
<listitem><para>Filename to use inside the source dir, default to the basename of path.</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>dest</option></term>
|
|
<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>
|
|
<term><option>commands</option></term>
|
|
<listitem><para>An array of shell commands that will be put in a shellscript file</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>dest-filename</option></term>
|
|
<listitem><para>Filename to use inside the source dir, default to the basename of path.</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>dest</option></term>
|
|
<listitem><para>Directory inside the source dir where the file will be copied.</para></listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</refsect3>
|
|
<refsect3>
|
|
<title>Patch sources</title>
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><option>type</option></term>
|
|
<listitem><para>"patch"</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>path</option></term>
|
|
<listitem><para>The path of a patch file that will be applied in the source dir</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>strip-components</option></term>
|
|
<listitem><para>The value of the -p argument to patch, defaults to 1.</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>dest</option></term>
|
|
<listitem><para>Directory inside the source dir where the patch will be applied.</para></listitem>
|
|
</varlistentry>
|
|
</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>
|
|
|
|
<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
|
|
already. This is useful to rebuild things but without updating git or bzr repositories
|
|
from the remote repository.
|
|
</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>--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>
|
|
Do nothing, leaving a non-existiant <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>--keep-build-dirs</option></term>
|
|
|
|
<listitem><para>
|
|
Don't remote 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>
|
|
|
|
</variablelist>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>Examples</title>
|
|
|
|
<para>
|
|
<command>$ xdg-app-builder my-app-dir manifest.json</command>
|
|
</para>
|
|
|
|
<para>
|
|
Example manifest file:
|
|
</para>
|
|
<programlisting>
|
|
{
|
|
"app-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"
|
|
}
|
|
]
|
|
}
|
|
]
|
|
}
|
|
</programlisting>
|
|
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>See also</title>
|
|
|
|
<para>
|
|
<citerefentry><refentrytitle>xdg-app</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
|
|
<citerefentry><refentrytitle>xdg-app-build-init</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
|
|
<citerefentry><refentrytitle>xdg-app-build-build</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
|
|
<citerefentry><refentrytitle>xdg-app-build-finish</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
|
|
<citerefentry><refentrytitle>xdg-app-build-export</refentrytitle><manvolnum>1</manvolnum></citerefentry>
|
|
</para>
|
|
|
|
</refsect1>
|
|
|
|
</refentry>
|