1FLATPAK-BUILDER(1) flatpak builder FLATPAK-BUILDER(1)
2
6 flatpak-builder - Help build application dependencies
7
9 flatpak-builder [OPTION...] DIRECTORY MANIFEST
10 flatpak-builder --run [OPTION...] DIRECTORY MANIFEST COMMAND
12 flatpak-builder --show-deps [OPTION...] MANIFEST
14 flatpak-builder --show-manifest [OPTION...] MANIFEST
16
18 flatpak-builder is a wrapper around the flatpak build command that
19 automates the building of applications and their dependencies. It is
20 one option you can use to build applications.
21 The goal of flatpak-builder is to push as much knowledge about how to
23 build modules to the individual upstream projects. It does this by
24 assuming that the modules adhere to the Build API specified at
25 https://github.com/cgwalters/build-api. This essentially means that it
26 follows the ./configure && make && make install scheme with an optional
27 autogen script. If the upstream does not adhere to the API you can make
28 it do so by adding patches and extra files.
29 An invocation of flatpak-builder proceeds in these stages, each being
31 specified in detail in json format in MANIFEST:
32 · Download all sources
34 · Initialize the application directory with flatpak build-init
36 · Build and install each module with flatpak build
38 · Clean up the final build tree by removing unwanted files and e.g.
40 stripping binaries
41 · Finish the application directory with flatpak build-finish
43 After this you will end up with a build of the application in
45 DIRECTORY, which you can export to a repository with the flatpak
46 build-export command. If you use the --repo option, flatpak-builder
47 will do the export for you at the end of the build process. When
48 flatpak-builder does the export, it also stores the manifest that was
49 used for the build in /app/manifest.json. The manifest is 'resolved',
50 i.e. git branch names are replaced by the actual commit IDs that were
51 used in the build.
52 At each of the above steps flatpak caches the result, and if you build
54 the same file again, it will start at the first step where something
55 changes. For instance the first version controlled source that had new
56 commits added, or the first module where some changes to the MANIFEST
57 file caused the build environment to change. This makes flatpak-builder
58 very efficient for incremental builds.
59 When building a flatpak to be published to the internet,
61 --collection-id=COLLECTION-ID should be specified as a globally unique
62 reverse DNS value to identify the collection of flatpaks this will be
63 added to. Setting a globally unique collection ID allows the apps in
64 the repository to be shared over peer to peer systems without needing
65 further configuration.
66
68 The manifest file is a json or yaml file whose format is described in
69 detail in its own manual page.
70
72 The following options are understood:
73 -h, --help
75 Show help options and exit.
76 -v, --verbose
78 Print debug information during command processing.
79 --version
81 Print version information and exit.
82 --arch=ARCH
84 Specify the machine architecture to build for. If no architecture
85 is specified, the host architecture will be automatically detected.
86 Only host compatible architectures can be specified.
87 --default-branch=BRANCH
89 Set the default branch to BRANCH. This is used if the manifest does
90 not specify a branch. The default is master.
91 --disable-cache
93 Don't look at the existing cache for a previous build, instead
94 always rebuild modules.
95 --disable-rofiles-fuse
97 Disable the use of rofiles-fuse to optimize the cache use via
98 hardlink checkouts.
99 --disable-download
101 Don't download any sources. This only works if some version of all
102 sources are downloaded already. This is useful if you want to
103 guarantee that no network i/o is done. However, the build will fail
104 if some source is not locally available.
105 --disable-updates
107 Download missing sources, but don't update local mirrors of version
108 control repos. This is useful to rebuild things but without
109 updating git, bzr or svn repositories from the remote repository.
110 --disable-tests
112 Don't run any of the tests.
113 --run
115 Run a command in a sandbox based on the build dir. This starts
116 flatpak build, with some extra arguments to give the same
117 environment as the build, and the same permissions the final app
118 will have (except filesystem permissions). The command to run must
119 be the last argument passed to flatpak-builder, after the directory
120 and the manifest.
121 Only the --arch=ARCH, --ccache and --verbose options can be
123 combined with this option.
124 --build-shell=MODULENAME
126 Extract and prepare the sources for the named module, and then
127 start a shell in a sandbox identical to the one flatpak-builder
128 would use for building the module. This is useful to debug a
129 module.
130 --show-deps
132 List all the (local) files that the manifest depends on.
133 Only the --verbose option can be combined with this option.
135 --show-manifest
137 Loads the manifest, including any included files and prints it in a
138 canonical json format. This is useful for tools that want to handle
139 manifest files to avoid having to support both yaml and json, as
140 well as some non-standard json handling that is supported (for
141 example comments and multiline strings).
142 Only the --verbose option can be combined with this option.
144 --download-only
146 Exit successfully after downloading the required sources.
147 --bundle-sources
149 Create an additional runtime with the source code for this module.
150 It will be named app-id.Sources, for example
151 org.gnome.Maps.Sources.
152 --build-only
154 Don't do the cleanup and finish stages, which is useful if you want
155 to build more things into the app.
156 --finish-only
158 Only do the cleanup, finish and export stages, picking up where a
159 --build-only command left off.
160 --export-only
162 Only do the export stages, picking up the build result from a
163 previous build. This can be used to split the build and
164 export/signature into two calls by leaving out --repo in the first
165 call.
166 --require-changes
168 Do nothing, leaving a non-existent DIRECTORY if nothing changes
169 since last cached build. If this is not specified, the latest
170 version from the cache will be put into DIRECTORY.
171 --state-dir=PATH
173 Use this directory for storing state (downloads, build dirs, build
174 cache, etc) rather than .flatpak-builder. This can be an absolute
175 or relative path, but must be on the same filesystem as the
176 specified target DIRECTORY.
177 --keep-build-dirs
179 Don't remove the sources and build after having built and installed
180 each module. This also creates a symlink to the build directory
181 with a stable name ("build-modulename").
182 --delete-build-dirs
184 Always remove the sources and build after having built each module,
185 even if the build failed. The default is to keep failed build
186 directories but remove successful ones. This is useful in e.g.
187 automatic build systems.
188 --ccache
190 Enable use of ccache in the build (needs ccache in the sdk). The
191 default ccache folder can be overridden by setting the environment
192 variable CCACHE_DIR.
193 --stop-at=MODULENAME
195 Stop at the specified module, ignoring it and all the following
196 ones in both the "download" and "build" phases. This is useful for
197 debugging and development. For instance, you can build all the
198 dependencies, but stop at the main application so that you can then
199 do a build from a pre-existing checkout. Implies --build-only.
200 --repo=DIR
202 When build is done, run export the result to this repository.
203 -s, --subject=SUBJECT
205 One line subject for the commit message. Used when exporting the
206 build results.
207 -b, --body=BODY
209 Full description for the commit message. Used when exporting the
210 build results.
211 --collection-id=COLLECTION-ID
213 Set as the collection ID of the repository. Setting a globally
214 unique collection ID allows the apps in the repository to be shared
215 over peer to peer systems without needing further configuration. If
216 building in an existing repository, the collection ID must match
217 the existing configured collection ID for that repository.
218 --gpg-sign=KEYID
220 Sign the commit with this GPG key. Used when exporting the build
221 results. This option can be used multiple times.
222 --gpg-homedir=PATH
224 GPG Homedir to use when looking for keyrings. Used when exporting
225 the build results.
226 --jobs=JOBS
228 Limit the number of parallel jobs during the build. The default is
229 the number of CPUs on the machine.
230 --force-clean
232 Erase the previous contents of DIRECTORY if it is not empty.
233 --sandbox
235 Disable the possibility to specify build-args that are passed to
236 flatpak build. This means the build process can't break out of its
237 sandbox, and is useful when building less trusted software.
238 --allow-missing-runtimes
240 Do not immediately fail if the sdk or platform runtimes are not
241 installed on this system. Attempting to build any manifest modules
242 will still fail if the sdk is missing, but may be useful for apps
243 that install files without a sandbox build.
244 --rebuild-on-sdk-change
246 Record the exact version of the sdk in the cache, and rebuild
247 everything if it changes. This is useful if you're building against
248 an API-unstable runtime, like a nightly build.
249 --skip-if-unchanged
251 If the json is unchanged since the last build of this filename,
252 then do nothing, and return exit code 42.
253 --mirror-screenshots-url=URL
255 Mirror any screenshots in the appstream and rewrite the appstream
256 xml as if they were on the specified URL. The resulting files will
257 be stored in the "screenshots" subdirectory in the app directory
258 and needs to be copied to the specified URL for the appdata to
259 work.
260 --extra-sources=SOURCE-DIR
262 When downloading sources (archives, files, git, bzr, svn), look in
263 this directory for pre-existing copies and use them instead of
264 downloading.
265 --extra-sources-url=URL
267 When downloading sources (archives, files, git, bzr, svn), look at
268 this url for mirrored downloads before downloading from the
269 original url.
270 --from-git=GIT
272 Look for the manifest in the given git repository. If this option
273 is given, MANIFEST is interpreted as a relative path inside the
274 repository.
275 --from-git-branch=BRANCH
277 The branch to use with --from-git.
278 --no-shallow-clone
280 Don't use shallow clones when mirroring git repos.
281 --add-tag=TAG
283 Add this tag to the tags list of the manifest before building.
284 --remove-tag=TAG
286 Remove this tag to the tags list of the manifest before building.
287 The remove happen before processing the --add-tag option, so if
288 both are specified, then --app-tag wins.
289 --install-deps-from=REMOTE
291 Install/update build required dependencies from the specified
292 remote.
293 --install-deps-only
295 Stop after downloading dependencies.
296 --install
298 When the build is finished, install the result locally.
299 --user
301 Install the dependencies in a per-user installation.
302 --system
304 Install the dependencies in the default system-wide installation.
305 --installation=NAME
307 Install the dependencies in a system-wide installation specified by
308 NAME among those defined in /etc/flatpak/installations.d/. Using
309 --installation=default is equivalent to using --system.
310
312 flatpak-builder caches sources and partial build results in the state
313 directory (defaulting to the .flatpak-builder subdirectory of the
314 current directory). If you use --keep-build-dirs, build directories for
315 each module are also stored here.
316 It is safe to remove the state directory. This will force a full build
318 the next time you build.
319
321 $ flatpak-builder my-app-dir manifest.json
322 Example manifest file:
324 {
326 "id": "org.test.TestApp",
327 "runtime": "org.freedesktop.Platform",
328 "runtime-version": "1.2",
329 "sdk": "org.freedesktop.Sdk",
330 "command": "test",
331 "cleanup": [ "/include", "*.la" ],
332 "build-options" : {
333 "cflags": "-O2 -g",
334 "cxxflags": "-O2 -g",
335 "env": {
336 "V": "1"
337 },
338 "arch": {
339 "x86_64": {
340 "cflags": "-O3 -g",
341 }
342 }
343 },
344 "modules": [
345 {
346 "name": "pygobject",
347 "config-opts": [ "--disable-introspection" ],
348 "sources": [
349 {
350 "type": "archive",
351 "url": "http://ftp.gnome.org/pub/GNOME/sources/pygobject/2.28/pygobject-2.28.6.tar.xz",
352 "sha256": "fb8a1d4f665130a125011659bd347c7339c944232163dbb9a34fd0686577adb8"
353 },
354 {
355 "type": "patch",
356 "path": "required-pygobject-fix.patch"
357 },
358 {
359 "type": "file",
360 "path": "pygobject-extra-file",
361 "dest-filename": "extra-file"
362 }
363 ]
364 },
365 {
366 "name": "babl",
367 "build-options" : { "cxxflags": "-O2 -g -std=c++11" },
368 "cleanup": [ "/bin" ],
369 "sources": [
370 {
371 "type": "git",
372 "url": "https://gitlab.gnome.org/GNOME/babl.git"
373 }
374 ]
375 },
376 {
377 "name": "testapp",
378 "sources": [
379 {
380 "type": "bzr",
381 "url": "lp:testapp"
382 }
383 ]
384 }
385 ]
386 }
387
389 flatpak(1), flatpak-manifest(5), flatpak-build-init(1), flatpak-
390 build(1), flatpak-build-finish(1), flatpak-build-export(1)
391flatpak FLATPAK-BUILDER(1)