1FLATPAK MANIFEST(5)            flatpak manifest            FLATPAK MANIFEST(5)
2
3
4

NAME

6       flatpak-manifest - Information for building an application
7

DESCRIPTION

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

FILE FORMAT

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
18   Toplevel properties
19       These are the properties that are accepted:
20
21       id or app-id (string)
22           A string defining the application id.
23
24       branch (string)
25           The branch of the application, defaults to master.
26
27       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
35       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
48       runtime (string)
49           The name of the runtime that the application uses.
50
51       runtime-version (string)
52           The version of the runtime that the application uses, defaults to
53           master.
54
55       sdk (string)
56           The name of the development runtime that the application builds
57           with.
58
59       var (string)
60           Initialize the (otherwise empty) writable /var in the build with a
61           copy of this runtime.
62
63       metadata (string)
64           Use this file as the base metadata file when finishing.
65
66       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
72       build-runtime (boolean)
73           Build a new runtime instead of an application.
74
75       build-extension (boolean)
76           Build an extension.
77
78       separate-locales (boolean)
79           Separate out locale files and translations to an extension runtime.
80           Defaults to true.
81
82       id-platform (string)
83           When building a runtime sdk, also create a platform based on it
84           with this id.
85
86       metadata-platform (string)
87           The metadata file to use for the platform we create.
88
89       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
93       appstream-compose (boolean)
94           Run appstream-compose during cleanup phase. Defaults to true.
95
96       sdk-extensions (array of strings)
97           Install these extra sdk extensions in /usr.
98
99       platform-extensions (array of strings)
100           Install these extra sdk extensions when creating the platform.
101
102       base (string)
103           Start with the files from the specified application. This can be
104           used to create applications that extend another application.
105
106       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
110       base-extensions (array of strings)
111           Install these extra extensions from the base application when
112           initializing the application directory.
113
114       inherit-extensions (array of strings)
115           Inherit these extra extensions points from the base application or
116           sdk when finishing the build.
117
118       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
123       tags (array of strings)
124           Add these tags to the metadata file.
125
126       build-options (object)
127           Object specifying the build environment. See below for details.
128
129       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
135       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
139       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
144       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
149       cleanup-commands (array of strings)
150           An array of commandlines that are run during the cleanup phase.
151
152       cleanup-platform (array of strings)
153           Extra files to clean up in the platform.
154
155       cleanup-platform-commands (array of strings)
156           An array of commandlines that are run during the cleanup phase of
157           the platform.
158
159       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
165       finish-args (array of strings)
166           An array of arguments passed to the flatpak build-finish command.
167
168       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
172       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
176       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
181       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
187       copy-icon (boolean)
188           If rename-icon is set, keep a copy of the old icon file.
189
190       desktop-file-name-prefix (string)
191           This string will be prefixed to the Name key in the main
192           application desktop file.
193
194       desktop-file-name-suffix (string)
195           This string will be suffixed to the Name key in the main
196           application desktop file.
197
198   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
203       These are the properties that are accepted:
204
205       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
210       cflags-override (boolean)
211           If this is true, clear cflags from previous build options before
212           adding it from these options.
213
214       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
219       cppflags-override (boolean)
220           If this is true, clear cppflags from previous build options before
221           adding it from these options.
222
223       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
228       cxxflags-override (boolean)
229           If this is true, clear cxxflags from previous build options before
230           adding it from these options.
231
232       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
237       ldflags-override (boolean)
238           If this is true, clear ldflags from previous build options before
239           adding it from these options.
240
241       prefix (string)
242           The build prefix for the modules (defaults to /app for applications
243           and /usr for runtimes).
244
245       libdir (string)
246           The build libdir for the modules (defaults to /app/lib for
247           applications and /usr/lib for runtimes).
248
249       append-path (string)
250           This will get appended to PATH in the build environment (with an
251           leading colon if needed).
252
253       prepend-path (string)
254           This will get prepended to PATH in the build environment (with an
255           trailing colon if needed).
256
257       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
261       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
265       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
269       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
273       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
278       build-args (array of strings)
279           This is an array containing extra options to pass to flatpak build.
280
281       test-args (array of strings)
282           Similar to build-args but affects the tests, not the normal build.
283
284       config-opts (array of strings)
285           This is an array containing extra options to pass to configure.
286
287       make-args (array of strings)
288           An array of extra arguments that will be passed to make
289
290       make-install-args (array of strings)
291           An array of extra arguments that will be passed to make install
292
293       strip (boolean)
294           If this is true (the default is false) then all ELF files will be
295           stripped after install.
296
297       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
302       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
307       arch (object)
308           This is a dictionary defining for each arch a separate build
309           options object that override the main one.
310
311   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
316       These are the properties that are accepted:
317
318       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
323       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
328       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
333       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
339   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
344       Modules can be nested, in order to turn related modules on and off with
345       a single key.
346
347       These are the properties that are accepted:
348
349       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
354       disabled (boolean)
355           If true, skip this module
356
357       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
363       config-opts (array of strings)
364           An array of options that will be passed to configure
365
366       make-args (array of strings)
367           An array of arguments that will be passed to make
368
369       make-install-args (array of strings)
370           An array of arguments that will be passed to make install
371
372       rm-configure (boolean)
373           If true, remove the configure script before starting build
374
375       no-autogen (boolean)
376           Ignore the existence of an autogen script
377
378       no-parallel-make (boolean)
379           Don't call make with arguments to build in parallel
380
381       install-rule (string)
382           Name of the rule passed to make for the install phase, default is
383           install
384
385       no-make-install (boolean)
386           Don't run the make install (or equivalent) stage
387
388       no-python-timestamp-fix (boolean)
389           Don't fix up the *.py[oc] header timestamps for ostree use.
390
391       cmake (boolean)
392           Use cmake instead of configure (deprecated: use buildsystem
393           instead)
394
395       buildsystem (string)
396           Build system to use: autotools, cmake, cmake-ninja, meson, simple,
397           qmake
398
399       builddir (boolean)
400           Use a build directory that is separate from the source directory
401
402       subdir (string)
403           Build inside this subdirectory of the extracted sources
404
405       build-options (object)
406           A build options object that can override global options
407
408       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
414       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
418       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
424       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
431       only-arches (array of strings)
432           If non-empty, only build the module on the arches listed.
433
434       skip-arches (array of strings)
435           Don't build on any of the arches listed.
436
437       cleanup-platform (array of strings)
438           Extra files to clean up in the platform.
439
440       run-tests (boolean)
441           If true this will run the tests after installing.
442
443       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
447       test-commands (array of strings)
448           Array of commands to run during the tests.
449
450       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
455   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
460       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
465       All sources
466           only-arches (array of strings)
467               If non-empty, only build the module on the arches listed.
468
469           skip-arches (array of strings)
470               Don't build on any of the arches listed.
471
472           dest (string)
473               Directory inside the source dir where this source will be
474               extracted.
475
476       Archive sources (tar, zip)
477           type
478               "archive"
479
480           path (string)
481               The path of the archive
482
483           url (string)
484               The URL of a remote archive that will be downloaded. This
485               overrides path if both are specified.
486
487           mirror-urls (array of strings)
488               A list of alternative urls that are used if the main url fails.
489
490           git-init (boolean)
491               Whether to initialise the repository as a git repository.
492
493           md5 (string)
494               The md5 checksum of the file, verified after download
495
496               Note that md5 is no longer considered a safe checksum, we
497               recommend you use at least sha256.
498
499           sha1 (string)
500               The sha1 checksum of the file, verified after download
501
502               Note that sha1 is no longer considered a safe checksum, we
503               recommend you use at least sha256.
504
505           sha256 (string)
506               The sha256 checksum of the file, verified after download
507
508           sha512 (string)
509               The sha512 checksum of the file, verified after download
510
511           strip-components (integer)
512               The number of initial pathname components to strip during
513               extraction. Defaults to 1.
514
515           dest-filename (string)
516               Filename to for the downloaded file, defaults to the basename
517               of url.
518
519       Git sources
520           type
521               "git"
522
523           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
528           url (string)
529               URL of the git repository. This overrides path if both are
530               specified.
531
532           branch (string)
533               The branch to use from the git repository
534
535           tag (string)
536               The tag to use from the git repository
537
538           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
544           disable-fsckobjects (boolean)
545               Don't use transfer.fsckObjects=1 to mirror git repository. This
546               may be needed for some (broken) repositories.
547
548           disable-shallow-clone (boolean)
549               Don't optimize by making a shallow clone when downloading the
550               git repo.
551
552       Bzr sources
553           type
554               "bzr"
555
556           url (string)
557               URL of the bzr repository
558
559           revision (string)
560               A specific revision to use in the branch
561
562       Svn sources
563           type
564               "svn"
565
566           url (string)
567               URL of the svn repository, including branch/tag part
568
569           revision (string)
570               A specific revision number to use
571
572       Directory sources
573           type
574               "dir"
575
576           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
581           skip (array of strings)
582               Source files to ignore in the directory.
583
584       File sources
585           type
586               "file"
587
588           path (string)
589               The path of a local file that will be copied into the source
590               dir
591
592           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
596           mirror-urls (array of strings)
597               A list of alternative urls that are used if the main url fails.
598
599           md5 (string)
600               The md5 checksum of the file, verified after download. This is
601               optional for local files.
602
603               Note that md5 is no longer considered a safe checksum, we
604               recommend you use at least sha256.
605
606           sha1 (string)
607               The sha1 checksum of the file, verified after download. This is
608               optional for local files.
609
610               Note that sha1 is no longer considered a safe checksum, we
611               recommend you use at least sha256.
612
613           sha256 (string)
614               The sha256 checksum of the file, verified after download. This
615               is optional for local files.
616
617           sha512 (string)
618               The sha512 checksum of the file, verified after download. This
619               is optional for local files.
620
621           dest-filename (string)
622               Filename to use inside the source dir, default to the basename
623               of path.
624
625       Script sources
626           This is a way to create a shell (/bin/sh) script from an inline set
627           of commands.
628
629           type
630               "script"
631
632           commands (array of strings)
633               An array of shell commands that will be put in a shellscript
634               file
635
636           dest-filename (string)
637               Filename to use inside the source dir, default to the basename
638               of path.
639
640       Shell sources
641           This is a way to create/modify the sources by running shell
642           commands.
643
644           type
645               "shell"
646
647           commands (array of strings)
648               An array of shell commands that will be run during source
649               extraction
650
651       Patch sources
652           type
653               "patch"
654
655           path (string)
656               The path of a patch file that will be applied in the source dir
657
658           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
662           strip-components (integer)
663               The value of the -p argument to patch, defaults to 1.
664
665           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
669           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
674           options (array of strings)
675               Extra options to pass to the patch command.
676
677       Extra data sources
678           type
679               "extra-data"
680
681           filename (string)
682               The name to use for the downloaded extra data
683
684           url (string)
685               The url to the extra data.
686
687           sha256 (string)
688               The sha256 of the extra data.
689
690           size (number)
691               The size of the extra data.
692
693           installed-size (string)
694               The extra installed size this adds to the app (optional).
695

BUILD ENVIRONMENT

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
703   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
713       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
720       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
725   Environment
726       The environment can be modified in several ways in the manifest, but
727       the default values are:
728
729       FLATPAK_ID
730           The id of the application currently building.
731
732       FLATPAK_ARCH
733           The architecture currently building.
734
735       FLATPAK_DEST
736           The path to where the current build should install into. This is
737           /app for application builds.
738
739       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
743       FLATPAK_BUILDER_BUILDDIR
744           The path to the build directory of the module currently building.
745           This is normally /run/build/$MODULE.
746
747       PATH
748           /app/bin:/usr/bin
749
750       LD_LIBRARY_PATH
751           /app/lib
752
753       PKG_CONFIG_PATH
754           /app/lib/pkgconfig:/app/share/pkgconfig:/usr/lib/pkgconfig:/usr/share/pkgconfig
755
756       ACLOCAL_PATH
757           /app/share/aclocal
758
759       C_INCLUDE_PATH
760           /app/include
761
762       CPLUS_INCLUDE_PATH
763           /app/include
764
765       LDFLAGS
766           -L/app/lib
767
768       LC_ALL
769           en_US.utf8
770
771   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

EXAMPLES

779       $ flatpak-builder my-app-dir manifest.json
780
781       Example manifest file:
782
783           {
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

SEE ALSO

847       flatpak-builder(1)
848
849
850
851flatpak                                                    FLATPAK MANIFEST(5)
Impressum