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 overridden 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 token-type (integer)
64 The type of token needed to install this commit. Setting this to a
65 value greater than 0 implies that authentication will be needed to
66 install the flatpak.
67 runtime (string)
69 The name of the runtime that the application uses.
70 runtime-version (string)
72 The version of the runtime that the application uses, defaults to
73 master.
74 sdk (string)
76 The name of the development runtime that the application builds
77 with.
78 var (string)
80 Initialize the (otherwise empty) writable /var in the build with a
81 copy of this runtime.
82 metadata (string)
84 Use this file as the base metadata file when finishing.
85 command (string)
87 The filename or path to the main binary of the application. Note
88 that this is really just a single file, not a commandline. If you
89 want to pass arguments, install a shell script wrapper and use that
90 as the command.
91 Also note that the command is used when the application is run via
93 flatpak run, and does not affect what gets executed when the
94 application is run in other ways, e.g. via the desktop file or
95 D-Bus activation.
96 build-runtime (boolean)
98 Build a new runtime instead of an application.
99 build-extension (boolean)
101 Build an extension.
102 separate-locales (boolean)
104 Separate out locale files and translations to an extension runtime.
105 Defaults to true.
106 id-platform (string)
108 When building a runtime sdk, also create a platform based on it
109 with this id.
110 metadata-platform (string)
112 The metadata file to use for the platform we create.
113 writable-sdk (boolean)
115 If true, use a writable copy of the sdk for /usr. Defaults to true
116 if build-runtime is specified.
117 appstream-compose (boolean)
119 Run appstream-compose during cleanup phase. Defaults to true.
120 sdk-extensions (array of strings)
122 Install these extra sdk extensions in /usr.
123 platform-extensions (array of strings)
125 Install these extra sdk extensions when creating the platform.
126 base (string)
128 Start with the files from the specified application. This can be
129 used to create applications that extend another application.
130 base-version (string)
132 Use this specific version of the application specified in base. If
133 unspecified, this uses the value specified in branch
134 base-extensions (array of strings)
136 Install these extra extensions from the base application when
137 initializing the application directory.
138 inherit-extensions (array of strings)
140 Inherit these extra extensions points from the base application or
141 sdk when finishing the build.
142 inherit-sdk-extensions (array of strings)
144 Inherit these extra extensions points from the base application or
145 sdk when finishing the build, but do not inherit them into the
146 platform.
147 tags (array of strings)
149 Add these tags to the metadata file.
150 build-options (object)
152 Object specifying the build environment. See below for details.
153 modules (array of objects or strings)
155 An array of objects specifying the modules to be built in order.
156 String members in the array are interpreted as the name of a
157 separate json or yaml file that contains a module. See below for
158 details.
159 add-extensions (objects)
161 This is a dictionary of extension objects. The key is the name of
162 the extension. See below for details.
163 add-build-extensions (objects)
165 This is a dictionary of extension objects similar to
166 add-extensions. The main difference is that the extensions are
167 added early and are available for use during the build.
168 cleanup (array of strings)
170 An array of file patterns that should be removed at the end.
171 Patterns starting with / are taken to be full pathnames (without
172 the /app prefix), otherwise they just match the basename.
173 cleanup-commands (array of strings)
175 An array of commandlines that are run during the cleanup phase.
176 cleanup-platform (array of strings)
178 Extra files to clean up in the platform.
179 cleanup-platform-commands (array of strings)
181 An array of commandlines that are run during the cleanup phase of
182 the platform.
183 prepare-platform-commands (array of strings)
185 An array of commandlines that are run after importing the base
186 platform, but before applying the new files from the sdk. This is a
187 good place to e.g. delete things from the base that may conflict
188 with the files added in the sdk.
189 finish-args (array of strings)
191 An array of arguments passed to the flatpak build-finish command.
192 rename-desktop-file (string)
194 Any desktop file with this name will be renamed to a name based on
195 id during the cleanup phase.
196 rename-appdata-file (string)
198 Any appdata file with this name will be renamed to a name based on
199 id during the cleanup phase.
200 rename-icon (string)
202 Any icon with this name will be renamed to a name based on id
203 during the cleanup phase. Note that this is the icon name, not the
204 full filenames, so it should not include a filename extension.
205 appdata-license (string)
207 Replace the appdata project_license field with this string. This is
208 useful as the upstream license is typically only about the
209 application itself, whereas the bundled app can contain other
210 licenses too.
211 copy-icon (boolean)
213 If rename-icon is set, keep a copy of the old icon file.
214 desktop-file-name-prefix (string)
216 This string will be prefixed to the Name key in the main
217 application desktop file.
218 desktop-file-name-suffix (string)
220 This string will be suffixed to the Name key in the main
221 application desktop file.
222 Build Options
224 Build options specify the build environment of a module, and can be
225 specified globally as well as per-module. Options can also be specified
226 on a per-architecture basis using the arch property.
227 These are the properties that are accepted:
229 cflags (string)
231 This is set in the environment variable CFLAGS during the build.
232 Multiple specifications of this (in e.g. per-arch area) are
233 concatenated, separated by spaces.
234 cflags-override (boolean)
236 If this is true, clear cflags from previous build options before
237 adding it from these options.
238 cppflags (string)
240 This is set in the environment variable CPPFLAGS during the build.
241 Multiple specifications of this (in e.g. per-arch area) are
242 concatenated, separated by spaces.
243 cppflags-override (boolean)
245 If this is true, clear cppflags from previous build options before
246 adding it from these options.
247 cxxflags (string)
249 This is set in the environment variable CXXFLAGS during the build.
250 Multiple specifications of this (in e.g. per-arch area) are
251 concatenated, separated by spaces.
252 cxxflags-override (boolean)
254 If this is true, clear cxxflags from previous build options before
255 adding it from these options.
256 ldflags (string)
258 This is set in the environment variable LDFLAGS during the build.
259 Multiple specifications of this (in e.g. per-arch area) are
260 concatenated, separated by spaces.
261 ldflags-override (boolean)
263 If this is true, clear ldflags from previous build options before
264 adding it from these options.
265 prefix (string)
267 The build prefix for the modules (defaults to /app for applications
268 and /usr for runtimes).
269 libdir (string)
271 The build libdir for the modules (defaults to /app/lib for
272 applications and /usr/lib for runtimes).
273 append-path (string)
275 This will get appended to PATH in the build environment (with an
276 leading colon if needed).
277 prepend-path (string)
279 This will get prepended to PATH in the build environment (with an
280 trailing colon if needed).
281 append-ld-library-path (string)
283 This will get appended to LD_LIBRARY_PATH in the build environment
284 (with an leading colon if needed).
285 prepend-ld-library-path (string)
287 This will get prepended to LD_LIBRARY_PATH in the build environment
288 (with an trailing colon if needed).
289 append-pkg-config-path (string)
291 This will get appended to PKG_CONFIG_PATH in the build environment
292 (with an leading colon if needed).
293 prepend-pkg-config-path (string)
295 This will get prepended to PKG_CONFIG_PATH in the build environment
296 (with an trailing colon if needed).
297 env (object)
299 This is a dictionary defining environment variables to be set
300 during the build. Elements in this override the properties that set
301 the environment, like cflags and ldflags. Keys with a null value
302 unset the corresponding variable.
303 build-args (array of strings)
305 This is an array containing extra options to pass to flatpak build.
306 test-args (array of strings)
308 Similar to build-args but affects the tests, not the normal build.
309 config-opts (array of strings)
311 This is an array containing extra options to pass to configure.
312 make-args (array of strings)
314 An array of extra arguments that will be passed to make
315 make-install-args (array of strings)
317 An array of extra arguments that will be passed to make install
318 strip (boolean)
320 If this is true (the default is false) then all ELF files will be
321 stripped after install.
322 no-debuginfo (boolean)
324 By default (if strip is not true) flatpak-builder extracts all
325 debug info in ELF files to a separate files and puts this in an
326 extension. If you want to disable this, set no-debuginfo to true.
327 no-debuginfo-compression (boolean)
329 By default when extracting debuginfo we compress the debug
330 sections. If you want to disable this, set no-debuginfo-compression
331 to true.
332 arch (object)
334 This is a dictionary defining for each arch a separate build
335 options object that override the main one.
336 Extension
338 Extension define extension points in the app/runtime that can be
339 implemented by extensions, supplying extra files which are available
340 during runtime..
341 These are the properties that are accepted:
343 directory (string)
345 The directory where the extension is mounted. If the extension
346 point is for an application, this path is relative to /app,
347 otherwise it is relative to /usr.
348 bundle (boolean)
350 If this is true, then the data created in the extension directory
351 is omitted from the result, and instead packaged in a separate
352 extension.
353 remove-after-build (boolean)
355 If this is true, the extension is removed during when finishing.
356 This is only interesting for extensions in the add-build-extensions
357 property.
358 Additionally the standard flatpak extension properties are supported,
360 and put directly into the metadata file: autodelete, no-autodownload,
361 subdirectories, add-ld-path, download-if, enable-if, merge-dirs,
362 subdirectory-suffix, locale-subset, version, versions. See the flatpak
363 metadata documentation for more information on these.
364 Module
366 Each module specifies a source that has to be separately built and
367 installed. It contains the build options and a list of sources to
368 download and extract before building.
369 Modules can be nested, in order to turn related modules on and off with
371 a single key.
372 These are the properties that are accepted:
374 name (string)
376 The name of the module, used in e.g. build logs. The name is also
377 used for constructing filenames and commandline arguments,
378 therefore using spaces or '/' in this string is a bad idea.
379 disabled (boolean)
381 If true, skip this module
382 sources (array of objects or strings)
384 An array of objects defining sources that will be downloaded and
385 extracted in order. String members in the array are interpreted as
386 the name of a separate json or yaml file that contains sources. See
387 below for details.
388 config-opts (array of strings)
390 An array of options that will be passed to configure
391 make-args (array of strings)
393 An array of arguments that will be passed to make
394 make-install-args (array of strings)
396 An array of arguments that will be passed to make install
397 rm-configure (boolean)
399 If true, remove the configure script before starting build
400 no-autogen (boolean)
402 Ignore the existence of an autogen script
403 no-parallel-make (boolean)
405 Don't call make with arguments to build in parallel
406 install-rule (string)
408 Name of the rule passed to make for the install phase, default is
409 install
410 no-make-install (boolean)
412 Don't run the make install (or equivalent) stage
413 no-python-timestamp-fix (boolean)
415 Don't fix up the *.py[oc] header timestamps for ostree use.
416 cmake (boolean)
418 Use cmake instead of configure (deprecated: use buildsystem
419 instead)
420 buildsystem (string)
422 Build system to use: autotools, cmake, cmake-ninja, meson, simple,
423 qmake
424 builddir (boolean)
426 Use a build directory that is separate from the source directory
427 subdir (string)
429 Build inside this subdirectory of the extracted sources
430 build-options (object)
432 A build options object that can override global options
433 build-commands (array of strings)
435 An array of commands to run during build (between make and make
436 install if those are used). This is primarily useful when using the
437 "simple" buildsystem. Each command is run in /bin/sh -c, so it can
438 use standard POSIX shell syntax such as piping output.
439 post-install (array of strings)
441 An array of shell commands that are run after the install phase.
442 Can for example clean up the install dir, or install extra files.
443 cleanup (array of strings)
445 An array of file patterns that should be removed at the end.
446 Patterns starting with / are taken to be full pathnames (without
447 the /app prefix), otherwise they just match the basename. Note that
448 any patterns will only match files installed by this module.
449 ensure-writable (array of strings)
451 The way the builder works is that files in the install directory
452 are hard-links to the cached files, so you're not allowed to modify
453 them in-place. If you list a file in this then the hardlink will be
454 broken and you can modify it. This is a workaround, ideally
455 installing files should replace files, not modify existing ones.
456 only-arches (array of strings)
458 If non-empty, only build the module on the arches listed.
459 skip-arches (array of strings)
461 Don't build on any of the arches listed.
462 cleanup-platform (array of strings)
464 Extra files to clean up in the platform.
465 run-tests (boolean)
467 If true this will run the tests after installing.
468 test-rule (string)
470 The target to build when running the tests. Defaults to "check" for
471 make and "test" for ninja. Set to empty to disable.
472 test-commands (array of strings)
474 Array of commands to run during the tests.
475 modules (array of objects or strings)
477 An array of objects specifying nested modules to be built before
478 this one. String members in the array are interpreted as names of a
479 separate json or yaml file that contains a module.
480 Sources
482 These contain a pointer to the source that will be extracted into the
483 source directory before the build starts. They can be of several types,
484 distinguished by the type property.
485 Additionally, the sources list can contain a plain string, which is
487 interpreted as the name of a separate json or yaml file that is read
488 and inserted at this point. The file can contain a single source, or an
489 array of sources.
490 All sources
492 only-arches (array of strings)
493 If non-empty, only build the module on the arches listed.
494 skip-arches (array of strings)
496 Don't build on any of the arches listed.
497 dest (string)
499 Directory inside the source dir where this source will be
500 extracted.
501 Archive sources (tar, zip)
503 type
504 "archive"
505 path (string)
507 The path of the archive
508 url (string)
510 The URL of a remote archive that will be downloaded. This
511 overrides path if both are specified.
512 mirror-urls (array of strings)
514 A list of alternative urls that are used if the main url fails.
515 git-init (boolean)
517 Whether to initialise the repository as a git repository.
518 archive-type (string)
520 The type of archive if it cannot be guessed from the path.
521 Possible values are "rpm", "tar", "tar-gzip", "tar-compress",
522 "tar-bzip2", "tar-lzip", "tar-lzma", "tar-lzop", "tar-xz",
523 "zip" and "7z".
524 md5 (string)
526 The md5 checksum of the file, verified after download
527 Note that md5 is no longer considered a safe checksum, we
529 recommend you use at least sha256.
530 sha1 (string)
532 The sha1 checksum of the file, verified after download
533 Note that sha1 is no longer considered a safe checksum, we
535 recommend you use at least sha256.
536 sha256 (string)
538 The sha256 checksum of the file, verified after download
539 sha512 (string)
541 The sha512 checksum of the file, verified after download
542 strip-components (integer)
544 The number of initial pathname components to strip during
545 extraction. Defaults to 1.
546 dest-filename (string)
548 Filename to for the downloaded file, defaults to the basename
549 of url.
550 Git sources
552 type
553 "git"
554 path (string)
556 The path to a local checkout of the git repository. Due to how
557 git-clone works, this will be much faster than specifying a URL
558 of file:///...
559 url (string)
561 URL of the git repository. This overrides path if both are
562 specified. When using git via SSH, the correct syntax is
563 ssh://user@domain/path/to/repo.git.
564 branch (string)
566 The branch to use from the git repository
567 tag (string)
569 The tag to use from the git repository
570 commit (string)
572 The commit to use from the git repository. If branch is also
573 specified, then it is verified that the branch/tag is at this
574 specific commit. This is a readable way to document that you're
575 using a particular tag, but verify that it does not change.
576 disable-fsckobjects (boolean)
578 Don't use transfer.fsckObjects=1 to mirror git repository. This
579 may be needed for some (broken) repositories.
580 disable-shallow-clone (boolean)
582 Don't optimize by making a shallow clone when downloading the
583 git repo.
584 disable-submodules (boolean)
586 Don't checkout the git submodules when cloning the repository.
587 Bzr sources
589 type
590 "bzr"
591 url (string)
593 URL of the bzr repository
594 revision (string)
596 A specific revision to use in the branch
597 Svn sources
599 type
600 "svn"
601 url (string)
603 URL of the svn repository, including branch/tag part
604 revision (string)
606 A specific revision number to use
607 Directory sources
609 type
610 "dir"
611 path (string)
613 The path of a local directory whose content will be copied into
614 the source dir. Note that directory sources don't currently
615 support caching, so they will be rebuilt each time.
616 skip (array of strings)
618 Source files to ignore in the directory.
619 File sources
621 type
622 "file"
623 path (string)
625 The path of a local file that will be copied into the source
626 dir
627 url (string)
629 The URL of a remote file that will be downloaded and copied
630 into the source dir. This overrides path if both are specified.
631 mirror-urls (array of strings)
633 A list of alternative urls that are used if the main url fails.
634 md5 (string)
636 The md5 checksum of the file, verified after download. This is
637 optional for local files.
638 Note that md5 is no longer considered a safe checksum, we
640 recommend you use at least sha256.
641 sha1 (string)
643 The sha1 checksum of the file, verified after download. This is
644 optional for local files.
645 Note that sha1 is no longer considered a safe checksum, we
647 recommend you use at least sha256.
648 sha256 (string)
650 The sha256 checksum of the file, verified after download. This
651 is optional for local files.
652 sha512 (string)
654 The sha512 checksum of the file, verified after download. This
655 is optional for local files.
656 dest-filename (string)
658 Filename to use inside the source dir, default to the basename
659 of path.
660 Script sources
662 This is a way to create a shell (/bin/sh) script from an inline set
663 of commands.
664 type
666 "script"
667 commands (array of strings)
669 An array of shell commands that will be put in a shellscript
670 file
671 dest-filename (string)
673 Filename to use inside the source dir, default to autogen.sh.
674 Shell sources
676 This is a way to create/modify the sources by running shell
677 commands.
678 type
680 "shell"
681 commands (array of strings)
683 An array of shell commands that will be run during source
684 extraction
685 Patch sources
687 type
688 "patch"
689 path (string)
691 The path of a patch file that will be applied in the source dir
692 paths (array of strings)
694 An list of paths to a patch files that will be applied in the
695 source dir, in order
696 strip-components (integer)
698 The value of the -p argument to patch, defaults to 1.
699 use-git (boolean)
701 Whether to use "git apply" rather than "patch" to apply the
702 patch, required when the patch file contains binary diffs.
703 use-git-am (boolean)
705 Whether to use "git am" rather than "patch" to apply the patch,
706 required when the patch file contains binary diffs. You cannot
707 use this at the same time as use-git.
708 options (array of strings)
710 Extra options to pass to the patch command.
711 Extra data sources
713 type
714 "extra-data"
715 filename (string)
717 The name to use for the downloaded extra data
718 url (string)
720 The url to the extra data.
721 sha256 (string)
723 The sha256 of the extra data.
724 size (number)
726 The size of the extra data.
727 installed-size (string)
729 The extra installed size this adds to the app (optional).
730
732 When building the application each command is run in a separate sandbox
733 with access to only the things required for it. This section describes
734 the details of the sandbox. Any options here can be overridden globally
735 or per-module with the build-args option (although such manifest will
736 not work if you start flatpak-builder with --sandbox).
737 Filesystem
739 Each module is built in its own build directory, stored in a sub
740 directory called build/$modulename-$count in the state dir (which is
741 typically .flatpak-builder/). Additionally there is a symlink
742 build/$modulename to the latest version. In order to generate
743 reproducible builds this directory is also mounted as
744 /run/build/$modulename in the sandbox (or
745 /run/build-runtime/$modulename when building runtimes). This is used as
746 current working directory for all build ops.
747 The destination directory for installation is accessible for writing at
749 the place it will seen at runtime. In the case of a regular application
750 this will be /app. If building a runtime it will instead be /usr, and
751 when building an extension it will be at the extensionpoint directory
752 somewhere below /app (for app extension) or /usr (for runtime
753 extensions).
754 Additionally the there will be (as needed, depending on what is
756 building) read-only mounts of the sdk at /usr, sdk extensions below
757 that, and the application at /app. No other filesystem access is
758 available.
759 Environment
761 The environment can be modified in several ways in the manifest, but
762 the default values are:
763 FLATPAK_ID
765 The id of the application currently building.
766 FLATPAK_ARCH
768 The architecture currently building.
769 FLATPAK_DEST
771 The path to where the current build should install into. This is
772 /app for application builds.
773 FLATPAK_BUILDER_N_JOBS
775 The number of jobs that flatpak-builder would normally use for make
776 -j. Defaults to ncpus unless the module disabled parallel make.
777 FLATPAK_BUILDER_BUILDDIR
779 The path to the build directory of the module currently building.
780 This is normally /run/build/$MODULE.
781 PATH
783 /app/bin:/usr/bin
784 LD_LIBRARY_PATH
786 /app/lib
787 PKG_CONFIG_PATH
789 /app/lib/pkgconfig:/app/share/pkgconfig:/usr/lib/pkgconfig:/usr/share/pkgconfig
790 ACLOCAL_PATH
792 /app/share/aclocal
793 C_INCLUDE_PATH
795 /app/include
796 CPLUS_INCLUDE_PATH
798 /app/include
799 LDFLAGS
801 -L/app/lib
802 LC_ALL
804 en_US.utf8
805 Permissions
807 Builds have the --allow=devel and --allow=multiarch permissions that
808 regular flatpak runs don't have by default. This allows limits the
809 syscall filtering that is normally done so development tools like
810 debuggers work. Otherwise the build sandbox is very limited, for
811 example there is no network access.
812
814 $ flatpak-builder my-app-dir manifest.json
815 Example manifest file:
817 {
819 "id": "org.test.TestApp",
820 "runtime": "org.freedesktop.Platform",
821 "runtime-version": "1.2",
822 "sdk": "org.freedesktop.Sdk",
823 "command": "test",
824 "clean": [ "/include", "*.la" ],
825 "build-options" : {
826 "cflags": "-O2 -g",
827 "cxxflags": "-O2 -g",
828 "env": {
829 "V": "1"
830 },
831 "arch": {
832 "x86_64": {
833 "cflags": "-O3 -g",
834 }
835 }
836 },
837 "modules": [
838 {
839 "name": "pygobject",
840 "config-opts": [ "--disable-introspection" ],
841 "sources": [
842 {
843 "type": "archive",
844 "url": "http://ftp.gnome.org/pub/GNOME/sources/pygobject/2.28/pygobject-2.28.6.tar.xz",
845 "sha256": "fb8a1d4f665130a125011659bd347c7339c944232163dbb9a34fd0686577adb8"
846 },
847 {
848 "type": "patch",
849 "path": "required-pygobject-fix.patch"
850 },
851 {
852 "type": "file",
853 "path": "pygobject-extra-file",
854 "dest-filename": "extra-file"
855 }
856 ]
857 },
858 {
859 "name": "babl",
860 "build-options" : { "cxxflags": "-O2 -g -std=c++11" },
861 "cleanup": [ "/bin" ],
862 "sources": [
863 {
864 "type": "git",
865 "url": "https://gitlab.gnome.org/GNOME/babl.git"
866 }
867 ]
868 },
869 {
870 "name": "testapp",
871 "sources": [
872 {
873 "type": "bzr",
874 "url": "lp:testapp"
875 }
876 ]
877 }
878 ]
879 }
880
882 flatpak-builder(1)
883flatpak FLATPAK MANIFEST(5)