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
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 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 An invocation of flatpak-builder proceeds in these stages, each being
29 specified in detail in json format in MANIFEST:
30 · Download all sources
32 · Initialize the application directory with flatpak build-init
34 · Build and install each module with flatpak build
36 · Clean up the final build tree by removing unwanted files and e.g.
38 stripping binaries
39 · Finish the application directory with flatpak build-finish
41 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 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 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
66 The manifest file is a json or yaml file whose format is described in
67 detail in its own manual page.
68
70 The following options are understood:
71 -h, --help
73 Show help options and exit.
74 -v, --verbose
76 Print debug information during command processing.
77 --version
79 Print version information and exit.
80 --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 --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 --disable-cache
91 Don't look at the existing cache for a previous build, instead
92 always rebuild modules.
93 --disable-rofiles-fuse
95 Disable the use of rofiles-fuse to optimize the cache use via
96 hardlink checkouts.
97 --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 --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 --disable-tests
110 Don't run any of the tests.
111 --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 Only the --arch=ARCH, --ccache and --verbose options can be
120 combined with this option.
121 --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 --show-deps
129 List all the (local) files that the manifest depends on.
130 Only the --verbose option can be combined with this option.
132 --download-only
134 Exit successfully after downloading the required sources.
135 --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 --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 --finish-only
146 Only do the cleanup, finish and export stages, picking up where a
147 --build-only command left off.
148 --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 --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 --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 --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 --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 --ccache
178 Enable use of ccache in the build (needs ccache in the sdk)
179 --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 --repo=DIR
188 When build is done, run export the result to this repository.
189 -s, --subject=SUBJECT
191 One line subject for the commit message. Used when exporting the
192 build results.
193 -b, --body=BODY
195 Full description for the commit message. Used when exporting the
196 build results.
197 --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 --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 --gpg-homedir=PATH
210 GPG Homedir to use when looking for keyrings. Used when exporting
211 the build results.
212 --jobs=JOBS
214 Limit the number of parallel jobs during the build. The default is
215 the number of CPUs on the machine.
216 --force-clean
218 Erase the previous contents of DIRECTORY if it is not empty.
219 --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 --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 --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 --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 --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 --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 --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 --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 --from-git-branch=BRANCH
263 The branch to use with --from-git.
264 --no-shallow-clone
266 Don't use shallow clones when mirroring git repos.
267 --add-tag=TAG
269 Add this tag to the tags list of the manifest before building.
270 --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 --install-deps-from=REMOTE
277 Install/update build required dependencies from the specified
278 remote.
279 --install-deps-only
281 Stop after downloading dependencies.
282 --install
284 When the build is finished, install the result locally.
285 --user
287 Install the dependencies in a per-user installation.
288 --system
290 Install the dependencies in the default system-wide installation.
291 --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
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 It is safe to remove the state directory. This will force a full build
304 the next time you build.
305
307 $ flatpak-builder my-app-dir manifest.json
308 Example manifest file:
310 {
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
375 flatpak(1), flatpak-manifest(5), flatpak-build-init(1), flatpak-
376 build(1), flatpak-build-finish(1), flatpak-build-export(1)
377flatpak FLATPAK-BUILDER(1)