1FLATPAK MANIFEST(5) flatpak manifest FLATPAK MANIFEST(5)
2
6 flatpak-manifest - Information for building an application
7
9 Flatpak uses manifest, or recipe, files in a json or yaml format to
10 describe how an application and its bundled dependencies can be built
11 from sources. The manifest gets used by flatpak-builder.
12
14 The top level of the manifest file describes global attributes of the
15 application, how it can be built, and the list of modules that need to
16 be built.
17 Toplevel properties
19 These are the properties that are accepted:
20 id or app-id (string)
22 A string defining the application id.
23 branch (string)
25 The branch to use when exporting the application. If this is unset
26 the defaults come from the default-branch option.
27 This key overrides both the default-branch key, and the
29 --default-branch commandline option. Unless you need a very
30 specific branchname (like for a runtime or an extension) it is
31 recommended to use the default-branch key instead, because you can
32 then override the default using --default-branch when building for
33 instance a test build.
34 default-branch (string)
36 The default branch to use when exporting the application. Defaults
37 to master.
38 This key can be overriden by the --default-branch commandline
40 option.
41 collection-id (string)
43 The collection ID of the repository, defaults to being unset.
44 Setting a globally unique collection ID allows the apps in the
45 repository to be shared over peer to peer systems without needing
46 further configuration. If building in an existing repository, the
47 collection ID must match the existing configured collection ID for
48 that repository.
49 extension-tag (string)
51 If building an extension, the tag for the extension point to use.
52 Since flatpak 0.11.4 a runtime may define multiple locations for
53 the same extension point with the intention that different branches
54 for the extension are mounted at each location. When building an
55 extension it is necessary to know what extension point to install
56 the extension to. This option resolves any ambiguity in which
57 extension point to choose. If not specified, the default choice is
58 to install into either the only location for the extension point or
59 into the location for the untagged extension point. If there are
60 multiple locations for the same extension point defined with
61 different tags then an error will occur.
62 runtime (string)
64 The name of the runtime that the application uses.
65 runtime-version (string)
67 The version of the runtime that the application uses, defaults to
68 master.
69 sdk (string)
71 The name of the development runtime that the application builds
72 with.
73 var (string)
75 Initialize the (otherwise empty) writable /var in the build with a
76 copy of this runtime.
77 metadata (string)
79 Use this file as the base metadata file when finishing.
80 command (string)
82 The filename or path to the main binary of the application. Note
83 that this is really just a single file, not a commandline. If you
84 want to pass arguments, install a shell script wrapper and use that
85 as the command.
86 Also note that the command is used when the application is run via
88 flatpak run, and does not affect what gets executed when the
89 application is run in other ways, e.g. via the desktop file or
90 D-Bus activation.
91 build-runtime (boolean)
93 Build a new runtime instead of an application.
94 build-extension (boolean)
96 Build an extension.
97 separate-locales (boolean)
99 Separate out locale files and translations to an extension runtime.
100 Defaults to true.
101 id-platform (string)
103 When building a runtime sdk, also create a platform based on it
104 with this id.
105 metadata-platform (string)
107 The metadata file to use for the platform we create.
108 writable-sdk (boolean)
110 If true, use a writable copy of the sdk for /usr. Defaults to true
111 if build-runtime is specified.
112 appstream-compose (boolean)
114 Run appstream-compose during cleanup phase. Defaults to true.
115 sdk-extensions (array of strings)
117 Install these extra sdk extensions in /usr.
118 platform-extensions (array of strings)
120 Install these extra sdk extensions when creating the platform.
121 base (string)
123 Start with the files from the specified application. This can be
124 used to create applications that extend another application.
125 base-version (string)
127 Use this specific version of the application specified in base. If
128 unspecified, this uses the value specified in branch
129 base-extensions (array of strings)
131 Install these extra extensions from the base application when
132 initializing the application directory.
133 inherit-extensions (array of strings)
135 Inherit these extra extensions points from the base application or
136 sdk when finishing the build.
137 inherit-sdk-extensions (array of strings)
139 Inherit these extra extensions points from the base application or
140 sdk when finishing the build, but do not inherit them into the
141 platform.
142 tags (array of strings)
144 Add these tags to the metadata file.
145 build-options (object)
147 Object specifying the build environment. See below for details.
148 modules (array of objects or strings)
150 An array of objects specifying the modules to be built in order.
151 String members in the array are interpreted as the name of a
152 separate json or yaml file that contains a module. See below for
153 details.
154 add-extensions (objects)
156 This is a dictionary of extension objects. The key is the name of
157 the extension. See below for details.
158 add-build-extensions (objects)
160 This is a dictionary of extension objects similar to
161 add-extensions. The main difference is that the extensions are
162 added early and are available for use during the build.
163 cleanup (array of strings)
165 An array of file patterns that should be removed at the end.
166 Patterns starting with / are taken to be full pathnames (without
167 the /app prefix), otherwise they just match the basename.
168 cleanup-commands (array of strings)
170 An array of commandlines that are run during the cleanup phase.
171 cleanup-platform (array of strings)
173 Extra files to clean up in the platform.
174 cleanup-platform-commands (array of strings)
176 An array of commandlines that are run during the cleanup phase of
177 the platform.
178 prepare-platform-commands (array of strings)
180 An array of commandlines that are run after importing the base
181 platform, but before applying the new files from the sdk. This is a
182 good place to e.g. delete things from the base that may conflict
183 with the files added in the sdk.
184 finish-args (array of strings)
186 An array of arguments passed to the flatpak build-finish command.
187 rename-desktop-file (string)
189 Any desktop file with this name will be renamed to a name based on
190 id during the cleanup phase.
191 rename-appdata-file (string)
193 Any appdata file with this name will be renamed to a name based on
194 id during the cleanup phase.
195 rename-icon (string)
197 Any icon with this name will be renamed to a name based on id
198 during the cleanup phase. Note that this is the icon name, not the
199 full filenames, so it should not include a filename extension.
200 appdata-license (string)
202 Replace the appdata project_license field with this string. This is
203 useful as the upstream license is typically only about the
204 application itself, whereas the bundled app can contain other
205 licenses too.
206 copy-icon (boolean)
208 If rename-icon is set, keep a copy of the old icon file.
209 desktop-file-name-prefix (string)
211 This string will be prefixed to the Name key in the main
212 application desktop file.
213 desktop-file-name-suffix (string)
215 This string will be suffixed to the Name key in the main
216 application desktop file.
217 Build Options
219 Build options specify the build environment of a module, and can be
220 specified globally as well as per-module. Options can also be specified
221 on a per-architecture basis using the arch property.
222 These are the properties that are accepted:
224 cflags (string)
226 This is set in the environment variable CFLAGS during the build.
227 Multiple specifications of this (in e.g. per-arch area) are
228 concatenated, separated by spaces.
229 cflags-override (boolean)
231 If this is true, clear cflags from previous build options before
232 adding it from these options.
233 cppflags (string)
235 This is set in the environment variable CPPFLAGS during the build.
236 Multiple specifications of this (in e.g. per-arch area) are
237 concatenated, separated by spaces.
238 cppflags-override (boolean)
240 If this is true, clear cppflags from previous build options before
241 adding it from these options.
242 cxxflags (string)
244 This is set in the environment variable CXXFLAGS during the build.
245 Multiple specifications of this (in e.g. per-arch area) are
246 concatenated, separated by spaces.
247 cxxflags-override (boolean)
249 If this is true, clear cxxflags from previous build options before
250 adding it from these options.
251 ldflags (string)
253 This is set in the environment variable LDFLAGS during the build.
254 Multiple specifications of this (in e.g. per-arch area) are
255 concatenated, separated by spaces.
256 ldflags-override (boolean)
258 If this is true, clear ldflags from previous build options before
259 adding it from these options.
260 prefix (string)
262 The build prefix for the modules (defaults to /app for applications
263 and /usr for runtimes).
264 libdir (string)
266 The build libdir for the modules (defaults to /app/lib for
267 applications and /usr/lib for runtimes).
268 append-path (string)
270 This will get appended to PATH in the build environment (with an
271 leading colon if needed).
272 prepend-path (string)
274 This will get prepended to PATH in the build environment (with an
275 trailing colon if needed).
276 append-ld-library-path (string)
278 This will get appended to LD_LIBRARY_PATH in the build environment
279 (with an leading colon if needed).
280 prepend-ld-library-path (string)
282 This will get prepended to LD_LIBRARY_PATH in the build environment
283 (with an trailing colon if needed).
284 append-pkg-config-path (string)
286 This will get appended to PKG_CONFIG_PATH in the build environment
287 (with an leading colon if needed).
288 prepend-pkg-config-path (string)
290 This will get prepended to PKG_CONFIG_PATH in the build environment
291 (with an trailing colon if needed).
292 env (object)
294 This is a dictionary defining environment variables to be set
295 during the build. Elements in this override the properties that set
296 the environment, like cflags and ldflags. Keys with a null value
297 unset the corresponding variable.
298 build-args (array of strings)
300 This is an array containing extra options to pass to flatpak build.
301 test-args (array of strings)
303 Similar to build-args but affects the tests, not the normal build.
304 config-opts (array of strings)
306 This is an array containing extra options to pass to configure.
307 make-args (array of strings)
309 An array of extra arguments that will be passed to make
310 make-install-args (array of strings)
312 An array of extra arguments that will be passed to make install
313 strip (boolean)
315 If this is true (the default is false) then all ELF files will be
316 stripped after install.
317 no-debuginfo (boolean)
319 By default (if strip is not true) flatpak-builder extracts all
320 debug info in ELF files to a separate files and puts this in an
321 extension. If you want to disable this, set no-debuginfo to true.
322 no-debuginfo-compression (boolean)
324 By default when extracting debuginfo we compress the debug
325 sections. If you want to disable this, set no-debuginfo-compression
326 to true.
327 arch (object)
329 This is a dictionary defining for each arch a separate build
330 options object that override the main one.
331 Extension
333 Extension define extension points in the app/runtime that can be
334 implemented by extensions, supplying extra files which are available
335 during runtime..
336 These are the properties that are accepted:
338 directory (string)
340 The directory where the extension is mounted. If the extension
341 point is for an application, this path is relative to /app,
342 otherwise it is relative to /usr.
343 bundle (boolean)
345 If this is true, then the data created in the extension directory
346 is omitted from the result, and instead packaged in a separate
347 extension.
348 remove-after-build (boolean)
350 If this is true, the extension is removed during when finishing.
351 This is only interesting for extensions in the add-build-extensions
352 property.
353 Additionally the standard flatpak extension properies are supported,
355 and put directly into the metadata file: autodelete, no-autodownload,
356 subdirectories, add-ld-path, download-if, enable-if, merge-dirs,
357 subdirectory-suffix, locale-subset, version, versions. See the flatpak
358 metadata documentation for more information on these.
359 Module
361 Each module specifies a source that has to be separately built and
362 installed. It contains the build options and a list of sources to
363 download and extract before building.
364 Modules can be nested, in order to turn related modules on and off with
366 a single key.
367 These are the properties that are accepted:
369 name (string)
371 The name of the module, used in e.g. build logs. The name is also
372 used for constructing filenames and commandline arguments,
373 therefore using spaces or '/' in this string is a bad idea.
374 disabled (boolean)
376 If true, skip this module
377 sources (array of objects or strings)
379 An array of objects defining sources that will be downloaded and
380 extracted in order. String members in the array are interpreted as
381 the name of a separate json or yaml file that contains sources. See
382 below for details.
383 config-opts (array of strings)
385 An array of options that will be passed to configure
386 make-args (array of strings)
388 An array of arguments that will be passed to make
389 make-install-args (array of strings)
391 An array of arguments that will be passed to make install
392 rm-configure (boolean)
394 If true, remove the configure script before starting build
395 no-autogen (boolean)
397 Ignore the existence of an autogen script
398 no-parallel-make (boolean)
400 Don't call make with arguments to build in parallel
401 install-rule (string)
403 Name of the rule passed to make for the install phase, default is
404 install
405 no-make-install (boolean)
407 Don't run the make install (or equivalent) stage
408 no-python-timestamp-fix (boolean)
410 Don't fix up the *.py[oc] header timestamps for ostree use.
411 cmake (boolean)
413 Use cmake instead of configure (deprecated: use buildsystem
414 instead)
415 buildsystem (string)
417 Build system to use: autotools, cmake, cmake-ninja, meson, simple,
418 qmake
419 builddir (boolean)
421 Use a build directory that is separate from the source directory
422 subdir (string)
424 Build inside this subdirectory of the extracted sources
425 build-options (object)
427 A build options object that can override global options
428 build-commands (array of strings)
430 An array of commands to run during build (between make and make
431 install if those are used). This is primarily useful when using the
432 "simple" buildsystem. Each command is run in /bin/sh -c, so it can
433 use standard POSIX shell syntax such as piping output.
434 post-install (array of strings)
436 An array of shell commands that are run after the install phase.
437 Can for example clean up the install dir, or install extra files.
438 cleanup (array of strings)
440 An array of file patterns that should be removed at the end.
441 Patterns starting with / are taken to be full pathnames (without
442 the /app prefix), otherwise they just match the basename. Note that
443 any patterns will only match files installed by this module.
444 ensure-writable (array of strings)
446 The way the builder works is that files in the install directory
447 are hard-links to the cached files, so you're not allowed to modify
448 them in-place. If you list a file in this then the hardlink will be
449 broken and you can modify it. This is a workaround, ideally
450 installing files should replace files, not modify existing ones.
451 only-arches (array of strings)
453 If non-empty, only build the module on the arches listed.
454 skip-arches (array of strings)
456 Don't build on any of the arches listed.
457 cleanup-platform (array of strings)
459 Extra files to clean up in the platform.
460 run-tests (boolean)
462 If true this will run the tests after installing.
463 test-rule (string)
465 The target to build when running the tests. Defaults to "check" for
466 make and "test" for ninja. Set to empty to disable.
467 test-commands (array of strings)
469 Array of commands to run during the tests.
470 modules (array of objects or strings)
472 An array of objects specifying nested modules to be built before
473 this one. String members in the array are interpreted as names of a
474 separate json or yaml file that contains a module.
475 Sources
477 These contain a pointer to the source that will be extracted into the
478 source directory before the build starts. They can be of several types,
479 distinguished by the type property.
480 Additionally, the sources list can contain a plain string, which is
482 interpreted as the name of a separate json or yaml file that is read
483 and inserted at this point. The file can contain a single source, or an
484 array of sources.
485 All sources
487 only-arches (array of strings)
488 If non-empty, only build the module on the arches listed.
489 skip-arches (array of strings)
491 Don't build on any of the arches listed.
492 dest (string)
494 Directory inside the source dir where this source will be
495 extracted.
496 Archive sources (tar, zip)
498 type
499 "archive"
500 path (string)
502 The path of the archive
503 url (string)
505 The URL of a remote archive that will be downloaded. This
506 overrides path if both are specified.
507 mirror-urls (array of strings)
509 A list of alternative urls that are used if the main url fails.
510 git-init (boolean)
512 Whether to initialise the repository as a git repository.
513 md5 (string)
515 The md5 checksum of the file, verified after download
516 Note that md5 is no longer considered a safe checksum, we
518 recommend you use at least sha256.
519 sha1 (string)
521 The sha1 checksum of the file, verified after download
522 Note that sha1 is no longer considered a safe checksum, we
524 recommend you use at least sha256.
525 sha256 (string)
527 The sha256 checksum of the file, verified after download
528 sha512 (string)
530 The sha512 checksum of the file, verified after download
531 strip-components (integer)
533 The number of initial pathname components to strip during
534 extraction. Defaults to 1.
535 dest-filename (string)
537 Filename to for the downloaded file, defaults to the basename
538 of url.
539 Git sources
541 type
542 "git"
543 path (string)
545 The path to a local checkout of the git repository. Due to how
546 git-clone works, this will be much faster than specifying a URL
547 of file:///...
548 url (string)
550 URL of the git repository. This overrides path if both are
551 specified. When using git via SSH, the correct syntax is
552 ssh://user@domain/path/to/repo.git.
553 branch (string)
555 The branch to use from the git repository
556 tag (string)
558 The tag to use from the git repository
559 commit (string)
561 The commit to use from the git repository. If branch is also
562 specified, then it is verified that the branch/tag is at this
563 specific commit. This is a readable way to document that you're
564 using a particular tag, but verify that it does not change.
565 disable-fsckobjects (boolean)
567 Don't use transfer.fsckObjects=1 to mirror git repository. This
568 may be needed for some (broken) repositories.
569 disable-shallow-clone (boolean)
571 Don't optimize by making a shallow clone when downloading the
572 git repo.
573 Bzr sources
575 type
576 "bzr"
577 url (string)
579 URL of the bzr repository
580 revision (string)
582 A specific revision to use in the branch
583 Svn sources
585 type
586 "svn"
587 url (string)
589 URL of the svn repository, including branch/tag part
590 revision (string)
592 A specific revision number to use
593 Directory sources
595 type
596 "dir"
597 path (string)
599 The path of a local directory whose content will be copied into
600 the source dir. Note that directory sources don't currently
601 support caching, so they will be rebuilt each time.
602 skip (array of strings)
604 Source files to ignore in the directory.
605 File sources
607 type
608 "file"
609 path (string)
611 The path of a local file that will be copied into the source
612 dir
613 url (string)
615 The URL of a remote file that will be downloaded and copied
616 into the source dir. This overrides path if both are specified.
617 mirror-urls (array of strings)
619 A list of alternative urls that are used if the main url fails.
620 md5 (string)
622 The md5 checksum of the file, verified after download. This is
623 optional for local files.
624 Note that md5 is no longer considered a safe checksum, we
626 recommend you use at least sha256.
627 sha1 (string)
629 The sha1 checksum of the file, verified after download. This is
630 optional for local files.
631 Note that sha1 is no longer considered a safe checksum, we
633 recommend you use at least sha256.
634 sha256 (string)
636 The sha256 checksum of the file, verified after download. This
637 is optional for local files.
638 sha512 (string)
640 The sha512 checksum of the file, verified after download. This
641 is optional for local files.
642 dest-filename (string)
644 Filename to use inside the source dir, default to the basename
645 of path.
646 Script sources
648 This is a way to create a shell (/bin/sh) script from an inline set
649 of commands.
650 type
652 "script"
653 commands (array of strings)
655 An array of shell commands that will be put in a shellscript
656 file
657 dest-filename (string)
659 Filename to use inside the source dir, default to autogen.sh.
660 Shell sources
662 This is a way to create/modify the sources by running shell
663 commands.
664 type
666 "shell"
667 commands (array of strings)
669 An array of shell commands that will be run during source
670 extraction
671 Patch sources
673 type
674 "patch"
675 path (string)
677 The path of a patch file that will be applied in the source dir
678 paths (array of strings)
680 An list of paths to a patch files that will be applied in the
681 source dir, in order
682 strip-components (integer)
684 The value of the -p argument to patch, defaults to 1.
685 use-git (boolean)
687 Whether to use "git apply" rather than "patch" to apply the
688 patch, required when the patch file contains binary diffs.
689 use-git-am (boolean)
691 Whether to use "git am" rather than "patch" to apply the patch,
692 required when the patch file contains binary diffs. You cannot
693 use this at the same time as use-git.
694 options (array of strings)
696 Extra options to pass to the patch command.
697 Extra data sources
699 type
700 "extra-data"
701 filename (string)
703 The name to use for the downloaded extra data
704 url (string)
706 The url to the extra data.
707 sha256 (string)
709 The sha256 of the extra data.
710 size (number)
712 The size of the extra data.
713 installed-size (string)
715 The extra installed size this adds to the app (optional).
716
718 When building the application each command is run in a separate sandbox
719 with access to only the things required for it. This section describes
720 the details of the sandbox. Any options here can be overridden globally
721 or per-module with the build-args option (although such manifest will
722 not work if you start flatpak-builder with --sandbox).
723 Filesystem
725 Each module is built in its own build directory, stored in a sub
726 directory called build/$modulename-$count in the state dir (which is
727 typically .flatpak-builder/). Additionally there is a symlink
728 build/$modulename to the latest version. In order to generate
729 reproducible builds this directory is also mounted as
730 /run/build/$modulename in the sandbox (or
731 /run/build-runtime/$modulename when building runtimes). This is used as
732 current working directory for all build ops.
733 The destination directory for installation is accessible for writing at
735 the place it will seen at runtime. In the case of a regular application
736 this will be /app. If building a runtime it will instead be /usr, and
737 when building an extension it will be at the extensionpoint directory
738 somewhere below /app (for app extension) or /usr (for runtime
739 extensions).
740 Additionally the there will be (as needed, depending on what is
742 building) read-only mounts of the sdk at /usr, sdk extensions below
743 that, and the application at /app. No other filesystem access is
744 available.
745 Environment
747 The environment can be modified in several ways in the manifest, but
748 the default values are:
749 FLATPAK_ID
751 The id of the application currently building.
752 FLATPAK_ARCH
754 The architecture currently building.
755 FLATPAK_DEST
757 The path to where the current build should install into. This is
758 /app for application builds.
759 FLATPAK_BUILDER_N_JOBS
761 The number of jobs that flatpak-builder would normally use for make
762 -j. Defaults to ncpus unless the module disabled parallel make.
763 FLATPAK_BUILDER_BUILDDIR
765 The path to the build directory of the module currently building.
766 This is normally /run/build/$MODULE.
767 PATH
769 /app/bin:/usr/bin
770 LD_LIBRARY_PATH
772 /app/lib
773 PKG_CONFIG_PATH
775 /app/lib/pkgconfig:/app/share/pkgconfig:/usr/lib/pkgconfig:/usr/share/pkgconfig
776 ACLOCAL_PATH
778 /app/share/aclocal
779 C_INCLUDE_PATH
781 /app/include
782 CPLUS_INCLUDE_PATH
784 /app/include
785 LDFLAGS
787 -L/app/lib
788 LC_ALL
790 en_US.utf8
791 Permissions
793 Builds have the --allow=devel and --allow=multiarch permissions that
794 regular flatpak runs don't have by default. This allows limits the
795 syscall filtering that is normally done so development tools like
796 debuggers work. Otherwise the build sandbox is very limited, for
797 example there is no network access.
798
800 $ flatpak-builder my-app-dir manifest.json
801 Example manifest file:
803 {
805 "id": "org.test.TestApp",
806 "runtime": "org.freedesktop.Platform",
807 "runtime-version": "1.2",
808 "sdk": "org.freedesktop.Sdk",
809 "command": "test",
810 "clean": [ "/include", "*.la" ],
811 "build-options" : {
812 "cflags": "-O2 -g",
813 "cxxflags": "-O2 -g",
814 "env": {
815 "V": "1"
816 },
817 "arch": {
818 "x86_64": {
819 "cflags": "-O3 -g",
820 }
821 }
822 },
823 "modules": [
824 {
825 "name": "pygobject",
826 "config-opts": [ "--disable-introspection" ],
827 "sources": [
828 {
829 "type": "archive",
830 "url": "http://ftp.gnome.org/pub/GNOME/sources/pygobject/2.28/pygobject-2.28.6.tar.xz",
831 "sha256": "fb8a1d4f665130a125011659bd347c7339c944232163dbb9a34fd0686577adb8"
832 },
833 {
834 "type": "patch",
835 "path": "required-pygobject-fix.patch"
836 },
837 {
838 "type": "file",
839 "path": "pygobject-extra-file",
840 "dest-filename": "extra-file"
841 }
842 ]
843 },
844 {
845 "name": "babl",
846 "build-options" : { "cxxflags": "-O2 -g -std=c++11" },
847 "cleanup": [ "/bin" ],
848 "sources": [
849 {
850 "type": "git",
851 "url": "https://gitlab.gnome.org/GNOME/babl.git"
852 }
853 ]
854 },
855 {
856 "name": "testapp",
857 "sources": [
858 {
859 "type": "bzr",
860 "url": "lp:testapp"
861 }
862 ]
863 }
864 ]
865 }
866
868 flatpak-builder(1)
869flatpak FLATPAK MANIFEST(5)