1FLATPAK-BUILDER(1)              flatpak builder             FLATPAK-BUILDER(1)
2
3
4

NAME

6       flatpak-builder - Help build application dependencies
7

SYNOPSIS

9       flatpak-builder [OPTION...] DIRECTORY MANIFEST
10
11       flatpak-builder --run [OPTION...] DIRECTORY MANIFEST COMMAND
12
13       flatpak-builder --show-deps [OPTION...] MANIFEST
14
15       flatpak-builder --show-manifest [OPTION...] MANIFEST
16

DESCRIPTION

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
22       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
30       An invocation of flatpak-builder proceeds in these stages, each being
31       specified in detail in json format in MANIFEST:
32
33       •   Download all sources
34
35       •   Initialize the application directory with flatpak build-init
36
37       •   Build and install each module with flatpak build
38
39       •   Clean up the final build tree by removing unwanted files and e.g.
40           stripping binaries
41
42       •   Finish the application directory with flatpak build-finish
43
44       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
53       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
60       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

MANIFEST

68       The manifest file is a json or yaml file whose format is described in
69       detail in its own manual page.
70

OPTIONS

72       The following options are understood:
73
74       -h, --help
75           Show help options and exit.
76
77       -v, --verbose
78           Print debug information during command processing.
79
80       --version
81           Print version information and exit.
82
83       --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
88       --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
92       --disable-cache
93           Don't look at the existing cache for a previous build, instead
94           always rebuild modules.
95
96       --disable-rofiles-fuse
97           Disable the use of rofiles-fuse to optimize the cache use via
98           hardlink checkouts.
99
100       --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
106       --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
111       --disable-tests
112           Don't run any of the tests.
113
114       --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
122           Only the --arch=ARCH, --ccache and --verbose options can be
123           combined with this option.
124
125       --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
131       --show-deps
132           List all the (local) files that the manifest depends on.
133
134           Only the --verbose option can be combined with this option.
135
136       --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
143           Only the --verbose option can be combined with this option.
144
145       --download-only
146           Exit successfully after downloading the required sources.
147
148       --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
153       --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
157       --finish-only
158           Only do the cleanup, finish and export stages, picking up where a
159           --build-only command left off.
160
161       --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
167       --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
172       --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
178       --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
183       --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
189       --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
194       --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
201       --repo=DIR
202           After the build finishes, run flatpak build-export to export the
203           result to the repository DIR. If DIR exists, it must be an OSTree
204           repository; otherwise a new one will be created.
205
206       -s, --subject=SUBJECT
207           One line subject for the commit message. Used when exporting the
208           build results.
209
210       -b, --body=BODY
211           Full description for the commit message. Used when exporting the
212           build results.
213
214       --collection-id=COLLECTION-ID
215           Set as the collection ID of the repository. Setting a globally
216           unique collection ID allows the apps in the repository to be shared
217           over peer to peer systems without needing further configuration. If
218           building in an existing repository, the collection ID must match
219           the existing configured collection ID for that repository.
220
221       --token-type=VAL
222           Set type of token needed to install this commit. Setting this to a
223           value greater than 0 implies that authentication will be needed to
224           install the flatpak. A token-type property set in the manifest
225           takes precedence over this option. Used when exporting the build
226           results.
227
228       --gpg-sign=KEYID
229           Sign the commit with this GPG key. Used when exporting the build
230           results. This option can be used multiple times.
231
232       --gpg-homedir=PATH
233           GPG Homedir to use when looking for keyrings. Used when exporting
234           the build results.
235
236       --jobs=JOBS
237           Limit the number of parallel jobs during the build. The default is
238           the number of CPUs on the machine.
239
240       --force-clean
241           Erase the previous contents of DIRECTORY if it is not empty.
242
243       --sandbox
244           Disable the possibility to specify build-args that are passed to
245           flatpak build. This means the build process can't break out of its
246           sandbox, and is useful when building less trusted software.
247
248       --allow-missing-runtimes
249           Do not immediately fail if the sdk or platform runtimes are not
250           installed on this system. Attempting to build any manifest modules
251           will still fail if the sdk is missing, but may be useful for apps
252           that install files without a sandbox build.
253
254       --rebuild-on-sdk-change
255           Record the exact version of the sdk in the cache, and rebuild
256           everything if it changes. This is useful if you're building against
257           an API-unstable runtime, like a nightly build.
258
259       --skip-if-unchanged
260           If the json is unchanged since the last build of this filename,
261           then do nothing, and return exit code 42.
262
263       --mirror-screenshots-url=URL
264           Mirror any screenshots in the appstream and rewrite the appstream
265           xml as if they were on the specified URL. The resulting files will
266           be stored in the "screenshots" subdirectory in the app directory
267           and needs to be copied to the specified URL for the appdata to
268           work.
269
270       --extra-sources=SOURCE-DIR
271           When downloading sources (archives, files, git, bzr, svn), look in
272           this directory for pre-existing copies and use them instead of
273           downloading.
274
275       --extra-sources-url=URL
276           When downloading sources (archives, files, git, bzr, svn), look at
277           this url for mirrored downloads before downloading from the
278           original url.
279
280       --from-git=GIT
281           Look for the manifest in the given git repository. If this option
282           is given, MANIFEST is interpreted as a relative path inside the
283           repository.
284
285       --from-git-branch=BRANCH
286           The branch to use with --from-git.
287
288       --no-shallow-clone
289           Don't use shallow clones when mirroring git repos.
290
291       --add-tag=TAG
292           Add this tag to the tags list of the manifest before building.
293
294       --remove-tag=TAG
295           Remove this tag to the tags list of the manifest before building.
296           The remove happen before processing the --add-tag option, so if
297           both are specified, then --app-tag wins.
298
299       --install-deps-from=REMOTE
300           Install/update build required dependencies from the specified
301           remote.
302
303       --install-deps-only
304           Stop after downloading dependencies.
305
306       --install
307           When the build is finished, install the result locally.
308
309       --user
310           Install the dependencies in a per-user installation.
311
312       --system
313           Install the dependencies in the default system-wide installation.
314
315       --installation=NAME
316           Install the dependencies in a system-wide installation specified by
317           NAME among those defined in /etc/flatpak/installations.d/. Using
318           --installation=default is equivalent to using --system.
319

CACHING

321       flatpak-builder caches sources and partial build results in the state
322       directory (defaulting to the .flatpak-builder subdirectory of the
323       current directory). If you use --keep-build-dirs, build directories for
324       each module are also stored here.
325
326       It is safe to remove the state directory. This will force a full build
327       the next time you build.
328

EXAMPLES

330       $ flatpak-builder my-app-dir manifest.json
331
332       Example manifest file:
333
334           {
335               "id": "org.test.TestApp",
336               "runtime": "org.freedesktop.Platform",
337               "runtime-version": "1.2",
338               "sdk": "org.freedesktop.Sdk",
339               "command": "test",
340               "cleanup": [ "/include", "*.la" ],
341               "build-options" : {
342                   "cflags": "-O2 -g",
343                   "cxxflags": "-O2 -g",
344                   "env": {
345                       "V": "1"
346                   },
347                   "arch": {
348                       "x86_64": {
349                           "cflags": "-O3 -g",
350                       }
351                   }
352               },
353               "modules": [
354                   {
355                       "name": "pygobject",
356                       "config-opts": [ "--disable-introspection" ],
357                       "sources": [
358                           {
359                               "type": "archive",
360                               "url": "http://ftp.gnome.org/pub/GNOME/sources/pygobject/2.28/pygobject-2.28.6.tar.xz",
361                               "sha256": "fb8a1d4f665130a125011659bd347c7339c944232163dbb9a34fd0686577adb8"
362                           },
363                           {
364                               "type": "patch",
365                               "path": "required-pygobject-fix.patch"
366                           },
367                           {
368                               "type": "file",
369                               "path": "pygobject-extra-file",
370                               "dest-filename": "extra-file"
371                           }
372                       ]
373                   },
374                   {
375                       "name": "babl",
376                       "build-options" : { "cxxflags": "-O2 -g -std=c++11" },
377                       "cleanup": [ "/bin" ],
378                       "sources": [
379                           {
380                               "type": "git",
381                               "url": "https://gitlab.gnome.org/GNOME/babl.git"
382                           }
383                       ]
384                   },
385                   {
386                       "name": "testapp",
387                       "sources": [
388                           {
389                               "type": "bzr",
390                               "url": "lp:testapp"
391                           }
392                       ]
393                   }
394               ]
395           }
396

SEE ALSO

398       flatpak(1), flatpak-manifest(5), flatpak-build-init(1), flatpak-
399       build(1), flatpak-build-finish(1), flatpak-build-export(1)
400
401
402
403flatpak                                                     FLATPAK-BUILDER(1)
Impressum