Manifests¶
The input to flatpak-builder
is a JSON or YAML file that describes the
parameters for building an application, as well as instructions for each of
the modules that are to be built. This file is called the manifest.
This page provides information and guidance on how to use manifests, including an explanation of the most common parameters that can be specified. It is recommended to have followed the Erstellen des ersten Flatpaks tutorial before reading this section, and to be familiar with Flatpak Builder.
Manifest files should be named using the application ID. For example, the
manifest file for GNOME Dictionary is named org.gnome.Dictionary.yml
. This
page uses this manifest file for all its examples.
A complete list of all the properties that can be specified in manifest files
can be found in the Flatpak Builder Command Reference, as well as the
flatpak-manifest
man page.
Basic properties¶
Each manifest file should specify basic information about the application that
is to be built, including the id
, runtime
, runtime-version
,
sdk
and command
parameters. These properties are typically specified
at the beginning of the file.
For example, the GNOME Dictionary manifest includes:
id: org.gnome.Dictionary
runtime: org.gnome.Platform
runtime-version: '45'
sdk: org.gnome.Sdk
command: gnome-dictionary
Specifying a runtime and runtime version allows that the runtime that is needed by your application to be automatically installed on users‘ systems.
File renaming¶
Exports are application files that are made available to the host, and include
things like the application’s .desktop
file and icon.
The names of files that are exported by a Flatpak must be prefixed using the
application ID, such as org.gnome.Dictionary.desktop
. The best way to
do this is to rename these files directly in the application’s source.
If renaming exported files to use the application ID is not possible,
flatpak-builder
allows them to be renamed as part of the build
process. This can be done by specifying one of the following properties in
the manifest:
rename-icon
- rename the application iconrename-desktop-file
- rename the.desktop
filenamerename-appdata-file
- rename the MetaInfo file
Each of these properties accepts the name of the source file to be
renamed. flatpak-builder
then automatically renames the file to match
the application ID. Note that this renaming method can introduce internal
naming conflicts, and that renaming files in tree is therefore the most
reliable approach.
Finishing¶
Applications that are run with Flatpak have extremely limited access to the host environment by default, but applications require access to resources outside of their sandbox in order to be useful. Finishing is the build stage where the application’s sandbox permissions are specified, in order to give access to these resources.
The finishing manifest section uses the finish-args
property, which can
be seen in the Dictionary manifest file:
finish-args:
# X11 + XShm access
- --share=ipc
- --socket=fallback-x11
# Wayland access
- --socket=wayland
# GPU acceleration if needed
- --device=dri
# Needs to talk to the network:
- --share=network
# Needs to save files locally
- --filesystem=xdg-documents
Guidance on which permissions to use can be found in the Sandbox Permissions.
Cleanup¶
The cleanup property can be used to remove files produced by the build process that are not wanted as part of the application, such as headers or developer documentation. Two properties in the manifest file are used for this. This can be either done for each modules in which case only names created by that module will be matched or at the toplevel which will match anything created in the entire manifest.
Items starting with / are taken to be relative to the prefix, so
/include
will cleanup /app/include
, otherwise it matches the
basename.
First, a list of filename patterns can be included:
cleanup:
- '/include'
- '/bin/foo-*'
- '*.a'
A cleanup with *
, at the module level will cleanup all artifacts
built from that module. This is often useful for build dependencies of
a module that does not need to be shipped in the final Flatpak package:
cleanup:
- '*'
The cleanup-commands property can be a list of cleanup commands:
cleanup-commands:
- 'find /app/bin -mindepth 1 -maxdepth 1 -name 'rpm*' ! -name 'rpm2cpio' -delete'
Note that, instead of cleaning up unnecessary files, it is often better
to build less components through config-opts, build-commands, make-args
.
For example, if the application does not need documentation files or
manpages, it’s best to stop building them. This should make the build
faster in some cases and reduce the need for excessive cleanups.
Modules¶
The module list specifies each of the modules that are to be built as part of the build process. One of these modules is the application itself, and other modules are dependencies and libraries that are bundled as part of the Flatpak. While simple applications may only specify one or two modules, and therefore have short modules sections, some applications can bundle numerous modules and therefore have lengthy modules sections.
GNOME Dictionary’s modules section is short, since it just contains the application itself, and looks like:
modules:
- name: gnome-dictionary
buildsystem: meson
config-opts:
- -Dbuild_man=false
sources:
- type: archive
url: https://download.gnome.org/sources/gnome-dictionary/3.26/gnome-dictionary-3.26.1.tar.xz
sha256: 16b8bc248dcf68987826d5e39234b1bb7fd24a2607fcdbf4258fde88f012f300
- type: patch
path: appdata_oars.patch
As can be seen, each listed module has a name
(which can be freely
assigned) and a list of sources
. Each source has a type
, and available
types include:
archive
-.tar
or.zip
archive files
git
- Git repositories
bzr
- Bazaar repositories
file
- local/remote files (these are copied into the source directory)
dir
- local directories (these are copied into the source directory)
script
- an array of shell commands (these are put in a shellscript file)
shell
- an array of shell commands that are run during source extraction
patch
- a patch (are applied to the source directory)
extra-data
- data that can be downloaded at install time; this can include archive or package files
Different properties are available for each source type, which are listed in the Module Sources.
Supported build systems¶
Modules can be built with a variety of build systems, including:
A „simple“ build method is also available, which allows a series of commands to be specified.
Flatpak Builder Tools¶
Flatpak Builder Tools (or flatpak-builder-tools) is a collection of scripts to aid using flatpak-builder. In this repository, each directory contains instructions to generate a manifest for the respective platform.
Example manifests¶
A complete manifest for GNOME Dictionary built from Git. It is also possible to browse all the manifests hosted by Flathub.