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 of the application, defaults to master.
26 collection-id (string)
28 The collection ID of the repository, defaults to being unset.
29 Setting a globally unique collection ID allows the apps in the
30 repository to be shared over peer to peer systems without needing
31 further configuration. If building in an existing repository, the
32 collection ID must match the existing configured collection ID for
33 that repository.
34 extension-tag (string)
36 If building an extension, the tag for the extension point to use.
37 Since flatpak 0.11.4 a runtime may define multiple locations for
38 the same extension point with the intention that different branches
39 for the extension are mounted at each location. When building an
40 extension it is necessary to know what extension point to install
41 the extension to. This option resolves any ambiguity in which
42 extension point to choose. If not specified, the default choice is
43 to install into either the only location for the extension point or
44 into the location for the untagged extension point. If there are
45 multiple locations for the same extension point defined with
46 different tags then an error will occur.
47 runtime (string)
49 The name of the runtime that the application uses.
50 runtime-version (string)
52 The version of the runtime that the application uses, defaults to
53 master.
54 sdk (string)
56 The name of the development runtime that the application builds
57 with.
58 var (string)
60 Initialize the (otherwise empty) writable /var in the build with a
61 copy of this runtime.
62 metadata (string)
64 Use this file as the base metadata file when finishing.
65 command (string)
67 The filename or path to the main binary of the application. Note
68 that this is really just a single file, not a commandline. If you
69 want to pass arguments, install a shell script wrapper and use that
70 as the command.
71 build-runtime (boolean)
73 Build a new runtime instead of an application.
74 build-extension (boolean)
76 Build an extension.
77 separate-locales (boolean)
79 Separate out locale files and translations to an extension runtime.
80 Defaults to true.
81 id-platform (string)
83 When building a runtime sdk, also create a platform based on it
84 with this id.
85 metadata-platform (string)
87 The metadata file to use for the platform we create.
88 writable-sdk (boolean)
90 If true, use a writable copy of the sdk for /usr. Defaults to true
91 if build-runtime is specified.
92 appstream-compose (boolean)
94 Run appstream-compose during cleanup phase. Defaults to true.
95 sdk-extensions (array of strings)
97 Install these extra sdk extensions in /usr.
98 platform-extensions (array of strings)
100 Install these extra sdk extensions when creating the platform.
101 base (string)
103 Start with the files from the specified application. This can be
104 used to create applications that extend another application.
105 base-version (string)
107 Use this specific version of the application specified in base. If
108 unspecified, this uses the value specified in branch
109 base-extensions (array of strings)
111 Install these extra extensions from the base application when
112 initializing the application directory.
113 inherit-extensions (array of strings)
115 Inherit these extra extensions points from the base application or
116 sdk when finishing the build.
117 inherit-sdk-extensions (array of strings)
119 Inherit these extra extensions points from the base application or
120 sdk when finishing the build, but do not inherit them into the
121 platform.
122 tags (array of strings)
124 Add these tags to the metadata file.
125 build-options (object)
127 Object specifying the build environment. See below for details.
128 modules (array of objects or strings)
130 An array of objects specifying the modules to be built in order.
131 String members in the array are interpreted as the name of a
132 separate json or yaml file that contains a module. See below for
133 details.
134 add-extensions (objects)
136 This is a dictionary of extension objects. The key is the name of
137 the extension. See below for details.
138 add-build-extensions (objects)
140 This is a dictionary of extension objects similar to
141 add-extensions. The main difference is that the extensions are
142 added early and are available for use during the build.
143 cleanup (array of strings)
145 An array of file patterns that should be removed at the end.
146 Patterns starting with / are taken to be full pathnames (without
147 the /app prefix), otherwise they just match the basename.
148 cleanup-commands (array of strings)
150 An array of commandlines that are run during the cleanup phase.
151 cleanup-platform (array of strings)
153 Extra files to clean up in the platform.
154 cleanup-platform-commands (array of strings)
156 An array of commandlines that are run during the cleanup phase of
157 the platform.
158 prepare-platform-commands (array of strings)
160 An array of commandlines that are run after importing the base
161 platform, but before applying the new files from the sdk. This is a
162 good place to e.g. delete things from the base that may conflict
163 with the files added in the sdk.
164 finish-args (array of strings)
166 An array of arguments passed to the flatpak build-finish command.
167 rename-desktop-file (string)
169 Any desktop file with this name will be renamed to a name based on
170 id during the cleanup phase.
171 rename-appdata-file (string)
173 Any appdata file with this name will be renamed to a name based on
174 id during the cleanup phase.
175 rename-icon (string)
177 Any icon with this name will be renamed to a name based on id
178 during the cleanup phase. Note that this is the icon name, not the
179 full filenames, so it should not include a filename extension.
180 appdata-license (string)
182 Replace the appdata project_license field with this string. This is
183 useful as the upstream license is typically only about the
184 application itself, whereas the bundled app can contain other
185 licenses too.
186 copy-icon (boolean)
188 If rename-icon is set, keep a copy of the old icon file.
189 desktop-file-name-prefix (string)
191 This string will be prefixed to the Name key in the main
192 application desktop file.
193 desktop-file-name-suffix (string)
195 This string will be suffixed to the Name key in the main
196 application desktop file.
197 Build Options
199 Build options specify the build environment of a module, and can be
200 specified globally as well as per-module. Options can also be specified
201 on a per-architecture basis using the arch property.
202 These are the properties that are accepted:
204 cflags (string)
206 This is set in the environment variable CFLAGS during the build.
207 Multiple specifications of this (in e.g. per-arch area) are
208 concatenated, separated by spaces.
209 cflags-override (boolean)
211 If this is true, clear cflags from previous build options before
212 adding it from these options.
213 cppflags (string)
215 This is set in the environment variable CPPFLAGS during the build.
216 Multiple specifications of this (in e.g. per-arch area) are
217 concatenated, separated by spaces.
218 cppflags-override (boolean)
220 If this is true, clear cppflags from previous build options before
221 adding it from these options.
222 cxxflags (string)
224 This is set in the environment variable CXXFLAGS during the build.
225 Multiple specifications of this (in e.g. per-arch area) are
226 concatenated, separated by spaces.
227 cxxflags-override (boolean)
229 If this is true, clear cxxflags from previous build options before
230 adding it from these options.
231 ldflags (string)
233 This is set in the environment variable LDFLAGS during the build.
234 Multiple specifications of this (in e.g. per-arch area) are
235 concatenated, separated by spaces.
236 ldflags-override (boolean)
238 If this is true, clear ldflags from previous build options before
239 adding it from these options.
240 prefix (string)
242 The build prefix for the modules (defaults to /app for applications
243 and /usr for runtimes).
244 libdir (string)
246 The build libdir for the modules (defaults to /app/lib for
247 applications and /usr/lib for runtimes).
248 append-path (string)
250 This will get appended to PATH in the build environment (with an
251 leading colon if needed).
252 prepend-path (string)
254 This will get prepended to PATH in the build environment (with an
255 trailing colon if needed).
256 append-ld-library-path (string)
258 This will get appended to LD_LIBRARY_PATH in the build environment
259 (with an leading colon if needed).
260 prepend-ld-library-path (string)
262 This will get prepended to LD_LIBRARY_PATH in the build environment
263 (with an trailing colon if needed).
264 append-pkg-config-path (string)
266 This will get appended to PKG_CONFIG_PATH in the build environment
267 (with an leading colon if needed).
268 prepend-pkg-config-path (string)
270 This will get prepended to PKG_CONFIG_PATH in the build environment
271 (with an trailing colon if needed).
272 env (object)
274 This is a dictionary defining environment variables to be set
275 during the build. Elements in this override the properties that set
276 the environment, like cflags and ldflags.
277 build-args (array of strings)
279 This is an array containing extra options to pass to flatpak build.
280 test-args (array of strings)
282 Similar to build-args but affects the tests, not the normal build.
283 config-opts (array of strings)
285 This is an array containing extra options to pass to configure.
286 make-args (array of strings)
288 An array of extra arguments that will be passed to make
289 make-install-args (array of strings)
291 An array of extra arguments that will be passed to make install
292 strip (boolean)
294 If this is true (the default is false) then all ELF files will be
295 stripped after install.
296 no-debuginfo (boolean)
298 By default (if strip is not true) flatpak-builder extracts all
299 debug info in ELF files to a separate files and puts this in an
300 extension. If you want to disable this, set no-debuginfo to true.
301 no-debuginfo-compression (boolean)
303 By default when extracting debuginfo we compress the debug
304 sections. If you want to disable this, set no-debuginfo-compression
305 to true.
306 arch (object)
308 This is a dictionary defining for each arch a separate build
309 options object that override the main one.
310 Extension
312 Extension define extension points in the app/runtime that can be
313 implemented by extensions, supplying extra files which are available
314 during runtime..
315 These are the properties that are accepted:
317 directory (string)
319 The directory where the extension is mounted. If the extension
320 point is for an application, this path is relative to /app,
321 otherwise it is relative to /usr.
322 bundle (boolean)
324 If this is true, then the data created in the extension directory
325 is omitted from the result, and instead packaged in a separate
326 extension.
327 remove-after-build (boolean)
329 If this is true, the extension is removed during when finishing.
330 This is only interesting for extensions in the add-build-extensions
331 property.
332 Additionally the standard flatpak extension properies are supported,
334 and put directly into the metadata file: autodelete, no-autodownload,
335 subdirectories, add-ld-path, download-if, enable-if, merge-dirs,
336 subdirectory-suffix, locale-subset, version, versions. See the flatpak
337 metadata documentation for more information on these.
338 Module
340 Each module specifies a source that has to be separately built and
341 installed. It contains the build options and a list of sources to
342 download and extract before building.
343 Modules can be nested, in order to turn related modules on and off with
345 a single key.
346 These are the properties that are accepted:
348 name (string)
350 The name of the module, used in e.g. build logs. The name is also
351 used for constructing filenames and commandline arguments,
352 therefore using spaces or '/' in this string is a bad idea.
353 disabled (boolean)
355 If true, skip this module
356 sources (array of objects or strings)
358 An array of objects defining sources that will be downloaded and
359 extracted in order. String members in the array are interpreted as
360 the name of a separate json or yaml file that contains sources. See
361 below for details.
362 config-opts (array of strings)
364 An array of options that will be passed to configure
365 make-args (array of strings)
367 An array of arguments that will be passed to make
368 make-install-args (array of strings)
370 An array of arguments that will be passed to make install
371 rm-configure (boolean)
373 If true, remove the configure script before starting build
374 no-autogen (boolean)
376 Ignore the existence of an autogen script
377 no-parallel-make (boolean)
379 Don't call make with arguments to build in parallel
380 install-rule (string)
382 Name of the rule passed to make for the install phase, default is
383 install
384 no-make-install (boolean)
386 Don't run the make install (or equivalent) stage
387 no-python-timestamp-fix (boolean)
389 Don't fix up the *.py[oc] header timestamps for ostree use.
390 cmake (boolean)
392 Use cmake instead of configure (deprecated: use buildsystem
393 instead)
394 buildsystem (string)
396 Build system to use: autotools, cmake, cmake-ninja, meson, simple,
397 qmake
398 builddir (boolean)
400 Use a build directory that is separate from the source directory
401 subdir (string)
403 Build inside this subdirectory of the extracted sources
404 build-options (object)
406 A build options object that can override global options
407 build-commands (array of strings)
409 An array of commands to run during build (between make and make
410 install if those are used). This is primarily useful when using the
411 "simple" buildsystem. Each command is run in /bin/sh -c, so it can
412 use standard POSIX shell syntax such as piping output.
413 post-install (array of strings)
415 An array of shell commands that are run after the install phase.
416 Can for example clean up the install dir, or install extra files.
417 cleanup (array of strings)
419 An array of file patterns that should be removed at the end.
420 Patterns starting with / are taken to be full pathnames (without
421 the /app prefix), otherwise they just match the basename. Note that
422 any patterns will only match files installed by this module.
423 ensure-writable (array of strings)
425 The way the builder works is that files in the install directory
426 are hard-links to the cached files, so you're not allowed to modify
427 them in-place. If you list a file in this then the hardlink will be
428 broken and you can modify it. This is a workaround, ideally
429 installing files should replace files, not modify existing ones.
430 only-arches (array of strings)
432 If non-empty, only build the module on the arches listed.
433 skip-arches (array of strings)
435 Don't build on any of the arches listed.
436 cleanup-platform (array of strings)
438 Extra files to clean up in the platform.
439 run-tests (boolean)
441 If true this will run the tests after installing.
442 test-rule (string)
444 The target to build when running the tests. Defaults to "check" for
445 make and "test" for ninja. Set to empty to disable.
446 test-commands (array of strings)
448 Array of commands to run during the tests.
449 modules (array of objects or strings)
451 An array of objects specifying nested modules to be built before
452 this one. String members in the array are interpreted as names of a
453 separate json or yaml file that contains a module.
454 Sources
456 These contain a pointer to the source that will be extracted into the
457 source directory before the build starts. They can be of several types,
458 distinguished by the type property.
459 Additionally, the sources list can contain a plain string, which is
461 interpreted as the name of a separate json or yaml file that is read
462 and inserted at this point. The file can contain a single source, or an
463 array of sources.
464 All sources
466 only-arches (array of strings)
467 If non-empty, only build the module on the arches listed.
468 skip-arches (array of strings)
470 Don't build on any of the arches listed.
471 dest (string)
473 Directory inside the source dir where this source will be
474 extracted.
475 Archive sources (tar, zip)
477 type
478 "archive"
479 path (string)
481 The path of the archive
482 url (string)
484 The URL of a remote archive that will be downloaded. This
485 overrides path if both are specified.
486 mirror-urls (array of strings)
488 A list of alternative urls that are used if the main url fails.
489 git-init (boolean)
491 Whether to initialise the repository as a git repository.
492 md5 (string)
494 The md5 checksum of the file, verified after download
495 Note that md5 is no longer considered a safe checksum, we
497 recommend you use at least sha256.
498 sha1 (string)
500 The sha1 checksum of the file, verified after download
501 Note that sha1 is no longer considered a safe checksum, we
503 recommend you use at least sha256.
504 sha256 (string)
506 The sha256 checksum of the file, verified after download
507 sha512 (string)
509 The sha512 checksum of the file, verified after download
510 strip-components (integer)
512 The number of initial pathname components to strip during
513 extraction. Defaults to 1.
514 dest-filename (string)
516 Filename to for the downloaded file, defaults to the basename
517 of url.
518 Git sources
520 type
521 "git"
522 path (string)
524 The path to a local checkout of the git repository. Due to how
525 git-clone works, this will be much faster than specifying a URL
526 of file:///...
527 url (string)
529 URL of the git repository. This overrides path if both are
530 specified.
531 branch (string)
533 The branch to use from the git repository
534 tag (string)
536 The tag to use from the git repository
537 commit (string)
539 The commit to use from the git repository. If branch is also
540 specified, then it is verified that the branch/tag is at this
541 specific commit. This is a readable way to document that you're
542 using a particular tag, but verify that it does not change.
543 disable-fsckobjects (boolean)
545 Don't use transfer.fsckObjects=1 to mirror git repository. This
546 may be needed for some (broken) repositories.
547 disable-shallow-clone (boolean)
549 Don't optimize by making a shallow clone when downloading the
550 git repo.
551 Bzr sources
553 type
554 "bzr"
555 url (string)
557 URL of the bzr repository
558 revision (string)
560 A specific revision to use in the branch
561 Svn sources
563 type
564 "svn"
565 url (string)
567 URL of the svn repository, including branch/tag part
568 revision (string)
570 A specific revision number to use
571 Directory sources
573 type
574 "dir"
575 path (string)
577 The path of a local directory whose content will be copied into
578 the source dir. Note that directory sources don't currently
579 support caching, so they will be rebuilt each time.
580 skip (array of strings)
582 Source files to ignore in the directory.
583 File sources
585 type
586 "file"
587 path (string)
589 The path of a local file that will be copied into the source
590 dir
591 url (string)
593 The URL of a remote file that will be downloaded and copied
594 into the source dir. This overrides path if both are specified.
595 mirror-urls (array of strings)
597 A list of alternative urls that are used if the main url fails.
598 md5 (string)
600 The md5 checksum of the file, verified after download. This is
601 optional for local files.
602 Note that md5 is no longer considered a safe checksum, we
604 recommend you use at least sha256.
605 sha1 (string)
607 The sha1 checksum of the file, verified after download. This is
608 optional for local files.
609 Note that sha1 is no longer considered a safe checksum, we
611 recommend you use at least sha256.
612 sha256 (string)
614 The sha256 checksum of the file, verified after download. This
615 is optional for local files.
616 sha512 (string)
618 The sha512 checksum of the file, verified after download. This
619 is optional for local files.
620 dest-filename (string)
622 Filename to use inside the source dir, default to the basename
623 of path.
624 Script sources
626 This is a way to create a shell (/bin/sh) script from an inline set
627 of commands.
628 type
630 "script"
631 commands (array of strings)
633 An array of shell commands that will be put in a shellscript
634 file
635 dest-filename (string)
637 Filename to use inside the source dir, default to the basename
638 of path.
639 Shell sources
641 This is a way to create/modify the sources by running shell
642 commands.
643 type
645 "shell"
646 commands (array of strings)
648 An array of shell commands that will be run during source
649 extraction
650 Patch sources
652 type
653 "patch"
654 path (string)
656 The path of a patch file that will be applied in the source dir
657 paths (array of strings)
659 An list of paths to a patch files that will be applied in the
660 source dir, in order
661 strip-components (integer)
663 The value of the -p argument to patch, defaults to 1.
664 use-git (boolean)
666 Whether to use "git apply" rather than "patch" to apply the
667 patch, required when the patch file contains binary diffs.
668 use-git-am (boolean)
670 Whether to use "git am" rather than "patch" to apply the patch,
671 required when the patch file contains binary diffs. You cannot
672 use this at the same time as use-git.
673 options (array of strings)
675 Extra options to pass to the patch command.
676 Extra data sources
678 type
679 "extra-data"
680 filename (string)
682 The name to use for the downloaded extra data
683 url (string)
685 The url to the extra data.
686 sha256 (string)
688 The sha256 of the extra data.
689 size (number)
691 The size of the extra data.
692 installed-size (string)
694 The extra installed size this adds to the app (optional).
695
697 When building the application each command is run in a separate sandbox
698 with access to only the things required for it. This section describes
699 the details of the sandbox. Any options here can be overridden globally
700 or per-module with the build-args option (although such manifest will
701 not work if you start flatpak-builder with --sandbox).
702 Filesystem
704 Each module is built in its own build directory, stored in a sub
705 directory called build/$modulename-$count in the state dir (which is
706 typically .flatpak-builder/). Additionally there is a symlink
707 build/$modulename to the latest version. In order to generate
708 reproducible builds this directory is also mounted as
709 /run/build/$modulename in the sandbox (or
710 /run/build-runtime/$modulename when building runtimes). This is used as
711 current working directory for all build ops.
712 The destination directory for installation is accessible for writing at
714 the place it will seen at runtime. In the case of a regular application
715 this will be /app. If building a runtime it will instead be /usr, and
716 when building an extension it will be at the extensionpoint directory
717 somewhere below /app (for app extension) or /usr (for runtime
718 extensions).
719 Additionally the there will be (as needed, depending on what is
721 building) read-only mounts of the sdk at /usr, sdk extensions below
722 that, and the application at /app. No other filesystem access is
723 available.
724 Environment
726 The environment can be modified in several ways in the manifest, but
727 the default values are:
728 FLATPAK_ID
730 The id of the application currently building.
731 FLATPAK_ARCH
733 The architecture currently building.
734 FLATPAK_DEST
736 The path to where the current build should install into. This is
737 /app for application builds.
738 FLATPAK_BUILDER_N_JOBS
740 The number of jobs that flatpak-builder would normally use for make
741 -j. Defaults to ncpus unless the module disabled parallel make.
742 FLATPAK_BUILDER_BUILDDIR
744 The path to the build directory of the module currently building.
745 This is normally /run/build/$MODULE.
746 PATH
748 /app/bin:/usr/bin
749 LD_LIBRARY_PATH
751 /app/lib
752 PKG_CONFIG_PATH
754 /app/lib/pkgconfig:/app/share/pkgconfig:/usr/lib/pkgconfig:/usr/share/pkgconfig
755 ACLOCAL_PATH
757 /app/share/aclocal
758 C_INCLUDE_PATH
760 /app/include
761 CPLUS_INCLUDE_PATH
763 /app/include
764 LDFLAGS
766 -L/app/lib
767 LC_ALL
769 en_US.utf8
770 Permissions
772 Builds have the --allow=devel and --allow=multiarch permissions that
773 regular flatpak runs don't have by default. This allows limits the
774 syscall filtering that is normally done so development tools like
775 debuggers work. Otherwise the build sandbox is very limited, for
776 example there is no network access.
777
779 $ flatpak-builder my-app-dir manifest.json
780 Example manifest file:
782 {
784 "id": "org.test.TestApp",
785 "runtime": "org.freedesktop.Platform",
786 "runtime-version": "1.2",
787 "sdk": "org.freedesktop.Sdk",
788 "command": "test",
789 "clean": [ "/include", "*.la" ],
790 "build-options" : {
791 "cflags": "-O2 -g",
792 "cxxflags": "-O2 -g",
793 "env": {
794 "V": "1"
795 },
796 "arch": {
797 "x86_64": {
798 "cflags": "-O3 -g",
799 }
800 }
801 },
802 "modules": [
803 {
804 "name": "pygobject",
805 "config-opts": [ "--disable-introspection" ],
806 "sources": [
807 {
808 "type": "archive",
809 "url": "http://ftp.gnome.org/pub/GNOME/sources/pygobject/2.28/pygobject-2.28.6.tar.xz",
810 "sha256": "fb8a1d4f665130a125011659bd347c7339c944232163dbb9a34fd0686577adb8"
811 },
812 {
813 "type": "patch",
814 "path": "required-pygobject-fix.patch"
815 },
816 {
817 "type": "file",
818 "path": "pygobject-extra-file",
819 "dest-filename": "extra-file"
820 }
821 ]
822 },
823 {
824 "name": "babl",
825 "build-options" : { "cxxflags": "-O2 -g -std=c++11" },
826 "cleanup": [ "/bin" ],
827 "sources": [
828 {
829 "type": "git",
830 "url": "https://gitlab.gnome.org/GNOME/babl.git"
831 }
832 ]
833 },
834 {
835 "name": "testapp",
836 "sources": [
837 {
838 "type": "bzr",
839 "url": "lp:testapp"
840 }
841 ]
842 }
843 ]
844 }
845
847 flatpak-builder(1)
848flatpak FLATPAK MANIFEST(5)