diff --git a/doc/Makefile.am b/doc/Makefile.am index 917efd93a..ec94b09c2 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -50,6 +50,7 @@ man1 = \ $(NULL) man5 = \ + flatpak-manifest.5 \ flatpak-metadata.5 \ flatpak-flatpakrepo.5 \ flatpak-flatpakref.5 \ diff --git a/doc/flatpak-builder.xml b/doc/flatpak-builder.xml index fb9796d78..939b118da 100644 --- a/doc/flatpak-builder.xml +++ b/doc/flatpak-builder.xml @@ -102,512 +102,9 @@ - Manifest format - - Toplevel - - The top level of the json file describes global attributes of the application, how it can be - built, and the list of modules that need to be built. - - - These are the properties that are accepted: - - - - or (string) - A string defining the application id. - - - (string) - The branch of the application, defaults to master. - - - (string) - The name of the runtime that the application uses. - - - (string) - The version of the runtime that the application uses, defaults to master. - - - (string) - The name of the development runtime that the application builds with. - - - (string) - Initialize the (otherwise empty) writable /var in the build with a copy of this runtime. - - - (string) - Use this file as the base metadata file when finishing. - - - (string) - The filename or path to the main binary of the application. Note that this is really just a single file, not a commandline. If you want to pass arguments, install a shell script wrapper and use that as the command. - - - (boolean) - Build a new runtime instead of an application. - - - (boolean) - Separate out locale files and translations to an extension runtime. Defaults to true. - - - (string) - When building a runtime sdk, also create a platform based on it with this id. - - - (string) - The metadata file to use for the platform we create. - - - (boolean) - If true, use a writable copy of the sdk for /usr. - Defaults to true if --build-runtime is specified. - - - (boolean) - Run appstream-compose during cleanup phase. Defaults to true. - - - (array of strings) - Install these extra sdk extensions in /usr. - - - (array of strings) - Install these extra sdk extensions when creating the platform. - + Manifest - - (string) - Start with the files from the specified application. This can be - used to create applications that extend another application. - - - (string) - Use this specific version of the application specified in base. - If unspecified, this uses the value specified in branch - - - (array of strings) - Install these extra extensions from the base application when initializing - the application directory. - - - - (array of strings) - Add these tags to the metadata file. - - - (object) - Object specifying the build environment. See below for details. - - - (array of objects or string) - An array of objects specifying the modules to be built in order. - String members in the array are interpreted as the name of a separate json file that contains a module. - See below for details. - - - (array of strings) - An array of file patterns that should be removed at the end. - Patterns starting with / are taken to be full pathnames (without the /app prefix), otherwise they just match - the basename. - - - (array of strings) - An array of commandlines that are run during the cleanup phase. - - - (array of strings) - Extra files to clean up in the platform. - - - (array of strings) - An array of commandlines that are run during the cleanup phase of the platform. - - - (array of strings) - An array of arguments passed to the flatpak build-finish command. - - - (string) - Any desktop file with this name will be renamed to a name based on id during the cleanup phase. - - - (string) - Any appdata file with this name will be renamed to a name based on id during the cleanup phase. - - - (string) - Any icon with this name will be renamed to a name based on id during the cleanup phase. - - - (boolean) - If rename-icon is set, keep a copy of the old icon file. - - - (string) - This string will be prefixed to the Name key in the main application desktop file. - - - (string) - This string will be suffixed to the Name key in the main application desktop file. - - - - - - Build Options - - Build options specify the build environment of a module, and can be specified globally as - well as per-module. Options can also be specified on a per-architecture basis using the arch property. - - - These are the properties that are accepted: - - - - (string) - This is set in the environment variable CFLAGS during the build. Multiple specifications of this (in e.g. per-arch area) are concatinated with spaces inbetween. - - - (string) - This is set in the environment variable CXXFLAGS during the build. Multiple specifications of this (in e.g. per-arch area) are concatinated with spaces inbetween. - - - (string) - This is set in the environment variable LDFLAGS during the build. Multiple specifications of this (in e.g. per-arch area) are concatinated with spaces inbetween. - - - (string) - The build prefix for the modules (defaults to /app for - applications and /usr for runtimes). - - - (object) - This is a dictionary defining environment variables to be set during the build. - - - (array of strings) - This is an array containing extra options to pass to flatpak build. - - - (array of strings) - This is an array containing extra options to pass to configure. - - - (boolean) - If this is true (the default is false) then all ELF files will be stripped after install. - - - (boolean) - By default (if strip is not true) flatpak-builder extracts all debug info in ELF files to a separate files - and puts this in an extension. If you want to disable this, set no-debuginfo to true. - - - (object) - This is a dictionary defining for each arch a separate build options object that override the main one. - - - - - Module - - Each module specifies a source that has to be separately built and installed. It contains - the build options and a list of sources to download and extract before building. - - - Modules can be nested, in order to turn related modules on and off with a single key. - - - These are the properties that are accepted: - - - - (string) - The name of the module, used in e.g. build logs. The name is also used for constructing filenames and commandline arguments, therefore using spaces or '/' in this string is a bad idea. - - - (boolean) - If true, skip this module - - - (array of objects) - An array of objects defining sources that will be downloaded and extracted in order - - - (array of strings) - An array of options that will be passed to configure - - - (array of strings) - An array of arguments that will be passed to make - - - (array of strings) - An array of arguments that will be passed to make install - - - (boolean) - If true, remove the configure script before starting build - - - (boolean) - Ignore the existence of an autogen script - - - (boolean) - Don't call make with arguments to build in parallel - - - (boolean) - Don't run the make install (or equivalent) stage - - - (boolean) - Don't fix up the *.py[oc] header timestamps for ostree use. - - - (boolean) - Use cmake instead of configure (deprecated: use buildsystem instead) - - - (string) - Build system to use: autotools, cmake, cmake-ninja, meson, simple - - - (boolean) - Use a build directory that is separate from the source directory - - - (string) - Build inside this subdirectory of the extracted sources - - - (object) - A build options object that can override global options - - - (array of strings) - An array of commands to run during build (between make and make install if those are used). - This is primarily useful when using the "simple" buildsystem. - - - - (array of strings) - An array of shell commands that are run after the install phase. Can for example - clean up the install dir, or install extra files. - - - - (array of strings) - An array of file patterns that should be removed at the end. - Patterns starting with / are taken to be full pathnames (without the /app prefix), otherwise they just match - the basename. Note that any patterns will only match files installed by this module. - - - - (array of strings) - The way the builder works is that files in the install directory - are hard-links to the cached files, so you're not allowed to modify them in-place. - If you list a file in this then the hardlink will be broken and you can modify it. - This is a workaround, ideally installing files should replace files, not modify - existing ones. - - - (array of strings) - If non-empty, only build the module on the arches listed. - - - (array of strings) - Don't build on any of the arches listed. - - - (array of strings) - Extra files to clean up in the platform. - - - (array of objects or strings) - An array of objects specifying nested modules to be built before this one. - String members in the array are interpreted as names of a separate json file that contains a module. - - - - - Sources - - These contain a pointer to the source that will be extracted into the source directory before - the build starts. They can be of several types, distinguished by the type property. - - - All sources - - - (array of strings) - If non-empty, only build the module on the arches listed. - - - (array of strings) - Don't build on any of the arches listed. - - - (string) - Directory inside the source dir where this source will be extracted. - - - - - Archive sources (tar, zip) - - - - "archive" - - - (string) - The path of the archive - - - (string) - The URL of a remote archive that will be downloaded. This overrides path if both are specified. - - - (string) - The sha256 checksum of the file, verified after download - - - (integer) - The number of initial pathname components to strip during extraction. Defaults to 1. - - - - - Git sources - - - - "git" - - - (string) - The path to a local checkout of the git repository. Due to how git-clone works, this will be much faster than specifying a URL of file:///... - - - (string) - URL of the git repository. This overrides path if both are specified. - - - (string) - The branch/tag/commit to use from the git repository - - - - - Bzr sources - - - - "bzr" - - - (string) - URL of the bzr repository - - - (string) - A specific revision to use in the branch - - - - - File sources - - - - "file" - - - (string) - The path of a local file that will be copied into the source dir - - - (string) - The URL of a remote file that will be downloaded and copied into the source dir. This overrides path if both are specified. - - - (string) - The sha256 checksum of the file, verified after download. This is optional for local files. - - - (string) - Filename to use inside the source dir, default to the basename of path. - - - - - Script sources - - This is a way to create a shell (/bin/sh) script from an inline set of commands. - - - - - "script" - - - (array of strings) - An array of shell commands that will be put in a shellscript file - - - (string) - Filename to use inside the source dir, default to the basename of path. - - - - - Shell sources - - This is a way to create/modify the sources by running shell commands. - - - - - "shell" - - - (array of strings) - An array of shell commands that will be run during source extraction - - - - - Patch sources - - - - "patch" - - - (string) - The path of a patch file that will be applied in the source dir - - - (integer) - The value of the -p argument to patch, defaults to 1. - - - (boolean) - Whether to use "git apply" rather than "patch" to apply the patch, required when the patch file contains binary diffs. - - - (array of strings) - Extra options to pass to the patch command. - - - - + The manifest file is a json file whose format is described in detail in its own manual page. @@ -1004,6 +501,7 @@ flatpak1, + flatpak-manifest5 flatpak-build-init1, flatpak-build1, flatpak-build-finish1, diff --git a/doc/flatpak-manifest.xml b/doc/flatpak-manifest.xml new file mode 100644 index 000000000..b78959328 --- /dev/null +++ b/doc/flatpak-manifest.xml @@ -0,0 +1,638 @@ + + + + + + + flatpak manifest + flatpak + + + + Developer + Alexander + Larsson + alexl@redhat.com + + + + + + flatpak manifest + 5 + + + + flatpak-manifest + Information for building an application + + + + Description + + + Flatpak uses manifest, or recipe, files in a json format to describe how an + application and its bundled dependencies can be built from sources. The manifest + gets used by flatpak-builder. + + + + + File format + + + The top level of the json file describes global attributes of the application, how + it can be built, and the list of modules that need to be built. + + + + Toplevel properties + + These are the properties that are accepted: + + + + or (string) + A string defining the application id. + + + (string) + The branch of the application, defaults to master. + + + (string) + The name of the runtime that the application uses. + + + (string) + The version of the runtime that the application uses, defaults to master. + + + (string) + The name of the development runtime that the application builds with. + + + (string) + Initialize the (otherwise empty) writable /var in the build with a copy of this runtime. + + + (string) + Use this file as the base metadata file when finishing. + + + (string) + The filename or path to the main binary of the application. Note that this is really just a single file, not a commandline. If you want to pass arguments, install a shell script wrapper and use that as the command. + + + (boolean) + Build a new runtime instead of an application. + + + (boolean) + Separate out locale files and translations to an extension runtime. Defaults to true. + + + (string) + When building a runtime sdk, also create a platform based on it with this id. + + + (string) + The metadata file to use for the platform we create. + + + (boolean) + If true, use a writable copy of the sdk for /usr. + Defaults to true if --build-runtime is specified. + + + (boolean) + Run appstream-compose during cleanup phase. Defaults to true. + + + (array of strings) + Install these extra sdk extensions in /usr. + + + (array of strings) + Install these extra sdk extensions when creating the platform. + + + + (string) + Start with the files from the specified application. This can be + used to create applications that extend another application. + + + (string) + Use this specific version of the application specified in base. + If unspecified, this uses the value specified in branch + + + (array of strings) + Install these extra extensions from the base application when initializing + the application directory. + + + + (array of strings) + Add these tags to the metadata file. + + + (object) + Object specifying the build environment. See below for details. + + + (array of objects or string) + An array of objects specifying the modules to be built in order. + String members in the array are interpreted as the name of a separate json file that contains a module. + See below for details. + + + (array of strings) + An array of file patterns that should be removed at the end. + Patterns starting with / are taken to be full pathnames (without the /app prefix), otherwise they just match + the basename. + + + (array of strings) + An array of commandlines that are run during the cleanup phase. + + + (array of strings) + Extra files to clean up in the platform. + + + (array of strings) + An array of commandlines that are run during the cleanup phase of the platform. + + + (array of strings) + An array of arguments passed to the flatpak build-finish command. + + + (string) + Any desktop file with this name will be renamed to a name based on id during the cleanup phase. + + + (string) + Any appdata file with this name will be renamed to a name based on id during the cleanup phase. + + + (string) + Any icon with this name will be renamed to a name based on id during the cleanup phase. + + + (boolean) + If rename-icon is set, keep a copy of the old icon file. + + + (string) + This string will be prefixed to the Name key in the main application desktop file. + + + (string) + This string will be suffixed to the Name key in the main application desktop file. + + + + + + Build Options + + Build options specify the build environment of a module, and can be specified globally as + well as per-module. Options can also be specified on a per-architecture basis using the arch property. + + + These are the properties that are accepted: + + + + (string) + This is set in the environment variable CFLAGS during the build. Multiple specifications of this (in e.g. per-arch area) are concatinated with spaces inbetween. + + + (string) + This is set in the environment variable CXXFLAGS during the build. Multiple specifications of this (in e.g. per-arch area) are concatinated with spaces inbetween. + + + (string) + This is set in the environment variable LDFLAGS during the build. Multiple specifications of this (in e.g. per-arch area) are concatinated with spaces inbetween. + + + (string) + The build prefix for the modules (defaults to /app for + applications and /usr for runtimes). + + + (object) + This is a dictionary defining environment variables to be set during the build. + + + (array of strings) + This is an array containing extra options to pass to flatpak build. + + + (array of strings) + This is an array containing extra options to pass to configure. + + + (boolean) + If this is true (the default is false) then all ELF files will be stripped after install. + + + (boolean) + By default (if strip is not true) flatpak-builder extracts all debug info in ELF files to a separate files + and puts this in an extension. If you want to disable this, set no-debuginfo to true. + + + (object) + This is a dictionary defining for each arch a separate build options object that override the main one. + + + + + Module + + Each module specifies a source that has to be separately built and installed. It contains + the build options and a list of sources to download and extract before building. + + + Modules can be nested, in order to turn related modules on and off with a single key. + + + These are the properties that are accepted: + + + + (string) + The name of the module, used in e.g. build logs. The name is also used for constructing filenames and commandline arguments, therefore using spaces or '/' in this string is a bad idea. + + + (boolean) + If true, skip this module + + + (array of objects) + An array of objects defining sources that will be downloaded and extracted in order + + + (array of strings) + An array of options that will be passed to configure + + + (array of strings) + An array of arguments that will be passed to make + + + (array of strings) + An array of arguments that will be passed to make install + + + (boolean) + If true, remove the configure script before starting build + + + (boolean) + Ignore the existence of an autogen script + + + (boolean) + Don't call make with arguments to build in parallel + + + (boolean) + Don't run the make install (or equivalent) stage + + + (boolean) + Don't fix up the *.py[oc] header timestamps for ostree use. + + + (boolean) + Use cmake instead of configure (deprecated: use buildsystem instead) + + + (string) + Build system to use: autotools, cmake, cmake-ninja, meson, simple + + + (boolean) + Use a build directory that is separate from the source directory + + + (string) + Build inside this subdirectory of the extracted sources + + + (object) + A build options object that can override global options + + + (array of strings) + An array of commands to run during build (between make and make install if those are used). + This is primarily useful when using the "simple" buildsystem. + + + + (array of strings) + An array of shell commands that are run after the install phase. Can for example + clean up the install dir, or install extra files. + + + + (array of strings) + An array of file patterns that should be removed at the end. + Patterns starting with / are taken to be full pathnames (without the /app prefix), otherwise they just match + the basename. Note that any patterns will only match files installed by this module. + + + + (array of strings) + The way the builder works is that files in the install directory + are hard-links to the cached files, so you're not allowed to modify them in-place. + If you list a file in this then the hardlink will be broken and you can modify it. + This is a workaround, ideally installing files should replace files, not modify + existing ones. + + + (array of strings) + If non-empty, only build the module on the arches listed. + + + (array of strings) + Don't build on any of the arches listed. + + + (array of strings) + Extra files to clean up in the platform. + + + (array of objects or strings) + An array of objects specifying nested modules to be built before this one. + String members in the array are interpreted as names of a separate json file that contains a module. + + + + + Sources + + These contain a pointer to the source that will be extracted into the source directory before + the build starts. They can be of several types, distinguished by the type property. + + + All sources + + + (array of strings) + If non-empty, only build the module on the arches listed. + + + (array of strings) + Don't build on any of the arches listed. + + + (string) + Directory inside the source dir where this source will be extracted. + + + + + Archive sources (tar, zip) + + + + "archive" + + + (string) + The path of the archive + + + (string) + The URL of a remote archive that will be downloaded. This overrides path if both are specified. + + + (string) + The sha256 checksum of the file, verified after download + + + (integer) + The number of initial pathname components to strip during extraction. Defaults to 1. + + + + + Git sources + + + + "git" + + + (string) + The path to a local checkout of the git repository. Due to how git-clone works, this will be much faster than specifying a URL of file:///... + + + (string) + URL of the git repository. This overrides path if both are specified. + + + (string) + The branch/tag/commit to use from the git repository + + + + + Bzr sources + + + + "bzr" + + + (string) + URL of the bzr repository + + + (string) + A specific revision to use in the branch + + + + + File sources + + + + "file" + + + (string) + The path of a local file that will be copied into the source dir + + + (string) + The URL of a remote file that will be downloaded and copied into the source dir. This overrides path if both are specified. + + + (string) + The sha256 checksum of the file, verified after download. This is optional for local files. + + + (string) + Filename to use inside the source dir, default to the basename of path. + + + + + Script sources + + This is a way to create a shell (/bin/sh) script from an inline set of commands. + + + + + "script" + + + (array of strings) + An array of shell commands that will be put in a shellscript file + + + (string) + Filename to use inside the source dir, default to the basename of path. + + + + + Shell sources + + This is a way to create/modify the sources by running shell commands. + + + + + "shell" + + + (array of strings) + An array of shell commands that will be run during source extraction + + + + + Patch sources + + + + "patch" + + + (string) + The path of a patch file that will be applied in the source dir + + + (integer) + The value of the -p argument to patch, defaults to 1. + + + (boolean) + Whether to use "git apply" rather than "patch" to apply the patch, required when the patch file contains binary diffs. + + + (array of strings) + Extra options to pass to the patch command. + + + + + + + + Examples + + + $ flatpak-builder my-app-dir manifest.json + + + + Example manifest file: + + +{ + "id": "org.test.TestApp", + "runtime": "org.freedesktop.Platform", + "runtime-version": "1.2", + "sdk": "org.freedesktop.Sdk", + "command": "test", + "clean": [ "/include", "*.la" ], + "build-options" : { + "cflags": "-O2 -g", + "cxxflags": "-O2 -g", + "env": { + "V": "1" + }, + "arch": { + "x86_64": { + "cflags": "-O3 -g", + } + } + }, + "modules": [ + { + "name": "pygobject", + "config-opts": [ "--disable-introspection" ], + "sources": [ + { + "type": "archive", + "url": "http://ftp.gnome.org/pub/GNOME/sources/pygobject/2.28/pygobject-2.28.6.tar.xz", + "sha256": "fb8a1d4f665130a125011659bd347c7339c944232163dbb9a34fd0686577adb8" + }, + { + "type": "patch", + "path": "required-pygobject-fix.patch" + }, + { + "type": "file", + "path": "pygobject-extra-file", + "dest-filename": "extra-file" + } + ] + }, + { + "name": "babl", + "build-options" : { "cxxflags": "-O2 -g -std=c++11" }, + "cleanup": [ "/bin" ], + "sources": [ + { + "type": "git", + "url": "git://git.gnome.org/babl" + } + ] + }, + { + "name": "testapp", + "sources": [ + { + "type": "bzr", + "url": "lp:testapp" + } + ] + } + ] +} + + + + + + See also + + + flatpak-builder1 + + + + +