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

DESCRIPTION

16       flatpak-builder is a wrapper around the flatpak build command that
17       automates the building of applications and their dependencies. It is
18       one option you can use to build applications.
19
20       The goal of flatpak-builder is to push as much knowledge about how to
21       build modules to the individual upstream projects. It does this by
22       assuming that the modules adhere to the Build API specified at
23       https://github.com/cgwalters/build-api. This essentially means that it
24       follows the ./configure && make && make install scheme with an optional
25       autogen script. If the upstream does not adhere to the API you can make
26       it do so by adding patches and extra files.
27
28       An invocation of flatpak-builder proceeds in these stages, each being
29       specified in detail in json format in MANIFEST:
30
31       ·   Download all sources
32
33       ·   Initialize the application directory with flatpak build-init
34
35       ·   Build and install each module with flatpak build
36
37       ·   Clean up the final build tree by removing unwanted files and e.g.
38           stripping binaries
39
40       ·   Finish the application directory with flatpak build-finish
41
42       After this you will end up with a build of the application in
43       DIRECTORY, which you can export to a repository with the flatpak
44       build-export command. If you use the --repo option, flatpak-builder
45       will do the export for you at the end of the build process. When
46       flatpak-builder does the export, it also stores the manifest that was
47       used for the build in /app/manifest.json. The manifest is 'resolved',
48       i.e. git branch names are replaced by the actual commit IDs that were
49       used in the build.
50
51       At each of the above steps flatpak caches the result, and if you build
52       the same file again, it will start at the first step where something
53       changes. For instance the first version controlled source that had new
54       commits added, or the first module where some changes to the MANIFEST
55       file caused the build environment to change. This makes flatpak-builder
56       very efficient for incremental builds.
57
58       When building a flatpak to be published to the internet,
59       --collection-id=COLLECTION-ID should be specified as a globally unique
60       reverse DNS value to identify the collection of flatpaks this will be
61       added to. Setting a globally unique collection ID allows the apps in
62       the repository to be shared over peer to peer systems without needing
63       further configuration.
64

MANIFEST

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

OPTIONS

70       The following options are understood:
71
72       -h, --help
73           Show help options and exit.
74
75       -v, --verbose
76           Print debug information during command processing.
77
78       --version
79           Print version information and exit.
80
81       --arch=ARCH
82           Specify the machine architecture to build for. If no architecture
83           is specified, the host architecture will be automatically detected.
84           Only host compatible architectures can be specified.
85
86       --default-branch=BRANCH
87           Set the default branch to BRANCH. This is used if the manifest does
88           not specify a branch. The default is master.
89
90       --disable-cache
91           Don't look at the existing cache for a previous build, instead
92           always rebuild modules.
93
94       --disable-rofiles-fuse
95           Disable the use of rofiles-fuse to optimize the cache use via
96           hardlink checkouts.
97
98       --disable-download
99           Don't download any sources. This only works if some version of all
100           sources are downloaded already. This is useful if you want to
101           guarantee that no network i/o is done. However, the build will fail
102           if some source is not locally available.
103
104       --disable-updates
105           Download missing sources, but don't update local mirrors of version
106           control repos. This is useful to rebuild things but without
107           updating git, bzr or svn repositories from the remote repository.
108
109       --disable-tests
110           Don't run any of the tests.
111
112       --run
113           Run a command in a sandbox based on the build dir. This starts
114           flatpak build, with some extra arguments to give the same
115           environment as the build, and the same permissions the final app
116           will have. The command to run must be the last argument passed to
117           flatpak-builder, after the directory and the manifest.
118
119           Only the --arch=ARCH, --ccache and --verbose options can be
120           combined with this option.
121
122       --build-shell=MODULENAME
123           Extract and prepare the sources for the named module, and then
124           start a shell in a sandbox identical to the one flatpak-builder
125           would use for building the module. This is useful to debug a
126           module.
127
128       --show-deps
129           List all the (local) files that the manifest depends on.
130
131           Only the --verbose option can be combined with this option.
132
133       --download-only
134           Exit successfully after downloading the required sources.
135
136       --bundle-sources
137           Create an additional runtime with the source code for this module.
138           It will be named app-id.Sources, for example
139           org.gnome.Maps.Sources.
140
141       --build-only
142           Don't do the cleanup and finish stages, which is useful if you want
143           to build more things into the app.
144
145       --finish-only
146           Only do the cleanup, finish and export stages, picking up where a
147           --build-only command left off.
148
149       --export-only
150           Only do the export stages, picking up the build result from a
151           previous build. This can be used to split the build and
152           export/signature into two calls by leaving out --repo in the first
153           call.
154
155       --require-changes
156           Do nothing, leaving a non-existent DIRECTORY if nothing changes
157           since last cached build. If this is not specified, the latest
158           version from the cache will be put into DIRECTORY.
159
160       --state-dir=PATH
161           Use this directory for storing state (downloads, build dirs, build
162           cache, etc) rather than .flatpak-builder. This can be an absolute
163           or relative path, but must be on the same filesystem as the
164           specified target DIRECTORY.
165
166       --keep-build-dirs
167           Don't remove the sources and build after having built and installed
168           each module. This also creates a symlink to the build directory
169           with a stable name ("build-modulename").
170
171       --delete-build-dirs
172           Always remove the sources and build after having built each module,
173           even if the build failed. The default is to keep failed build
174           directories but remove successful ones. This is useful in e.g.
175           automatic build systems.
176
177       --ccache
178           Enable use of ccache in the build (needs ccache in the sdk)
179
180       --stop-at=MODULENAME
181           Stop at the specified module, ignoring it and all the following
182           ones in both the "download" and "build" phases. This is useful for
183           debugging and development. For instance, you can build all the
184           dependencies, but stop at the main application so that you can then
185           do a build from a pre-existing checkout. Implies --build-only.
186
187       --repo=DIR
188           When build is done, run export the result to this repository.
189
190       -s, --subject=SUBJECT
191           One line subject for the commit message. Used when exporting the
192           build results.
193
194       -b, --body=BODY
195           Full description for the commit message. Used when exporting the
196           build results.
197
198       --collection-id=COLLECTION-ID
199           Set as the collection ID of the repository. Setting a globally
200           unique collection ID allows the apps in the repository to be shared
201           over peer to peer systems without needing further configuration. If
202           building in an existing repository, the collection ID must match
203           the existing configured collection ID for that repository.
204
205       --gpg-sign=KEYID
206           Sign the commit with this GPG key. Used when exporting the build
207           results. This option can be used multiple times.
208
209       --gpg-homedir=PATH
210           GPG Homedir to use when looking for keyrings. Used when exporting
211           the build results.
212
213       --jobs=JOBS
214           Limit the number of parallel jobs during the build. The default is
215           the number of CPUs on the machine.
216
217       --force-clean
218           Erase the previous contents of DIRECTORY if it is not empty.
219
220       --sandbox
221           Disable the possibility to specify build-args that are passed to
222           flatpak build. This means the build process can't break out of its
223           sandbox, and is useful when building less trusted software.
224
225       --allow-missing-runtimes
226           Do not immediately fail if the sdk or platform runtimes are not
227           installed on this system. Attempting to build any manifest modules
228           will still fail if the sdk is missing, but may be useful for apps
229           that install files without a sandbox build.
230
231       --rebuild-on-sdk-change
232           Record the exact version of the sdk in the cache, and rebuild
233           everything if it changes. This is useful if you're building against
234           an API-unstable runtime, like a nightly build.
235
236       --skip-if-unchanged
237           If the json is unchanged since the last build of this filename,
238           then do nothing, and return exit code 42.
239
240       --mirror-screenshots-url=URL
241           Mirror any screenshots in the appstream and rewrite the appstream
242           xml as if they were on the specified URL. The resulting files will
243           be stored in the "screenshots" subdirectory in the app directory
244           and needs to be copied to the specified URL for the appdata to
245           work.
246
247       --extra-sources=SOURCE-DIR
248           When downloading sources (archives, files, git, bzr, svn), look in
249           this directory for pre-existing copies and use them instead of
250           downloading.
251
252       --extra-sources-url=URL
253           When downloading sources (archives, files, git, bzr, svn), look at
254           this url for mirrored downloads before downloading from the
255           original url.
256
257       --from-git=GIT
258           Look for the manifest in the given git repository. If this option
259           is given, MANIFEST is interpreted as a relative path inside the
260           repository.
261
262       --from-git-branch=BRANCH
263           The branch to use with --from-git.
264
265       --no-shallow-clone
266           Don't use shallow clones when mirroring git repos.
267
268       --add-tag=TAG
269           Add this tag to the tags list of the manifest before building.
270
271       --remove-tag=TAG
272           Remove this tag to the tags list of the manifest before building.
273           The remove happen before processing the --add-tag option, so if
274           both are specified, then --app-tag wins.
275
276       --install-deps-from=REMOTE
277           Install/update build required dependencies from the specified
278           remote.
279
280       --install-deps-only
281           Stop after downloading dependencies.
282
283       --install
284           When the build is finished, install the result locally.
285
286       --user
287           Install the dependencies in a per-user installation.
288
289       --system
290           Install the dependencies in the default system-wide installation.
291
292       --installation=NAME
293           Install the dependencies in a system-wide installation specified by
294           NAME among those defined in /etc/flatpak/installations.d/. Using
295           --installation=default is equivalent to using --system.
296

CACHING

298       flatpak-builder caches sources and partial build results in the state
299       directory (defaulting to the .flatpak-builder subdirectory of the
300       current directory). If you use --keep-build-dirs, build directories for
301       each module are also stored here.
302
303       It is safe to remove the state directory. This will force a full build
304       the next time you build.
305

EXAMPLES

307       $ flatpak-builder my-app-dir manifest.json
308
309       Example manifest file:
310
311           {
312               "id": "org.test.TestApp",
313               "runtime": "org.freedesktop.Platform",
314               "runtime-version": "1.2",
315               "sdk": "org.freedesktop.Sdk",
316               "command": "test",
317               "cleanup": [ "/include", "*.la" ],
318               "build-options" : {
319                   "cflags": "-O2 -g",
320                   "cxxflags": "-O2 -g",
321                   "env": {
322                       "V": "1"
323                   },
324                   "arch": {
325                       "x86_64": {
326                           "cflags": "-O3 -g",
327                       }
328                   }
329               },
330               "modules": [
331                   {
332                       "name": "pygobject",
333                       "config-opts": [ "--disable-introspection" ],
334                       "sources": [
335                           {
336                               "type": "archive",
337                               "url": "http://ftp.gnome.org/pub/GNOME/sources/pygobject/2.28/pygobject-2.28.6.tar.xz",
338                               "sha256": "fb8a1d4f665130a125011659bd347c7339c944232163dbb9a34fd0686577adb8"
339                           },
340                           {
341                               "type": "patch",
342                               "path": "required-pygobject-fix.patch"
343                           },
344                           {
345                               "type": "file",
346                               "path": "pygobject-extra-file",
347                               "dest-filename": "extra-file"
348                           }
349                       ]
350                   },
351                   {
352                       "name": "babl",
353                       "build-options" : { "cxxflags": "-O2 -g -std=c++11" },
354                       "cleanup": [ "/bin" ],
355                       "sources": [
356                           {
357                               "type": "git",
358                               "url": "https://gitlab.gnome.org/GNOME/babl.git"
359                           }
360                       ]
361                   },
362                   {
363                       "name": "testapp",
364                       "sources": [
365                           {
366                               "type": "bzr",
367                               "url": "lp:testapp"
368                           }
369                       ]
370                   }
371               ]
372           }
373

SEE ALSO

375       flatpak(1), flatpak-manifest(5), flatpak-build-init(1), flatpak-
376       build(1), flatpak-build-finish(1), flatpak-build-export(1)
377
378
379
380flatpak                                                     FLATPAK-BUILDER(1)
Impressum