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 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 -s, --subject=SUBJECT
207 One line subject for the commit message. Used when exporting the
208 build results.
209 -b, --body=BODY
211 Full description for the commit message. Used when exporting the
212 build results.
213 --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 --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 --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 --gpg-homedir=PATH
233 GPG Homedir to use when looking for keyrings. Used when exporting
234 the build results.
235 --jobs=JOBS
237 Limit the number of parallel jobs during the build. The default is
238 the number of CPUs on the machine.
239 --force-clean
241 Erase the previous contents of DIRECTORY if it is not empty.
242 --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 --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 --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 --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 --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 --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 --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 --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 --from-git-branch=BRANCH
286 The branch to use with --from-git.
287 --no-shallow-clone
289 Don't use shallow clones when mirroring git repos.
290 --add-tag=TAG
292 Add this tag to the tags list of the manifest before building.
293 --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 --install-deps-from=REMOTE
300 Install/update build required dependencies from the specified
301 remote.
302 --install-deps-only
304 Stop after downloading dependencies.
305 --install
307 When the build is finished, install the result locally.
308 --user
310 Install the dependencies in a per-user installation.
311 --system
313 Install the dependencies in the default system-wide installation.
314 --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
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 It is safe to remove the state directory. This will force a full build
327 the next time you build.
328
330 $ flatpak-builder my-app-dir manifest.json
331 Example manifest file:
333 {
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
398 flatpak(1), flatpak-manifest(5), flatpak-build-init(1), flatpak-
399 build(1), flatpak-build-finish(1), flatpak-build-export(1)
400flatpak FLATPAK-BUILDER(1)