'\" t .\" Title: flatpak-builder .\" Author: Alexander Larsson .\" Generator: DocBook XSL Stylesheets v1.79.1 .\" Date: 04/14/2021 .\" Manual: flatpak builder .\" Source: flatpak .\" Language: English .\" .TH "FLATPAK\-BUILDER" "1" "" "flatpak" "flatpak builder" .\" ----------------------------------------------------------------- .\" * Define some portability stuff .\" ----------------------------------------------------------------- .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .\" http://bugs.debian.org/507673 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" ----------------------------------------------------------------- .\" * set default formatting .\" ----------------------------------------------------------------- .\" disable hyphenation .nh .\" disable justification (adjust text to left margin only) .ad l .\" ----------------------------------------------------------------- .\" * MAIN CONTENT STARTS HERE * .\" ----------------------------------------------------------------- .SH "NAME" flatpak-builder \- Help build application dependencies .SH "SYNOPSIS" .HP \w'\fBflatpak\-builder\fR\ 'u \fBflatpak\-builder\fR [OPTION...] DIRECTORY MANIFEST .HP \w'\fBflatpak\-builder\fR\ 'u \fBflatpak\-builder\fR \-\-run [OPTION...] DIRECTORY MANIFEST COMMAND .HP \w'\fBflatpak\-builder\fR\ 'u \fBflatpak\-builder\fR \-\-show\-deps [OPTION...] MANIFEST .HP \w'\fBflatpak\-builder\fR\ 'u \fBflatpak\-builder\fR \-\-show\-manifest [OPTION...] MANIFEST .SH "DESCRIPTION" .PP \fBflatpak\-builder\fR is a wrapper around the \fBflatpak build\fR command that automates the building of applications and their dependencies\&. It is one option you can use to build applications\&. .PP The goal of \fBflatpak\-builder\fR 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 \fB\&./configure && make && make install\fR 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\&. .PP An invocation of \fBflatpak\-builder\fR proceeds in these stages, each being specified in detail in json format in MANIFEST: .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} Download all sources .RE .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} Initialize the application directory with \fBflatpak build\-init\fR .RE .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} Build and install each module with \fBflatpak build\fR .RE .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} Clean up the final build tree by removing unwanted files and e\&.g\&. stripping binaries .RE .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} Finish the application directory with \fBflatpak build\-finish\fR .RE .sp After this you will end up with a build of the application in DIRECTORY, which you can export to a repository with the \fBflatpak build\-export\fR command\&. If you use the \fB\-\-repo\fR 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 \*(Aqresolved\*(Aq, i\&.e\&. git branch names are replaced by the actual commit IDs that were used in the build\&. .PP 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\&. .PP When building a flatpak to be published to the internet, \fB\-\-collection\-id=COLLECTION\-ID\fR 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\&. .SH "MANIFEST" .PP The manifest file is a json or yaml file whose format is described in detail in its own manual page\&. .SH "OPTIONS" .PP The following options are understood: .PP \fB\-h\fR, \fB\-\-help\fR .RS 4 Show help options and exit\&. .RE .PP \fB\-v\fR, \fB\-\-verbose\fR .RS 4 Print debug information during command processing\&. .RE .PP \fB\-\-version\fR .RS 4 Print version information and exit\&. .RE .PP \fB\-\-arch=ARCH\fR .RS 4 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\&. .RE .PP \fB\-\-default\-branch=\fR\fB\fIBRANCH\fR\fR .RS 4 Set the default branch to \fIBRANCH\fR\&. This is used if the manifest does not specify a branch\&. The default is master\&. .RE .PP \fB\-\-disable\-cache\fR .RS 4 Don\*(Aqt look at the existing cache for a previous build, instead always rebuild modules\&. .RE .PP \fB\-\-disable\-rofiles\-fuse\fR .RS 4 Disable the use of rofiles\-fuse to optimize the cache use via hardlink checkouts\&. .RE .PP \fB\-\-disable\-download\fR .RS 4 Don\*(Aqt 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\&. .RE .PP \fB\-\-disable\-updates\fR .RS 4 Download missing sources, but don\*(Aqt 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\&. .RE .PP \fB\-\-disable\-tests\fR .RS 4 Don\*(Aqt run any of the tests\&. .RE .PP \fB\-\-run\fR .RS 4 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\&. .sp Only the \fB\-\-arch=\fR\fIARCH\fR, \fB\-\-ccache\fR and \fB\-\-verbose\fR options can be combined with this option\&. .RE .PP \fB\-\-build\-shell=MODULENAME\fR .RS 4 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\&. .RE .PP \fB\-\-show\-deps\fR .RS 4 List all the (local) files that the manifest depends on\&. .sp Only the \fB\-\-verbose\fR option can be combined with this option\&. .RE .PP \fB\-\-show\-manifest\fR .RS 4 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)\&. .sp Only the \fB\-\-verbose\fR option can be combined with this option\&. .RE .PP \fB\-\-download\-only\fR .RS 4 Exit successfully after downloading the required sources\&. .RE .PP \fB\-\-bundle\-sources\fR .RS 4 Create an additional runtime with the source code for this module\&. It will be named \fIapp\-id\fR\&.Sources, for example org\&.gnome\&.Maps\&.Sources\&. .RE .PP \fB\-\-build\-only\fR .RS 4 Don\*(Aqt do the cleanup and finish stages, which is useful if you want to build more things into the app\&. .RE .PP \fB\-\-finish\-only\fR .RS 4 Only do the cleanup, finish and export stages, picking up where a \-\-build\-only command left off\&. .RE .PP \fB\-\-export\-only\fR .RS 4 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\&. .RE .PP \fB\-\-require\-changes\fR .RS 4 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\&. .RE .PP \fB\-\-state\-dir=PATH\fR .RS 4 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\&. .RE .PP \fB\-\-keep\-build\-dirs\fR .RS 4 Don\*(Aqt 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")\&. .RE .PP \fB\-\-delete\-build\-dirs\fR .RS 4 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\&. .RE .PP \fB\-\-ccache\fR .RS 4 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\&. .RE .PP \fB\-\-stop\-at=MODULENAME\fR .RS 4 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\&. .RE .PP \fB\-\-repo=DIR\fR .RS 4 After the build finishes, run \fBflatpak build\-export\fR to export the result to the repository DIR\&. If DIR exists, it must be an OSTree repository; otherwise a new one will be created\&. .RE .PP \fB\-s\fR, \fB\-\-subject=SUBJECT\fR .RS 4 One line subject for the commit message\&. Used when exporting the build results\&. .RE .PP \fB\-b\fR, \fB\-\-body=BODY\fR .RS 4 Full description for the commit message\&. Used when exporting the build results\&. .RE .PP \fB\-\-collection\-id=COLLECTION\-ID\fR .RS 4 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\&. .RE .PP \fB\-\-token\-type=VAL\fR .RS 4 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 \fBtoken\-type\fR property set in the manifest takes precedence over this option\&. Used when exporting the build results\&. .RE .PP \fB\-\-gpg\-sign=KEYID\fR .RS 4 Sign the commit with this GPG key\&. Used when exporting the build results\&. This option can be used multiple times\&. .RE .PP \fB\-\-gpg\-homedir=PATH\fR .RS 4 GPG Homedir to use when looking for keyrings\&. Used when exporting the build results\&. .RE .PP \fB\-\-jobs=JOBS\fR .RS 4 Limit the number of parallel jobs during the build\&. The default is the number of CPUs on the machine\&. .RE .PP \fB\-\-force\-clean\fR .RS 4 Erase the previous contents of DIRECTORY if it is not empty\&. .RE .PP \fB\-\-sandbox\fR .RS 4 Disable the possibility to specify build\-args that are passed to flatpak build\&. This means the build process can\*(Aqt break out of its sandbox, and is useful when building less trusted software\&. .RE .PP \fB\-\-allow\-missing\-runtimes\fR .RS 4 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\&. .RE .PP \fB\-\-rebuild\-on\-sdk\-change\fR .RS 4 Record the exact version of the sdk in the cache, and rebuild everything if it changes\&. This is useful if you\*(Aqre building against an API\-unstable runtime, like a nightly build\&. .RE .PP \fB\-\-skip\-if\-unchanged\fR .RS 4 If the json is unchanged since the last build of this filename, then do nothing, and return exit code 42\&. .RE .PP \fB\-\-mirror\-screenshots\-url=URL\fR .RS 4 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\&. .RE .PP \fB\-\-extra\-sources=SOURCE\-DIR\fR .RS 4 When downloading sources (archives, files, git, bzr, svn), look in this directory for pre\-existing copies and use them instead of downloading\&. .RE .PP \fB\-\-extra\-sources\-url=URL\fR .RS 4 When downloading sources (archives, files, git, bzr, svn), look at this url for mirrored downloads before downloading from the original url\&. .RE .PP \fB\-\-from\-git=GIT\fR .RS 4 Look for the manifest in the given git repository\&. If this option is given, MANIFEST is interpreted as a relative path inside the repository\&. .RE .PP \fB\-\-from\-git\-branch=BRANCH\fR .RS 4 The branch to use with \-\-from\-git\&. .RE .PP \fB\-\-no\-shallow\-clone\fR .RS 4 Don\*(Aqt use shallow clones when mirroring git repos\&. .RE .PP \fB\-\-add\-tag=TAG\fR .RS 4 Add this tag to the tags list of the manifest before building\&. .RE .PP \fB\-\-remove\-tag=TAG\fR .RS 4 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\&. .RE .PP \fB\-\-install\-deps\-from=REMOTE\fR .RS 4 Install/update build required dependencies from the specified remote\&. .RE .PP \fB\-\-install\-deps\-only\fR .RS 4 Stop after downloading dependencies\&. .RE .PP \fB\-\-install\fR .RS 4 When the build is finished, install the result locally\&. .RE .PP \fB\-\-user\fR .RS 4 Install the dependencies in a per\-user installation\&. .RE .PP \fB\-\-system\fR .RS 4 Install the dependencies in the default system\-wide installation\&. .RE .PP \fB\-\-installation=NAME\fR .RS 4 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\&. .RE .SH "CACHING" .PP 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 \fB\-\-keep\-build\-dirs\fR, build directories for each module are also stored here\&. .PP It is safe to remove the state directory\&. This will force a full build the next time you build\&. .SH "EXAMPLES" .PP \fB$ flatpak\-builder my\-app\-dir manifest\&.json\fR .PP Example manifest file: .sp .if n \{\ .RS 4 .\} .nf { "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" } ] } ] } .fi .if n \{\ .RE .\} .SH "SEE ALSO" .PP \fBflatpak\fR(1), \fBflatpak-manifest\fR(5), \fBflatpak-build-init\fR(1), \fBflatpak-build\fR(1), \fBflatpak-build-finish\fR(1), \fBflatpak-build-export\fR(1)