FLATPAK-BUILDER(1) flatpak builder FLATPAK-BUILDER(1)
NAME
flatpak-builder - Help build application dependencies
SYNOPSIS
flatpak-builder [OPTION...] DIRECTORY MANIFEST
flatpak-builder --run [OPTION...] DIRECTORY MANIFEST COMMAND
flatpak-builder --show-deps [OPTION...] MANIFEST
flatpak-builder --show-manifest [OPTION...] MANIFEST
DESCRIPTION
flatpak-builder is a wrapper around the flatpak build command that
automates the building of applications and their dependencies. It is
one option you can use to build applications.
The goal of flatpak-builder is to push as much knowledge about how to
build modules to the individual upstream projects. It does this by
assuming that the modules adhere to the Build API specified at
https://github.com/cgwalters/build-api. This essentially means that it
follows the ./configure && make && make install scheme with an optional
autogen script. If the upstream does not adhere to the API you can make
it do so by adding patches and extra files.
An invocation of flatpak-builder proceeds in these stages, each being
specified in detail in json format in MANIFEST:
• Download all sources
• Initialize the application directory with flatpak build-init
• Build and install each module with flatpak build
• Clean up the final build tree by removing unwanted files and e.g.
stripping binaries
• Finish the application directory with flatpak build-finish
After this you will end up with a build of the application in
DIRECTORY, which you can export to a repository with the flatpak
build-export command. If you use the --repo option, flatpak-builder
will do the export for you at the end of the build process. When
flatpak-builder does the export, it also stores the manifest that was
used for the build in /app/manifest.json. The manifest is 'resolved',
i.e. git branch names are replaced by the actual commit IDs that were
used in the build.
At each of the above steps flatpak caches the result, and if you build
the same file again, it will start at the first step where something
changes. For instance the first version controlled source that had new
commits added, or the first module where some changes to the MANIFEST
file caused the build environment to change. This makes flatpak-builder
very efficient for incremental builds.
When building a flatpak to be published to the internet,
--collection-id=COLLECTION-ID 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.
MANIFEST
The manifest file is a json or yaml file whose format is described in
detail in its own manual page.
OPTIONS
The following options are understood:
-h, --help
Show help options and exit.
-v, --verbose
Print debug information during command processing.
--version
Print version information and exit.
--arch=ARCH
Specify the machine architecture to build for. If no architecture
is specified, the host architecture will be automatically detected.
Only host compatible architectures can be specified.
--default-branch=BRANCH
Set the default branch to BRANCH. This is used if the manifest does
not specify a branch. The default is master.
--disable-cache
Don't look at the existing cache for a previous build, instead
always rebuild modules.
--disable-rofiles-fuse
Disable the use of rofiles-fuse to optimize the cache use via
hardlink checkouts.
--disable-download
Don't download any sources. This only works if some version of all
sources are downloaded already. This is useful if you want to
guarantee that no network i/o is done. However, the build will fail
if some source is not locally available.
--disable-updates
Download missing sources, but don't update local mirrors of version
control repos. This is useful to rebuild things but without
updating git, bzr or svn repositories from the remote repository.
--disable-tests
Don't run any of the tests.
--run
Run a command in a sandbox based on the build dir. This starts
flatpak build, with some extra arguments to give the same
environment as the build, and the same permissions the final app
will have (except filesystem permissions). The command to run must
be the last argument passed to flatpak-builder, after the directory
and the manifest.
Only the --arch=ARCH, --ccache and --verbose options can be
combined with this option.
--build-shell=MODULENAME
Extract and prepare the sources for the named module, and then
start a shell in a sandbox identical to the one flatpak-builder
would use for building the module. This is useful to debug a
module.
--show-deps
List all the (local) files that the manifest depends on.
Only the --verbose option can be combined with this option.
--show-manifest
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).
Only the --verbose option can be combined with this option.
--download-only
Exit successfully after downloading the required sources.
--bundle-sources
Create an additional runtime with the source code for this module.
It will be named app-id.Sources, for example
org.gnome.Maps.Sources.
--build-only
Don't do the cleanup and finish stages, which is useful if you want
to build more things into the app.
--finish-only
Only do the cleanup, finish and export stages, picking up where a
--build-only command left off.
--export-only
Only do the export stages, picking up the build result from a
previous build. This can be used to split the build and
export/signature into two calls by leaving out --repo in the first
call.
--require-changes
Do nothing, leaving a non-existent DIRECTORY if nothing changes
since last cached build. If this is not specified, the latest
version from the cache will be put into DIRECTORY.
--state-dir=PATH
Use this directory for storing state (downloads, build dirs, build
cache, etc) rather than .flatpak-builder. This can be an absolute
or relative path, but must be on the same filesystem as the
specified target DIRECTORY.
--keep-build-dirs
Don't remove the sources and build after having built and installed
each module. This also creates a symlink to the build directory
with a stable name ("build-modulename").
--delete-build-dirs
Always remove the sources and build after having built each module,
even if the build failed. The default is to keep failed build
directories but remove successful ones. This is useful in e.g.
automatic build systems.
--ccache
Enable use of ccache in the build (needs ccache in the sdk). The
default ccache folder can be overridden by setting the environment
variable CCACHE_DIR.
--stop-at=MODULENAME
Stop at the specified module, ignoring it and all the following
ones in both the "download" and "build" phases. This is useful for
debugging and development. For instance, you can build all the
dependencies, but stop at the main application so that you can then
do a build from a pre-existing checkout. Implies --build-only.
--repo=DIR
After the build finishes, run flatpak build-export to export the
result to the repository DIR. If DIR exists, it must be an OSTree
repository; otherwise a new one will be created.
-s, --subject=SUBJECT
One line subject for the commit message. Used when exporting the
build results.
-b, --body=BODY
Full description for the commit message. Used when exporting the
build results.
--collection-id=COLLECTION-ID
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.
--token-type=VAL
Set type of token needed to install this commit. Setting this to a
value greater than 0 implies that authentication will be needed to
install the flatpak. A token-type property set in the manifest
takes precedence over this option. Used when exporting the build
results.
--gpg-sign=KEYID
Sign the commit with this GPG key. Used when exporting the build
results. This option can be used multiple times.
--gpg-homedir=PATH
GPG Homedir to use when looking for keyrings. Used when exporting
the build results.
--jobs=JOBS
Limit the number of parallel jobs during the build. The default is
the number of CPUs on the machine.
--force-clean
Erase the previous contents of DIRECTORY if it is not empty.
--sandbox
Disable the possibility to specify build-args that are passed to
flatpak build. This means the build process can't break out of its
sandbox, and is useful when building less trusted software.
--allow-missing-runtimes
Do not immediately fail if the sdk or platform runtimes are not
installed on this system. Attempting to build any manifest modules
will still fail if the sdk is missing, but may be useful for apps
that install files without a sandbox build.
--rebuild-on-sdk-change
Record the exact version of the sdk in the cache, and rebuild
everything if it changes. This is useful if you're building against
an API-unstable runtime, like a nightly build.
--skip-if-unchanged
If the json is unchanged since the last build of this filename,
then do nothing, and return exit code 42.
--mirror-screenshots-url=URL
Mirror any screenshots in the appstream and rewrite the appstream
xml as if they were on the specified URL. The resulting files will
be stored in the "screenshots" subdirectory in the app directory
and needs to be copied to the specified URL for the appdata to
work.
--extra-sources=SOURCE-DIR
When downloading sources (archives, files, git, bzr, svn), look in
this directory for pre-existing copies and use them instead of
downloading.
--extra-sources-url=URL
When downloading sources (archives, files, git, bzr, svn), look at
this url for mirrored downloads before downloading from the
original url.
--from-git=GIT
Look for the manifest in the given git repository. If this option
is given, MANIFEST is interpreted as a relative path inside the
repository.
--from-git-branch=BRANCH
The branch to use with --from-git.
--no-shallow-clone
Don't use shallow clones when mirroring git repos.
--add-tag=TAG
Add this tag to the tags list of the manifest before building.
--remove-tag=TAG
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.
--install-deps-from=REMOTE
Install/update build required dependencies from the specified
remote.
--install-deps-only
Stop after downloading dependencies.
--install
When the build is finished, install the result locally.
--user
Install the dependencies in a per-user installation.
--system
Install the dependencies in the default system-wide installation.
--installation=NAME
Install the dependencies in a system-wide installation specified by
NAME among those defined in /etc/flatpak/installations.d/. Using
--installation=default is equivalent to using --system.
CACHING
flatpak-builder caches sources and partial build results in the state
directory (defaulting to the .flatpak-builder subdirectory of the
current directory). If you use --keep-build-dirs, build directories for
each module are also stored here.
It is safe to remove the state directory. This will force a full build
the next time you build.
EXAMPLES
$ flatpak-builder my-app-dir manifest.json
Example manifest file:
{
"id": "org.test.TestApp",
"runtime": "org.freedesktop.Platform",
"runtime-version": "1.2",
"sdk": "org.freedesktop.Sdk",
"command": "test",
"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"
}
]
}
]
}
SEE ALSO
flatpak(1), flatpak-manifest(5), flatpak-build-init(1), flatpak-
build(1), flatpak-build-finish(1), flatpak-build-export(1)
flatpak FLATPAK-BUILDER(1)
Generated by dwww version 1.15 on Fri Jun 21 11:10:40 CEST 2024.