flatpak-metadata

title: flatpak-metadata(5)

text:
# flatpak-metadata(5)

## NAME
flatpak-metadata - Information about an application or runtime

## DESCRIPTION
Flatpak uses metadata files to describe applications and runtimes. The metadata file for a deployed application or runtime is placed in the toplevel deploy directory. For example, the metadata for the locally installed application org.gnome.Calculator is in ~/.local/share/flatpak/app/org.gnome.Calculator/current/active/metadata.

Most aspects of the metadata configuration can be overridden when launching applications, either temporarily via options of the flatpak run command, or permanently with the flatpak override command.

A metadata file describing the effective configuration is available inside the running sandbox at /.flatpak-info. For compatibility with older Flatpak versions, /run/user/$UID/flatpak-info is a symbolic link to the same file.

## FILE FORMAT
The metadata file is using the same .ini file format that is used for systemd unit files or application .desktop files.

### [Application] or [Runtime]
Metadata for applications starts with an [Application] group, metadata for runtimes with a [Runtime] group.

The following keys can be present in these groups:

name (string)

The name of the application or runtime. This key is mandatory.

runtime (string)

The fully qualified name of the runtime that is used by the application. This key is mandatory for applications.

sdk (string)

The fully qualified name of the sdk that matches the runtime. Available since 0.1.

command (string)

The command to run. Only relevant for applications. Available since 0.1.

required-flatpak (string list)

The required version of Flatpak to run this application or runtime. For applications, this was available since 0.8.0. For runtimes, this was available since 0.9.1, and backported to 0.8.3 for the 0.8.x branch. Flatpak after version 1.4.3 and 1.2.5 support multiple versions here. This can be useful if you need to support features that are backported to a previous stable series. For example if you want to use a feature added in 1.6.0 that was also backported to 1.4.4 you would use 1.6.0;1.4.4;. Note that older versions of flatpak will just use the first element in the list, so make that the largest version.

tags (string list)

Tags to include in AppStream XML. Typical values in use on Flathub include beta, stable, proprietary and upstream-maintained. Available since 0.4.12.

### [Context]
This group determines various system resources that may be shared with the application when it is run in a flatpak sandbox.

Conditional Permissions

Some permissions (such as sockets and devices) support conditional grants, where access is only provided when specific runtime conditions are met. This allows applications to adapt to different system capabilities and session types. Available since 1.17.

Conditional permissions use the syntax if:PERMISSION:CONDITION in the metadata file. For example, if:wayland:has-wayland grants Wayland socket access only when running in a Wayland session.

The following conditions are supported:

true

Always evaluates to true.

false

Always evaluates to false.

has-input-device

True if this version of Flatpak supports the input device permission. This is always true in Flatpak 1.15.6 and later, and can be used to provide fallback behavior for older Flatpak versions.

has-wayland

True if the current desktop session supports Wayland.

has-usb-device

True if this version of Flatpak supports the usb device permission. This is always true in Flatpak 1.16.0 and later, and can be used to provide fallback behavior for older Flatpak versions.

has-usb-portal

True if the current desktop session supports the USB Portal.

Conditions can be negated by prefixing with !. For example, if:x11:!has-wayland grants X11 socket access only when NOT running in a Wayland session.

Multiple conditional permissions can be specified for the same resource. If any condition matches, the permission is granted (OR logic). For example:

```
sockets=wayland;if:x11:!has-wayland;if:x11:false
```

For backward compatibility with older Flatpak versions, conditional permissions can be combined with unconditional grants:

```
sockets=x11;if:x11:!has-wayland;
```

Older Flatpak versions will grant X11 access unconditionally (seeing only x11), while newer versions recognize the conditional syntax and grant X11 access only when not in Wayland sessions.

To explicitly deny a permission that might be granted at a lower layer (such as from the runtime or a global override), prefix the permission name with !:

```
sockets=!x11;
```

This denial can be combined with conditional grants to remove unconditional access while allowing conditional access:

```
sockets=!x11;x11;if:x11:!has-wayland;
```

This denies unconditional X11 access, but allows X11 access conditionally when not running in a Wayland session. The seemingly contradictory !x11 and x11 ensures backward compatibility: older Flatpak versions see the final x11 grant, while newer versions understand the conditional logic.

All keys in this group (and the group itself) are optional.

The keys supported in this group are:

shared (list)

List of subsystems to share with the host system. Possible subsystems: network, ipc. Available since 0.3. This option supports conditional permissions. See Conditional Permissions for details on how to share subsystem access conditionally based on runtime conditions.

sockets (list)

List of well-known sockets to make available in the sandbox. Possible sockets: x11, wayland, fallback-x11, pulseaudio, session-bus, system-bus, ssh-auth, pcsc, cups, gpg-agent, inherit-wayland-socket. When making a socket available, flatpak also sets well-known environment variables like DISPLAY or DBUS_SYSTEM_BUS_ADDRESS to let the application find sockets that are not in a fixed location. Available since 0.3. This option supports conditional permissions. See Conditional Permissions for details on how to grant socket access conditionally based on runtime conditions.

devices (list)

List of devices to make available in the sandbox. This just expose the devices nodes, it doesn't grant any permission that the user doesn't already have. Possible values: dri

GPU graphics and compute (/dev/dri), including vendor specific render and compute devices. Available since 0.3.

input

Input devices (/dev/input). Available since 1.15.6.

usb

USB device bus (all device nodes below /dev/bus/usb). Available since 1.15.11.

kvm

Virtualization (/dev/kvm). Available since 0.6.12.

all

All device nodes in /dev, but not /dev/shm (which is separately specified). Available since 0.6.6.

shm

Access to the host /dev/shm (/dev/shm). Available since 1.6.1.

This option supports conditional permissions. See Conditional Permissions for details on how to grant device access conditionally based on runtime conditions.

filesystems (list)

List of filesystem subsets to make available to the application. Possible values: home

The entire home directory. Available since 0.3.

home/path

Alias for ~/path Available since 1.10. For better compatibility with older Flatpak versions, prefer to write this as ~/path.

host

The entire host file system, except for directories that are handled specially by Flatpak. In particular, this shares /home, /media, /opt, /run/media and /srv if they exist. /dev is not shared: use devices=all; instead.

Parts of /sys are always shared. This option does not make additional files in /sys available.

Additionally, this keyword provides all of the same directories in /run/host as the host-os and host-etc keywords. If this keyword is used in conjunction with one of the host- keywords, whichever access level is higher (more permissive) will be used for the directories in /run/host: for example, host:rw;host-os:ro; is equivalent to host:rw;.

These other reserved directories are currently excluded: /app, /bin, /boot, /efi, /etc, /lib, /lib32, /lib64, /proc, /root, /run, /sbin, /tmp, /usr, /var.

Available since 0.3.

host-os

The host operating system's libraries, executables and static data from /usr and the related directories /bin, /lib, /lib32, /lib64, /sbin. Additionally, this keyword provides access to a subset of /etc that is associated with packaged libraries and executables, even if the host-etc keyword was not used: /etc/ld.so.cache, (used by the dynamic linker) and /etc/alternatives (on operating systems that use it, such as Debian). To avoid conflicting with the Flatpak runtime, these are mounted in the sandbox at /run/host/usr, /run/host/etc/ld.so.cache and so on.

Available since 1.7.

host-etc

The host operating system's configuration from /etc. To avoid conflicting with the Flatpak runtime, this is mounted in the sandbox at /run/host/etc.

Available since 1.7.

host-root

The complete host operating system. To avoid conflicting with the Flatpak runtime, this is mounted in the sandbox at /run/host/root.

This permission is only intended to be used as a last resort when there is no possible alternative with other filesystem permissions for applications that need the entire root filesystem of the host.

Please note that following symlinks under /run/host/root naively will result in a wrong path. For example, using realpath() is wrong. Instead, applications will have to implement some way of following symlinks in a way that behaves as if it were chroot'd into /run/host/root.

There are a few ways to do this. Modern kernels support the openat2()[1] call with RESOLVE_IN_ROOT. For a more portable solution with support for older kernels, see the implementation from the steam-runtime-tools[2] as an example.

Available since 1.17.

xdg-desktop, xdg-documents, xdg-download, xdg-music, xdg-pictures, xdg-public-share, xdg-videos, xdg-templates

freedesktop.org special directories[3]. Available since 0.3.

xdg-desktop/path, xdg-documents/path, etc.

Subdirectories of freedesktop.org special directories. Available since 0.4.13.

xdg-cache, xdg-config, xdg-data

Directories defined by the freedesktop.org Base Directory Specification[4]. Available since 0.6.14.

xdg-cache/path, xdg-config/path, xdg-data/path

Subdirectories of directories defined by the freedesktop.org Base Directory Specification. Available since 0.6.14.

xdg-run/path

Subdirectories of the XDG_RUNTIME_DIR defined by the freedesktop.org Base Directory Specification. Note that xdg-run on its own is not supported. Available since 0.4.13.

/path

An arbitrary absolute path. Available since 0.3.

~/path

An arbitrary path relative to the home directory. Available since 0.3.

~

The same as home. Available since 1.10. For better compatibility with older Flatpak versions, prefer to write this as home.

One of the above followed by :ro

Make the given directory available read-only.

One of the above followed by :rw

Make the given directory available read/write. This is the default.

One of the above followed by :create

Make the given directory available read/write, and create it if it does not already exist.

persistent (list)

List of homedir-relative paths to make available at the corresponding path in the per-application home directory, allowing the locations to be used for persistent data when the application does not have access to the real homedir. For instance making ".myapp" persistent would make "~/.myapp" in the sandbox a bind mount to "~/.var/app/org.my.App/.myapp", thus allowing an unmodified application to save data in the per-application location. Available since 0.3.

features (list)

List of features available or unavailable to the application, currently from the following list: devel

Allow system calls used by development-oriented tools such as perf, strace and gdb. Available since 0.6.10.

multiarch

Allow running multilib/multiarch binaries, for example i386 binaries in an x86_64 environment. Available since 0.6.12.

bluetooth

Allow the application to use bluetooth (AF_BLUETOOTH) sockets. Note, for bluetooth to fully work you must also have network access. Available since 0.11.8.

canbus

Allow the application to use canbus (AF_CAN) sockets. Note, for this work you must also have network access. Available since 1.0.3.

per-app-dev-shm

Share a single instance of /dev/shm between all instances of this application run by the same user ID, including sub-sandboxes. If the application has the shm device permission in its devices list, then this feature flag is ignored. Available since 1.12.0.

A feature can be prefixed with ! to indicate the absence of that feature, for example !devel if development and debugging are not allowed.

This option supports conditional permissions. See Conditional Permissions for details on how to allow features based conditionally on runtime conditions.

unset-environment (list)

A list of names of environment variables to unset. Note that environment variables to set to a value (possibly empty) appear in the [Environment] group instead.

### [Instance]
This group only appears in /.flatpak-info for a running app, and not in the metadata files written by application authors. It is filled in by Flatpak itself.

instance-id (string)

The ID of the running instance. This number is used as the name of the directory in XDG_RUNTIME_DIR/.flatpak where Flatpak stores information about this instance.

instance-path (string)

The absolute path on the host system of the app's persistent storage area in $HOME/.var.

app-path (string)

The absolute path on the host system of the app's app files, as mounted at /app inside the container. Available since 0.6.10. Since 1.12.0, if flatpak run was run with the --app-path option, this key gives the absolute path of whatever files were mounted on /app, even if that differs from the app's normal app files.

If flatpak run was run with --app-path= (resulting in an empty directory being mounted on /app), the value is set to the empty string.

original-app-path (string)

If flatpak run was run with the --app-path option, this key gives the absolute path of the app's original files, as mounted at /run/parent/app inside the container. Available since 1.12.0. If this key is missing, the app files are given by app-path.

app-commit (string)

The commit ID of the application that is running. The filename of a deployment of this commit can be found in original-app-path if present, or app-path otherwise.

app-extensions (list of strings)

A list of app extensions that are mounted into the running instance. The format for each list item is EXTENSION_ID=COMMIT. If original-app-path is present, the extensions are mounted below /run/parent/app; otherwise, they are mounted below /app.

branch (string)

The branch of the app, for example stable. Available since 0.6.10.

arch (string)

The architecture of the running instance.

flatpak-version (string)

The version number of the Flatpak version that ran this app. Available since 0.6.11.

runtime-path (string)

The absolute path on the host system of the app's runtime files, as mounted at /usr inside the container. Available since 0.6.10. Since 1.12.0, if flatpak run was run with the --usr-path option, this key gives the absolute path of whatever files were mounted on /usr, even if that differs from the app's normal runtime files.

original-runtime-path (string)

If flatpak run was run with the --runtime-path option, this key gives the absolute path of the app's original runtime, as mounted at /run/parent/usr inside the container. Available since 1.12.0. If this key is missing, the runtime files are given by runtime-path.

runtime-commit (string)

The commit ID of the runtime that is used. The filename of a deployment of this commit can be found in original-runtime-path if present, or runtime-path otherwise.

runtime-extensions (list of strings)

A list of runtime extensions that are mounted into the running instance. The format for each list item is EXTENSION_ID=COMMIT. If original-app-path is present, the extensions are mounted below /run/parent/usr; otherwise, they are mounted below /usr.

extra-args (string)

Extra arguments that were passed to flatpak run.

sandbox (boolean)

Whether the --sandbox option was passed to flatpak run.

build (boolean)

Whether this instance was created by flatpak build.

session-bus-proxy (boolean)

True if this app cannot access the D-Bus session bus directly (either it goes via a proxy, or it cannot access the session bus at all). Available since 0.8.0.

system-bus-proxy (boolean)

True if this app cannot access the D-Bus system bus directly (either it goes via a proxy, or it cannot access the system bus at all). Available since 0.8.0.

### [Session Bus Policy]
If the sockets key is not allowing full access to the D-Bus session bus, then flatpak provides filtered access.

The default policy for the session bus only allows the application to own its own application ID, its subnames and its own application ID as a subname of org.mpris.MediaPlayer2. For instance if the app is called org.my.App, it can only own org.my.App, org.my.App.* and org.mpris.MediaPlayer2.org.my.App. It is only allowed to talk to names matching those patterns, plus the bus itself (org.freedesktop.DBus) and the portal APIs (bus names of the form org.freedesktop.portal.*).

Additionally the app is always allowed to reply to messages sent to it, and emit broadcast signals (but these will not reach other sandboxed apps unless they are allowed to talk to your app.

If the [Session Bus Policy] group is present, it provides policy for session bus access.

Each key in this group has the form of a D-Bus bus name or prefix thereof, for example org.gnome.SessionManager or org.freedesktop.portal.*.

The possible values for an entry are the following, in increasing order of access. Each value implies all the access from any lower values:

none

The bus name is invisible to the application. Available since 0.2.

see

The bus name can be enumerated by the application. Available since 0.2.

talk

The application can send messages to, and receive replies and signals from, the bus name. Available since 0.2.

own

The application can own the bus name. Available since 0.2.

### [System Bus Policy]
If the sockets key is not allowing full access to the D-Bus system bus, then flatpak does not make the system bus available unless the [System Bus Policy] group is present and provides a policy for filtered access. Available since 0.2.

Entries in this group have the same form as for the [Session Bus Policy] group. However, the app has no permissions by default.

### [Environment]
The [Environment] group specifies environment variables to set when running the application. Available since 0.3.

Entries in this group have the form VAR=VALUE where VAR is the name of an environment variable to set.

Note that environment variables can also be unset (removed from the environment) by listing them in the unset-environment entry of the [Context] group.

### [Extension NAME]
Runtimes and applications can define extension points, which allow optional, additional runtimes to be mounted at a specified location inside the sandbox when they are present on the system. Typical uses for extension points include translations for applications, or debuginfo for sdks. The name of the extension point is specified as part of the group heading. Since 0.11.4, the name may optionally include a tag in the NAME in the name@tag ref syntax if you wish to use different configurations (eg, versions) of the same extension concurrently. The "tag" is effectively ignored, but is necessary in order to allow the same extension name to be specified more than once.

directory (string)

The relative path at which the extension will be mounted in the sandbox. If the extension point is for an application, the path is relative to /app, otherwise it is relative to /usr. This key is mandatory. Available since 0.1.

version (string)

The branch to use when looking for the extension. If this is not specified, it defaults to the branch of the application or runtime that the extension point is for. Available since 0.4.1.

versions (string)

The branches to use when looking for the extension. If this is not specified, it defaults to the branch of the application or runtime that the extension point is for. Available since 0.9.1, and backported to the 0.8.x branch in 0.8.4.

add-ld-path (string)

A path relative to the extension point directory that will be appended to LD_LIBRARY_PATH. Available since 0.9.1, and backported to the 0.8.x branch in 0.8.3.

merge-dirs (string)

A list of relative paths of directories below the extension point directory that will be merged. Available since 0.9.1, and backported to the 0.8.x branch in 0.8.3.

download-if (string)

A condition that must be true for the extension to be auto-downloaded. As of 1.1.1 this supports multiple conditions separated by semi-colons. These are the supported conditions:

active-gl-driver

Is true if the name of the active GL driver matches the extension point basename. Available since 0.9.1, and backported to the 0.8.x branch in 0.8.3.

active-gtk-theme

Is true if the name of the current GTK theme (via org.gnome.desktop.interface GSetting) matches the extension point basename. Added 0.10.1.

have-intel-gpu

Is true if the i915 kernel module is loaded. Added 0.10.1.

have-kernel-module-*

Is true if the suffix (case-sensitive) is found in /proc/modules. For example have-kernel-module-nvidia. Added 1.13.1.

on-xdg-desktop-*

Is true if the suffix (case-insensitively) is in the XDG_CURRENT_DESKTOP env var. For example on-xdg-desktop-GNOME-classic. Added 1.1.1.

autoprune-unless (string)

A condition that must be false for the extension to be considered unused when pruning. For example, flatpak uninstall --unused and flatpak update use this information. The only currently recognized value is active-gl-driver, which is true if the name of the active GL driver matches the extension point basename. Available since 0.11.8.

enable-if (string)

A condition that must be true for the extension to be enabled. As of 1.1.1 this supports multiple conditions separated by semi-colons. See download-if for available conditions.

subdirectory-suffix (string)

A suffix that gets appended to the directory name. This is very useful when the extension point naming scheme is "reversed". For example, an extension point for GTK+ themes would be /usr/share/themes/$NAME/gtk-3.0, which could be achieved using subdirectory-suffix=gtk-3.0. Available since 0.9.1, and backported to the 0.8.x branch in 0.8.3.

subdirectories (boolean)

If this key is set to true, then flatpak will look for extensions whose name is a prefix of the extension point name, and mount them at the corresponding name below the subdirectory. Available since 0.1.

no-autodownload (boolean)

Whether to automatically download extensions matching this extension point when updating or installing a 'related' application or runtime. Available since 0.6.7.

locale-subset (boolean)

If set, then the extensions are partially downloaded by default, based on the currently configured locales. This means that the extension contents should be a set of directories with the language code as name. Available since 0.9.13 (and 0.6.6 for any extensions called *.Locale)

autodelete (boolean)

Whether to automatically delete extensions matching this extension point when deleting a 'related' application or runtime. Available since 0.6.7.

collection-id (string)

The ID of the collection that this extension point belongs to. If this is unspecified, it defaults to the collection ID of the application or runtime that the extension point is for. Currently, extension points must be in the same collection as the application or runtime that they are for. Available since 0.99.1.

### [ExtensionOf]
This optional group may be present if the runtime is an extension.

ref (string)

The ref of the runtime or application that this extension belongs to. Available since 0.9.1.

runtime (string)

The runtime this extension will be inside of. If it is an app extension, this is the app's runtime; otherwise, this is identical to ref, without the runtime/ prefix. Available since 1.5.0.

priority (integer)

The priority to give this extension when looking for the best match. Default is 0. Available since 0.9.1, and backported to the 0.8.x branch in 0.8.3.

tag (string)

The tag name to use when searching for this extension's mount point in the parent flatpak. Available since 0.11.4.

### [Extra Data]
This optional group may be present if the runtime or application uses extra data that gets downloaded separately. The data in this group gets merged into the repository summary, with the xa.extra-data-sources key.

If multiple extra data sources are present, their uri, size and checksum keys are grouped together by using the same suffix. If only one extra data source is present, the suffix can be omitted.

NoRuntime (boolean)

Whether to mount the runtime while running the /app/bin/apply_extra script. Defaults to true, i.e. not mounting the runtime. Available since 0.9.1, and backported to the 0.8.x branch in 0.8.4.

uriX (string)

The uri for extra data source X. The only supported uri schemes are http and https. Available since 0.6.13.

sizeX (integer)

The size for extra data source X. Available since 0.6.13.

checksumX (string)

The sha256 sum for extra data source X. Available since 0.6.13.

### [Policy SUBSYSTEM]
Subsystems can define their own policies to be placed in a group whose name has this form. Their values are treated as lists, in which items can have their meaning negated by prepending ! to the value. They are not otherwise parsed by Flatpak. Available since 0.6.13.

### [USB Devices]
USB devices can be enumerable or hidden by the USB portal as specified by the keys in this group. The vendor and product ids are validated by Flatpak, but aren't otherwise used or parsed. This merely grant the permission to enumerate USB device for use by the portal. This does give access to the devices. Available since 1.15.11.

enumerable-devices (string list)

List of enumerable USB devices. Each element is the same syntax the arguments to `--usb`. Available since 1.15.11.

hidden-devices (string list)

List of hidden USB devices, i.e. to remove the enumerable devices list. Each element is the same syntax the arguments to `--nousb`. Hidden devices take precedence over enumerable devices. Available since 1.15.11.

## EXAMPLE

```
[Application]
name=org.gnome.Calculator
runtime=org.gnome.Platform/x86_64/3.20
sdk=org.gnome.Sdk/x86_64/3.20
command=gnome-calculator
[Context]
shared=network;ipc;
sockets=x11;wayland;
filesystems=xdg-run/dconf;~/.config/dconf:ro;
[Session Bus Policy]
ca.desrt.dconf=talk
[Environment]
DCONF_USER_CONFIG_DIR=.config/dconf
[USB Devices]
enumerable-devices=0fd9:*;
hidden-devices=0fd9:0063;
[Extension org.gnome.Calculator.Locale]
directory=share/runtime/locale
subdirectories=true
[Extension org.gnome.Calculator.Debug]
directory=lib/debug
```

Example using conditional permissions to support fallback from Wayland to X11:

```
[Application]
name=org.example.App
runtime=org.gnome.Platform/x86_64/3.20
sdk=org.gnome.Sdk/x86_64/3.20
[Context]
shared=network;ipc;
sockets=wayland;x11;if:x11:!has-wayland;
```

In this example, the application will always have access to the Wayland socket if there the app runs in a Wayland session. The X11 socket only is available if the app does not run in a wayland session (!has-wayland).

## SEE ALSO
flatpak(1), flatpak-run(1), flatpak-override(1)

## NOTES
1.

openat2()

https://man7.org/linux/man-pages/man2/openat2.2.html

2.

steam-runtime-tools

https://gitlab.steamos.cloud/steamrt/steam-runtime-tools/-/blob/65adfdd5fc812aeb5f33986755f6ff72c9612afa/steam-runtime-tools/resolve-in-sysroot.c

3.

freedesktop.org special directories

https://www.freedesktop.org/wiki/Software/xdg-user-dirs/

4.

freedesktop.org Base Directory Specification

https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html


flatpak-remote

package: flatpak

title: flatpak-remote(5)

summary: Configuration for a remote

text:
# flatpak-remote(5)

## NAME
flatpak-remote - Configuration for a remote

## DESCRIPTION
Flatpak stores information about configured remotes for an installation location in $installation/repo/config. For example, the remotes for the default system-wide installation are in $prefix/var/lib/flatpak/repo/config, and the remotes for the per-user installation are in $HOME/.local/share/flatpak/repo/config.

Normally, it is not necessary to edit remote config files directly, the flatpak remote-modify command should be used to change properties of remotes.

System-wide remotes can be statically preconfigured by dropping flatpakrepo(5) files into /usr/share/flatpak/remotes.d/ and /etc/flatpak/remotes.d/. Ifa file with the same name exists in both, the file under /etc will take precedence.

## FILE FORMAT
The remote config file format is using the same .ini file format that is used for systemd unit files or application .desktop files.

### [remote ...]
All the configuration for the the remote with name NAME is contained in the [remote "NAME"] group.

The following keys are recognized by OSTree, among others:

url (string)

The url for the remote. An URL of the form oci+https:// or oci+http:// is a Flatpak extension that indicates that the remote is not an ostree repository, but is rather an URL to an index of OCI images that are stored within a container image registry. For OCI remotes, client and CA certificates are read from /etc/containers/certs.d and ~/.config/containers/certs.d as documented in containers-certs.d(5).

gpg-verify (boolean)

Whether to use GPG verification for content from this remote.

gpg-verify-summary (boolean)

Whether to use GPG verification for the summary of this remote. This is ignored if collection-id is set, as refs are verified in commit metadata in that case. Enabling gpg-verify-summary would break peer to peer distribution of refs.

collection-id (string)

The globally unique identifier for the upstream collection repository, to allow mirrors to be grouped.

All flatpak-specific keys have a xa. prefix:

xa.disable (boolean)

Whether the remote is disabled. Defaults to false.

xa.prio (integer)

The priority for the remote. This is used when listing remotes, and when searching them for the runtime needed by an app. The remote providing the app is searched for its runtime before others with equal priority. Defaults to 1.

xa.noenumerate (boolean)

Whether this remote should be ignored when presenting available apps/runtimes, or when searching for a runtime dependency. Defaults to false.

xa.nodeps (boolean)

Whether this remote should be excluded when searching for dependencies. Defaults to false.

xa.title (string)

An optional title to use when presenting this remote in a UI.

xa.title-is-set (boolean)

This key is set to true if xa.title has been explicitly set.

xa.comment (string)

An optional single-line comment to use when presenting this remote in a UI.

xa.comment-is-set (boolean)

This key is set to true if xa.comment has been explicitly set.

xa.description (string)

An optional full-paragraph of text to use when presenting this remote in a UI.

xa.description-is-set (boolean)

This key is set to true if xa.description has been explicitly set.

xa.homepage (string)

An optional URL that points to a website for this repository to use when presenting this remote in a UI.

xa.homepage-is-set (boolean)

This key is set to true if xa.homepage has been explicitly set.

xa.icon (string)

An optional URL that points to an icon for this repository to use when presenting this remote in a UI.

xa.icon-is-set (boolean)

This key is set to true if xa.icon has been explicitly set.

xa.default-branch (string)

The default branch to use when installing from this remote.

xa.default-branch-is-set (boolean)

This key is set to true if xa.default-branch has been explicitly set.

xa.main-ref (string)

The main reference served by this remote. This is used for origin remotes of applications installed via a flatpakref file.

xa.signature-lookaside (string)

URL to load signatures from (OCI remotes only), using the containers/image separate storage mechanism.[1]

## EXAMPLES

```
[remote "gnome-nightly-apps"]
gpg-verify=true
gpg-verify-summary=true
url=https://sdk.gnome.org/nightly/repo-apps/
xa.title=GNOME Applications
```

```
[remote "flathub"]
gpg-verify=true
gpg-verify-summary=false
collection-id=org.flathub.Stable
url=https://dl.flathub.org/repo/
xa.title=Flathub
```

## SEE ALSO
flatpak-remote-modify(1)

## NOTES
1.

containers/image separate storage mechanism.

https://github.com/containers/image/blob/main/docs/signature-protocols.md

branch: sisyphus


flatpakref

title: flatpakref(5)

text:
# flatpakref(5)

## NAME
flatpakref - Reference to a remote for an application or runtime

## DESCRIPTION
Flatpak uses flatpakref files to share information about a remote for a single application. The flatpakref file contains enough information to add the remote and install the application. Use the flatpak install --from command to do so.

flatpakref files may also contain additional information that is useful when displaying the application to the user, e.g. in an app store.

The filename extension commonly used for flatpakref files is .flatpakref.

A flatpakref file can also refer to a remote for a runtime.

## FILE FORMAT
The flatpakref file is using the same .ini file format that is used for systemd unit files or application .desktop files.

### [Flatpak Ref]
All the information is contained in the [Flatpak Ref] group.

The following keys can be present in this group:

Version (uint64)

The version of the file format, must be 1 if present.

Name (string)

The fully qualified name of the runtime or application. This key is mandatory.

Url (string)

The url for the remote. This key is mandatory.

Branch (string)

The name of the branch from which to install the application or runtime. If this key is not specified, the "master" branch is used.

Title (string)

The title of the application or runtime. This should be a user-friendly name that can be displayed e.g. in an app store.

Comment (string)

A short summary of the application or runtime, for display e.g. in an app store.

Description (string)

A longer description of the application or runtime, for display e.g. in an app store.

Icon (string)

The url for an icon that can be used to represent the application or runtime.

Homepage (string)

The url of a webpage describing the application or runtime.

DeploySideloadCollectionID (string)

The collection ID of the remote, if it has one. This uniquely identifies the collection of apps in the remote, to allow peer to peer redistribution (see flatpak(1)). It is recommended to use this key over DeployCollectionID or CollectionID because only newer clients (Flatpak 1.12.8 or later) pay attention to it (and older clients don't handle collection IDs properly).

DeployCollectionID (string)

This is deprecated but still supported for backwards compatibility. Use DeploySideloadCollectionID instead.

CollectionID (string)

This is deprecated but still supported for backwards compatibility. Use DeploySideloadCollectionID instead.

IsRuntime (boolean)

Whether this file refers to a runtime. If this key is not specified, the file is assumed to refer to an application.

GPGKey (string)

The base64-encoded gpg key for the remote.

SignatureLookaside (string)

URL to use to look up signatures (OCI remotes only)

RuntimeRepo (string)

The url for a .flatpakrepo file for the remote where the runtime can be found. Note that if the runtime is available in the remote providing the app, that remote may be used instead but the one specified by this option will still be added.

SuggestRemoteName (string)

A suggested name for the remote.

## EXAMPLE

```
[Flatpak Ref]
Title=gedit
Name=org.gnome.gedit
Branch=stable
Url=http://sdk.gnome.org/repo-apps/
IsRuntime=false
GPGKey=mQENBFUUCGcBCAC/K9WeV4xCaKr3NKRqPXeY5mpaXAJyasLqCtrDx92WUgbu0voWrhohNAKpqizod2dvzc/XTxm3rHyIxmNfdhz1gaGhynU75Qw4aJVcly2eghTIl++gfDtOvrOZo/VuAq30f32dMIgHQdRwEpgCwz7WyjpqZYltPAEcCNL4MTChAfiHJeeiQ5ibystNBW8W6Ymf7sO4m4g5+/aOxI54oCOzD9TwBAe+yXcJJWtc2rAhMCjtyPJzxd0ZVXqIzCe1xRvJ6Rq7YCiMbiM2DQFWXKnmYQbj4TGNMnwNdAajCdrcBWEMSbzq7EzuThIJRd8Ky4BkEe1St6tuqwFaMZz+F9eXABEBAAG0KEdub21lIFNESyAzLjE2IDxnbm9tZS1vcy1saXN0QGdub21lLm9yZz6JATgEEwECACIFAlUUCGcCGwMGCwkIBwMCBhUIAgkKCwQWAgMBAh4BAheAAAoJEArkz6VV0VKBa5cH/0vXa31YgEjNk78gGFXqnQxdD1WYA87OYxDi189l4lA802EFTF4wCBuZyDOqdd5BhS3Ab0cR778DmZXRUP2gwe+1zTJypU2JMnDpkwJ4NK1VP6/tE4SAPrznBtmb76BKaWBqUfZ9Wq1zg3ugvqkZB/Exq+usypIOwQVp1KL58TrjBRda0HvRctzkNhr0qYAtkfLFe0GvksBp4vBm8uGwAx7fw/HbhIjQ9pekTwvB+5GwDPO/tSip/1bQfCS+XJB8Ffa04HYPLGedalnWBrwhYY+G/kn5Zh9L/AC8xeLwTJTHM212rBjPa9CWs9C6a57MSaeGIEHLC1hEyiJJ15w8jmY=
DeployCollectionID=org.gnome.Apps
```

## SEE ALSO
flatpak(1), flatpak-install(1) flatpakrepo(5),


flatpakrepo

title: flatpakrepo(5)

summary: Reference to a remote

text:
# flatpakrepo(5)

## NAME
flatpakrepo - Reference to a remote

## DESCRIPTION
Flatpak uses flatpakrepo files to share information about remotes. The flatpakrepo file contains enough information to add the remote. Use the flatpak remote-add --from command to do so.

flatpakrepo files may also contain additional information that is useful when displaying a remote to the user, e.g. in an app store.

The filename extension commonly used for flatpakrepo files is .flatpakrepo.

flatpakrepo files can also be placed in /usr/share/flatpak/remotes.d/ and /etc/flatpak/remotes.d/ to statically preconfigure system-wide remotes. Such files must use the .flatpakrepo extension. If a file with the same name exists in both, the file under /etc will take precedence.

## FILE FORMAT
The flatpakrepo file is using the same .ini file format that is used for systemd unit files or application .desktop files.

### [Flatpak Repo]
All the information is contained in the [Flatpak Repo] group.

The following keys can be present in this group:

Version (uint64)

The version of the file format, must be 1 if present.

Url (string)

The url for the remote. This key is mandatory.

GPGKey (string)

The base64-encoded gpg key for the remote.

DefaultBranch (string)

The default branch to use for this remote.

Subset (string)

Limit the remote to the named subset of refs.

Title (string)

The title of the remote. This should be a user-friendly name that can be displayed e.g. in an app store.

Comment (string)

A short summary of the remote, for display e.g. in an app store.

Description (string)

A longer description of the remote, for display e.g. in an app store.

Icon (string)

The url for an icon that can be used to represent the remote.

Homepage (string)

The url of a webpage describing the remote.

Filter (string)

The path of a local file to use to filter remote refs. See flatpak-remote-add(1) for details on the format of the file. Note: This field is treated a bit special by flatpak remote-add. If you install a remote with --if-not-exists then and the remote is already configured, then the filter field of the remote configuration will be update anyway. And, if the filter field is *not* specified then any existing filters are cleared. The goal here is to allow a pre-configured filtered remote to be replaced with the regular one if you add the normal upstream (unfiltered) flatpakrepo file.

DeploySideloadCollectionID (string)

The collection ID of the remote, if it has one. This uniquely identifies the collection of apps in the remote, to allow peer to peer redistribution (see flatpak(1)). It is recommended to use this key over DeployCollectionID or CollectionID because only newer clients (Flatpak 1.12.8 or later) pay attention to it (and older clients don't handle collection IDs properly).

DeployCollectionID (string)

This is deprecated but still supported for backwards compatibility. Use DeploySideloadCollectionID instead.

CollectionID (string)

This is deprecated but still supported for backwards compatibility. Use DeploySideloadCollectionID instead.

## EXAMPLE

```
[Flatpak Repo]
Title=gedit
Url=http://sdk.gnome.org/repo-apps/
GPGKey=mQENBFUUCGcBCAC/K9WeV4xCaKr3NKRqPXeY5mpaXAJyasLqCtrDx92WUgbu0voWrhohNAKpqizod2dvzc/XTxm3rHyIxmNfdhz1gaGhynU75Qw4aJVcly2eghTIl++gfDtOvrOZo/VuAq30f32dMIgHQdRwEpgCwz7WyjpqZYltPAEcCNL4MTChAfiHJeeiQ5ibystNBW8W6Ymf7sO4m4g5+/aOxI54oCOzD9TwBAe+yXcJJWtc2rAhMCjtyPJzxd0ZVXqIzCe1xRvJ6Rq7YCiMbiM2DQFWXKnmYQbj4TGNMnwNdAajCdrcBWEMSbzq7EzuThIJRd8Ky4BkEe1St6tuqwFaMZz+F9eXABEBAAG0KEdub21lIFNESyAzLjE2IDxnbm9tZS1vcy1saXN0QGdub21lLm9yZz6JATgEEwECACIFAlUUCGcCGwMGCwkIBwMCBhUIAgkKCwQWAgMBAh4BAheAAAoJEArkz6VV0VKBa5cH/0vXa31YgEjNk78gGFXqnQxdD1WYA87OYxDi189l4lA802EFTF4wCBuZyDOqdd5BhS3Ab0cR778DmZXRUP2gwe+1zTJypU2JMnDpkwJ4NK1VP6/tE4SAPrznBtmb76BKaWBqUfZ9Wq1zg3ugvqkZB/Exq+usypIOwQVp1KL58TrjBRda0HvRctzkNhr0qYAtkfLFe0GvksBp4vBm8uGwAx7fw/HbhIjQ9pekTwvB+5GwDPO/tSip/1bQfCS+XJB8Ffa04HYPLGedalnWBrwhYY+G/kn5Zh9L/AC8xeLwTJTHM212rBjPa9CWs9C6a57MSaeGIEHLC1hEyiJJ15w8jmY=
DeployCollectionID=org.gnome.Apps
```

## SEE ALSO
flatpak(1), flatpak-remote-add(1), flatpakref(5)


flatpak-manifest

package: flatpak-builder

title: flatpak-manifest(5)

summary: Information for building an application

text:
# flatpak-manifest(5)

## NAME
flatpak-manifest - Information for building an application

## DESCRIPTION
Flatpak uses manifest, or recipe, files in a json or yaml 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 manifest 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:

id or app-id (string)

A string defining the application id. Note, "app-id" is deprecated and preserved only for backwards compatibility.

branch (string)

The branch to use when exporting the application. If this is unset the default comes from the default-branch option. This key overrides both the default-branch key, and the --default-branch commandline option. Unless you need a very specific branchname (like for a runtime or an extension) it is recommended to use the default-branch key instead, as that can be overridden by the --default-branch option.

default-branch (string)

The default branch to use when exporting the application. Defaults to master. This key can be overridden by the --default-branch commandline option.

collection-id (string)

The collection ID of the repository, defaults to being unset. Setting a globally unique collection ID allows the apps in the repository to be shared over peer-to-peer systems without needing further configuration. If building in an existing repository, the collection ID must match the existing configured collection ID for that repository.

extension-tag (string)

If building an extension, the tag for the extension point to use. Since flatpak 0.11.4 a runtime may define multiple locations for the same extension point with the intention that different branches for the extension are mounted at each location. When building an extension it is necessary to know what extension point to install the extension to. This option resolves any ambiguity in which extension point to choose. If not specified, the default choice is to install into either the only location for the extension point or into the location for the untagged extension point. If there are multiple locations for the same extension point defined with different tags then an error will occur.

token-type (integer)

The type of token needed to install this commit. Setting this to a value greater than 0 implies that authentication will be needed to install the flatpak.

runtime (string)

The name of the runtime that the application uses.

runtime-version (string)

The version of the runtime that the application uses, defaults to master.

sdk (string)

The name of the development runtime that the application builds with.

var (string)

Initialize the (otherwise empty) writable /var in the build with a copy of this runtime.

metadata (string)

Use this file as the base metadata file when finishing.

command (string)

The filename or path to the main binary of the application. Note that this must be a single executable, not a commandline or an absolute path. If you want to pass arguments, install a shell script wrapper and use that as the command. Also note that the command is used when the application is run via flatpak run, and does not affect what gets executed when the application is run in other ways, e.g. via the desktop file or D-Bus activation.

build-runtime (boolean)

Build a new runtime instead of an application.

build-extension (boolean)

Build an extension.

separate-locales (boolean)

Separate out locale files and translations to an extension runtime. Defaults to true.

id-platform (string)

When building a runtime sdk, also create a platform based on it with this id.

metadata-platform (string)

The metadata file to use for the platform we create.

writable-sdk (boolean)

If true, use a writable copy of the sdk for /usr. Defaults to true if build-runtime is specified.

appstream-compose (boolean)

Run appstreamcli compose during cleanup phase. Defaults to true.

sdk-extensions (array of strings)

Install these extra sdk extensions in /usr.

platform-extensions (array of strings)

Install these extra sdk extensions when creating the platform.

base (string)

Start with the files from the specified application. This can be used to create applications that extend another application.

base-version (string)

Use this specific version of the application specified in base. If unspecified, this uses the value specified in branch

base-extensions (array of strings)

Install these extra extensions from the base application when initializing the application directory.

inherit-extensions (array of strings)

Inherit these extra extension points from the base application or sdk when finishing the build.

inherit-sdk-extensions (array of strings)

Inherit these extra extension points from the base application or sdk when finishing the build, but do not inherit them into the platform.

tags (array of strings)

Add these tags to the metadata file.

build-options (object)

Object specifying the build environment. See below for details.

modules (array of objects or strings)

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 or yaml file that contains a module. See below for details.

add-extensions (objects)

This is a dictionary of extension objects. The key is the name of the extension. See below for details.

add-build-extensions (objects)

This is a dictionary of extension objects similar to add-extensions. The main difference is that the extensions are added early and are available for use during the build.

cleanup (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.

cleanup-commands (array of strings)

An array of commandlines that are run during the cleanup phase.

cleanup-platform (array of strings)

Extra files to clean up in the platform.

cleanup-platform-commands (array of strings)

An array of commandlines that are run during the cleanup phase of the platform.

prepare-platform-commands (array of strings)

An array of commandlines that are run after importing the base platform, but before applying the new files from the sdk. This is a good place to e.g. delete things from the base that may conflict with the files added in the sdk.

finish-args (array of strings)

An array of arguments passed to the flatpak build-finish command.

rename-desktop-file (string)

Any desktop file with this name will be renamed to a name based on id during the cleanup phase. The appdata file launchable will be updated if needed.

rename-appdata-file (string)

Any appdata (metainfo) file with this name will be renamed to a name based on id during the cleanup phase. The id in the file will be updated as needed and the subsequent provides. (since 1.4.1)

rename-mime-file (string)

Any mimetypes file with this name will be renamed to a name based on id during the cleanup phase. (since 1.4.0)

rename-icon (string)

Any icon with this name will be renamed to a name based on id during the cleanup phase. Note that this is the icon name, not the full filename, so it should not include a filename extension.

rename-mime-icons (array of string)

Any mime icons with any of these names will be renamed to a name prefixed with id during the cleanup phase. Note that these are the icon names, not the full filenames, so they should not include a filename extension. (since 1.4.0)

appdata-license (string)

Replace the appdata (metainfo) project_license field with this string. This is useful as the upstream license is typically only about the application itself, whereas the bundled app can contain other licenses too.

copy-icon (boolean)

If rename-icon is set, keep a copy of the old icon file.

desktop-file-name-prefix (string)

This string will be prefixed to the Name key in the main application desktop file.

desktop-file-name-suffix (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:

cflags (string)

This is set in the environment variable CFLAGS during the build. Multiple specifications of this (in e.g. per-arch area) are concatenated, separated by spaces.

cflags-override (boolean)

If this is true, clear cflags from previous build options before adding it from these options.

cppflags (string)

This is set in the environment variable CPPFLAGS during the build. Multiple specifications of this (in e.g. per-arch area) are concatenated, separated by spaces.

cppflags-override (boolean)

If this is true, clear cppflags from previous build options before adding it from these options.

cxxflags (string)

This is set in the environment variable CXXFLAGS during the build. Multiple specifications of this (in e.g. per-arch area) are concatenated, separated by spaces.

cxxflags-override (boolean)

If this is true, clear cxxflags from previous build options before adding it from these options.

ldflags (string)

This is set in the environment variable LDFLAGS during the build. Multiple specifications of this (in e.g. per-arch area) are concatenated, separated by spaces.

ldflags-override (boolean)

If this is true, clear ldflags from previous build options before adding it from these options.

prefix (string)

The build prefix for the modules (defaults to /app for applications and /usr for runtimes).

libdir (string)

The build libdir for the modules (defaults to /app/lib for applications and /usr/lib for runtimes).

append-path (string)

This will get appended to PATH in the build environment (with an leading colon if needed).

prepend-path (string)

This will get prepended to PATH in the build environment (with an trailing colon if needed).

append-ld-library-path (string)

This will get appended to LD_LIBRARY_PATH in the build environment (with an leading colon if needed).

prepend-ld-library-path (string)

This will get prepended to LD_LIBRARY_PATH in the build environment (with an trailing colon if needed).

append-pkg-config-path (string)

This will get appended to PKG_CONFIG_PATH in the build environment (with an leading colon if needed).

prepend-pkg-config-path (string)

This will get prepended to PKG_CONFIG_PATH in the build environment (with an trailing colon if needed).

env (object)

This is a dictionary defining environment variables to be set during the build. Elements in this override the properties that set the environment, like cflags and ldflags. Keys with a null value unset the corresponding variable.

secret-env (array of strings)

This is an array defining which host environment variables are transfered to the build-commands or post-install environment.

build-args (array of strings)

This is an array containing extra options to pass to flatpak build.

test-args (array of strings)

Similar to build-args but affects the tests, not the normal build.

config-opts (array of strings)

This is an array containing extra options passed to the build system during configuration.

secret-opts (array of strings)

This is an array of options that will be passed to configure. This is meant to be used to pass secrets through host environment variables. Environment variables in the options will be expanded. '-DSECRET_ID=$CI_SECRET'

make-args (array of strings)

An array of extra arguments that will be passed to make

make-install-args (array of strings)

An array of extra arguments that will be passed to make install

strip (boolean)

If this is true (the default is false) then all ELF files will be stripped after install.

no-debuginfo (boolean)

By default (if strip is not true) flatpak-builder extracts all debug info in ELF files to separate files and puts them into an extension. If you want to disable this, set no-debuginfo to true.

no-debuginfo-compression (boolean)

By default when extracting debuginfo the debug sections are compressed. If you want to disable this, set no-debuginfo-compression to true.

arch (object)

This is a dictionary defining a separate build options object for each arch, to override the main build options.

### Extension
Defines extension points in the app or runtime that can be implemented by extensions, supplying extra files which are available during runtime.

These are the properties that are accepted:

directory (string)

The directory where the extension is mounted. If the extension point is for an application, this path is relative to /app, otherwise it is relative to /usr.

bundle (boolean)

If this is true, then the data created in the extension directory is omitted from the result, and instead packaged in a separate extension.

remove-after-build (boolean)

If this is true, the extension is removed when finishing. This is only interesting for extensions in the add-build-extensions property.

Additionally the standard flatpak extension properties are supported, and put directly into the metadata file: autodelete, no-autodownload, subdirectories, add-ld-path, download-if, enable-if, autoprune-unless, merge-dirs, subdirectory-suffix, locale-subset, version, versions. See the flatpak metadata documentation for more information on these.

### 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. Module scopes are always isolated, so nested modules do not inherit attributes from parent modules.

These are the properties that are accepted:

name (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.

disabled (boolean)

If true, skip this module

sources (array of objects or strings)

An array of objects defining sources that will be downloaded and extracted in order. String members in the array are interpreted as the name of a separate json or yaml file that contains sources. See below for details.

secret-env (array of strings)

An array defining which host environment variables is transfered to build-commands or post-install environment.

config-opts (array of strings)

An array of options that will be passed to configure

secret-opts (array of strings)

An array of options that will be passed to configure, meant to be used to pass secrets through host environment variables. Put the option with an environment variables and will be resolved beforehand. '-DSECRET_ID=$CI_SECRET'

make-args (array of strings)

An array of arguments that will be passed to make

make-install-args (array of strings)

An array of arguments that will be passed to make install

rm-configure (boolean)

If true, remove the configure script before starting build. This requires the configure script to exist in the source directory.

no-autogen (boolean)

Ignore the existence of an autogen script

no-parallel-make (boolean)

Don't call make with arguments to build in parallel

install-rule (string)

Name of the rule passed to make for the install phase, default is install

no-make-install (boolean)

Don't run the make install (or equivalent) stage

no-python-timestamp-fix (boolean)

Don't fix up the *.py[oc] header timestamps for ostree use.

cmake (boolean)

Use cmake instead of configure (deprecated: use buildsystem instead)

buildsystem (string)

Build system to use: autotools, cmake, cmake-ninja, meson, simple, qmake

builddir (boolean)

Use a build directory that is separate from the source directory

subdir (string)

Build inside this subdirectory of the extracted sources

build-options (object)

A build options object that can override global options. Note that this is not inherited by nested modules.

build-commands (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. Each command is run in /bin/sh -c, so it can use standard POSIX shell syntax such as piping output. If any individual entry in the array fails, then the whole build process will fail, similar to commands in a make(1) recipe.

post-install (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.

cleanup (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.

ensure-writable (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.

only-arches (array of strings)

If non-empty, only build the module on the arches listed.

skip-arches (array of strings)

Don't build on any of the arches listed.

cleanup-platform (array of strings)

Extra files to clean up in the platform.

run-tests (boolean)

If true this will run the tests after installing.

test-rule (string)

The target to build when running the tests. Defaults to "check" for make and "test" for ninja. Set to empty to disable.

test-commands (array of strings)

Array of commands to run during the tests.

license-files (array of strings)

Array of paths to LICENSE files of the module.

modules (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 or yaml 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.

Additionally, the sources list can contain a plain string, which is interpreted as the name of a separate json or yaml file that is read and inserted at this point. The file can contain a single source, or an array of sources.

All sources

only-arches (array of strings)

If non-empty, only build the module on the arches listed.

skip-arches (array of strings)

Don't build on any of the arches listed.

dest (string)

Directory inside the source dir where this source will be extracted.

Archive sources (tar, zip)

type

"archive"

path (string)

The path of the archive

url (string)

The URL of a remote archive that will be downloaded. This overrides path if both are specified.

mirror-urls (array of strings)

A list of alternative urls that are used if the main url fails.

referer (string)

Sets the HTTP "Referer" header when downloading the archive.

disable-http-decompression (boolean)

Disables decompression of downloads over HTTP for misconfigured servers.

git-init (boolean)

Whether to initialise the repository as a git repository.

archive-type (string)

The type of archive if it cannot be guessed from the path. Possible values are "rpm", "tar", "tar-gzip", "tar-compress", "tar-bzip2", "tar-lzip", "tar-lzma", "tar-lzop", "tar-xz", "tar-zst", "zip" and "7z".

md5 (string)

The md5 checksum of the file, verified after download Note that md5 is no longer considered a safe checksum, we recommend you use at least sha256.

sha1 (string)

The sha1 checksum of the file, verified after download Note that sha1 is no longer considered a safe checksum, we recommend you use at least sha256.

sha256 (string)

The sha256 checksum of the file, verified after download

sha512 (string)

The sha512 checksum of the file, verified after download

strip-components (integer)

The number of initial pathname components to strip during extraction. Defaults to 1.

dest-filename (string)

Filename to for the downloaded file, defaults to the basename of url.

Git sources

type

"git"

path (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:///...

url (string)

URL of the git repository. This overrides path if both are specified. When using git via SSH, the correct syntax is ssh://user@domain/path/to/repo.git.

branch (string)

The branch to use from the git repository. As of 1.2.3 this will try to auto-detect the upstream default branch. Previously this defaulted to master.

tag (string)

The tag to use from the git repository

commit (string)

The commit to use from the git repository. If branch is also specified, then it is verified that the branch/tag is at this specific commit. This is a readable way to document that you're using a particular tag, but verify that it does not change.

disable-fsckobjects (boolean)

Don't use transfer.fsckObjects=1 to mirror git repository. This may be needed for some (broken) repositories.

disable-shallow-clone (boolean)

Don't optimize by making a shallow clone when downloading the git repo.

disable-submodules (boolean)

Don't checkout the git submodules when cloning the repository.

disable-lfs (boolean)

Don't explicitly fetch or checkout LFS git objects. This will be ignored by Git if LFS filters are active in system or global gitconfig.

Bzr sources

type

"bzr"

url (string)

URL of the bzr repository

revision (string)

A specific revision to use in the branch

Svn sources

type

"svn"

url (string)

URL of the svn repository, including branch/tag part

revision (string)

A specific revision number to use

Directory sources

type

"dir"

path (string)

The path of a local directory whose content will be copied into the source dir. Note that directory sources don't currently support caching, so they will be rebuilt each time.

skip (array of strings)

Source files to ignore in the directory.

File sources

type

"file"

path (string)

The path of a local file that will be copied into the source dir

url (string)

The URL of a remote file that will be downloaded and copied into the source dir. This overrides path if both are specified.

mirror-urls (array of strings)

A list of alternative urls that are used if the main url fails.

referer (string)

Sets the HTTP "Referer" header when downloading the file.

disable-http-decompression (boolean)

Disables decompression of downloads over HTTP for misconfigured servers.

md5 (string)

The md5 checksum of the file, verified after download. This is optional for local files. Note that md5 is no longer considered a safe checksum, we recommend you use at least sha256.

sha1 (string)

The sha1 checksum of the file, verified after download. This is optional for local files. Note that sha1 is no longer considered a safe checksum, we recommend you use at least sha256.

sha256 (string)

The sha256 checksum of the file, verified after download. This is optional for local files.

sha512 (string)

The sha512 checksum of the file, verified after download. This is optional for local files.

dest-filename (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.

type

"script"

commands (array of strings)

An array of shell commands that will be put in a shellscript file

dest-filename (string)

Filename to use inside the source dir, default to autogen.sh.

Inline data sources

This is a way to create a file with given contents.

type

"inline"

dest-filename (string)

Filename to use inside the source dir.

contents (string)

Text data that will be put in the file.

base64 (boolean)

Whether content is base64-encoded.

Shell sources

This is a way to create/modify the sources by running shell commands.

type

"shell"

commands (array of strings)

An array of shell commands that will be run during source extraction

Patch sources

type

"patch"

path (string)

The path of a patch file that will be applied in the source dir

paths (array of strings)

An list of paths to a patch files that will be applied in the source dir, in order

strip-components (integer)

The value of the -p argument to patch, defaults to 1.

use-git (boolean)

Whether to use "git apply" rather than "patch" to apply the patch, required when the patch file contains binary diffs.

use-git-am (boolean)

Whether to use "git am" rather than "patch" to apply the patch, required when the patch file contains binary diffs. You cannot use this at the same time as use-git.

options (array of strings)

Extra options to pass to the patch command.

Extra data sources

type

"extra-data"

filename (string)

The name to use for the downloaded extra data

url (string)

The url to the extra data.

sha256 (string)

The sha256 of the extra data.

size (number)

The size of the extra data in bytes.

installed-size (string)

The extra installed size this adds to the app (optional).

## BUILD ENVIRONMENT
When building the application each command is run in a separate sandbox with access to only the things required for it. This section describes the details of the sandbox. Any options here can be overridden globally or per-module with the build-args option (although such manifest will not work if you start flatpak-builder with --sandbox).

### Filesystem
Each module is built in its own build directory, stored in a sub directory called build/$modulename-$count in the state dir (which is typically .flatpak-builder/). Additionally there is a symlink build/$modulename to the latest version. In order to generate reproducible builds this directory is also mounted as /run/build/$modulename in the sandbox (or /run/build-runtime/$modulename when building runtimes) and also as /run/active-build since 1.4.7. This is used as current working directory for all build ops.

The destination directory for installation is accessible for writing at the place it will seen at runtime. In the case of a regular application this will be /app. If building a runtime it will instead be /usr, and when building an extension it will be at the extensionpoint directory somewhere below /app (for app extension) or /usr (for runtime extensions).

Additionally the there will be (as needed, depending on what is building) read-only mounts of the sdk at /usr, sdk extensions below that, and the application at /app. No other filesystem access is available.

### Environment
The environment can be modified in several ways in the manifest, but the default values are:

FLATPAK_ID

The id of the application currently building.

FLATPAK_ARCH

The architecture currently building.

FLATPAK_DEST

The path to where the current build should install into. This is /app for application builds.

FLATPAK_BUILDER_N_JOBS

The number of jobs that flatpak-builder would normally use for make -j. Defaults to ncpus unless the module disabled parallel make.

FLATPAK_BUILDER_BUILDDIR

The path to the build directory of the module currently building. This is normally /run/build/$MODULE.

PATH

/app/bin:/usr/bin

LD_LIBRARY_PATH

/app/lib

PKG_CONFIG_PATH

/app/lib/pkgconfig:/app/share/pkgconfig:/usr/lib/pkgconfig:/usr/share/pkgconfig

ACLOCAL_PATH

/app/share/aclocal

C_INCLUDE_PATH

/app/include

CPLUS_INCLUDE_PATH

/app/include

LDFLAGS

-L/app/lib

LC_ALL

en_US.utf8

### Permissions
Builds have the --allow=devel and --allow=multiarch permissions that regular flatpak runs don't have by default. This limits the syscall filtering that is normally done so development tools like debuggers work. Otherwise the build sandbox is very limited, for example there is no network access.

## 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": "https://gitlab.gnome.org/GNOME/babl.git"

                }

            ]

        },

        {

            "name": "testapp",

            "sources": [

                {

                    "type": "bzr",

                    "url": "lp:testapp"

                }

            ]

        }

    ]
}
```

## SEE ALSO
flatpak-builder(1)


fluxbox-apps

package: fluxbox

title: fluxbox-apps(5)

summary: per\-window attribute configuration for fluxbox(1)

text:
# fluxbox-apps(5)

## NAME
fluxbox-apps - per-window attribute configuration for fluxbox(1)

## SYNOPSIS
~/.fluxbox/apps

## SYNTAX
Variable parameters are shown in emphasis: argument

All other characters shown are required verbatim. Whitespace is only required to delimit words, but it is fine to add more whitespace.

## DESCRIPTION
It is possible to force an application to always have the same dimensions, position, and other settings when it is first launched. These settings are saved in the ‘apps’ file.

Most simple settings can be saved using the “Remember...” submenu of the window menu, which can usually be opened with a right-click on the titlebar. More advanced features require manually editing the ‘apps’ file. This may include using GROUP SECTIONS to set up automatic window tab groups.

You do not need to “reload” fluxbox after editing the apps file, the changes should be rescanned when the next window is opened.

The file is made up of two main types of sections, apps and groups, detailed below.

## APP SECTIONS
[app] sections provide settings for individual application windows.

These sections begin with a line of the format

[app](pattern){count}

The pattern can be one or more patterns which match windows. For more details, see CLIENT PATTERNS. If you specify more than one pattern, they must ALL match for the settings to be applied.

The {count} is optional. If specified, then the entry will only match at most that many windows at any time. If omitted, the default is to apply the settings to all matching windows.

This opening [apps] line is followed by any number of settings for the application. See SETTINGS for more details.

Each of these sections ends with the single line

[end]

## GROUP SECTIONS
The primary purpose of [group] sections is to group windows together. All windows in a group will be tabbed together automatically.

These sections begin with a line of the format

[group](pattern)

Where the pattern item is optional. If specified, this pattern must match for the group to take effect. It is common to use non-window-specific patterns such as (workspace) here. See CLIENT PATTERNS for more details.

This is followed by any number of [app] lines. These have a similar format to the [app] section detailed above in APP SECTIONS, but do not contain any settings and do not have an associated [end] line.

Like this

[app](pattern)

This section may also contain settings that are applied to every window in the group. See the SETTINGS section for details.

As with [app] sections, each of these sections ends with the single line

[end]

## SETTINGS
These settings may be stored in the ‘apps’ file. A settings line must appear inside either an [app] or [group] section.

The general format is

[setting]{value}

All allowed values are described below, except for bool which can simply have the value yes or no, which enables or disables the associated setting, respectively.

[Workspace] {number}

Forces the application to open on the number workspace specified. Workspaces are set by number, beginning with 0.

[Jump] {bool}

Changes the active workspace to the remembered one when the application is opened. This is only useful when used in conjunction with [Workspace]. See EXAMPLES.

[Head] {number}

Forces the application to open on the number head specified (Xinerama only).

[Layer] {number}

Specify the layer to open the window on (by number). Each layer has a number. The named ones are: 2-AboveDock, 4-Dock, 6-Top, 8-Normal, 10-Bottom, 12-Desktop.

[Dimensions] {width[%] height[%]}

Opens the application with the specified width and height, in pixels. If the value is given in percent, then the window size will be based on the current screen’s size.

[Position] (anchor) {X[%] Y[%]}

Position the application at a particular spot. By default the upper-left corner is placed at screen coordinates (X,Y). If you specify an anchor, say BottomRight, then the lower-right corner of the window is positioned (X,Y) pixels from the lower-right corner of the screen. If the value is given in percent, then the coordinates will be based on the current screen’s size. anchor may be set to one of:

TopLeft Left BottomLeft Top Center Bottom TopRight Right BottomRight

[Deco] {value}

Specify the decoration state. There are several predefined value sets:

NORMAL

Standard decorations

NONE

No decorations

BORDER

Like NONE except keep the X window border

TAB

Like BORDER except keep external tabs (if enabled)

TINY

Titlebar with only an iconify button

TOOL

Titlebar only

The value may also be a bitmask for finer-grained control. The bits are, from (1<<0) to (1<<10): Titlebar, Handle/Grips, Border, Iconify Button, Maximize Button, Close Button, Menu Button, Sticky Button, Shade Button, External Tabs, Focus Enabled.

[Shaded] {bool}

Whether the window is Shaded (rolled-up) or not.

[Tab] {bool}

Whether the window has tabs enabled.

[FocusNewWindow] {bool}

If enabled, a new window will grab X focus as soon as it is opened. If disabled, a new window will not grab X focus as soon as it is opened.

[FocusHidden] {bool}

If enabled, the window will not appear in NextWindow/PrevWindow lists.

[IconHidden] {bool}

If enabled, the window will not appear in the icon area of the toolbar.

[Hidden] {bool}

A shortcut for setting both FocusHidden and IconHidden at the same time.

[Sticky] {bool}

Specify if an application should be sticky (shown on all workspaces) or not.

[Minimized] {bool}

Application should start minimized

[Maximized] {value}

Application should start maximized. value may be:

yes

Fully maximized

horz

Horizontally maximized

vert

Vertically maximized

no

Not maximized

[Fullscreen] {bool}

Application should start in fullscreen mode (fully maximized without any decorations).

[Close] {bool}

Save settings on close. By default, application settings are not updated when a window is closed.

[Alpha] {value [value]}

Set the alpha value for this window. If two values are given, they correspond to the focused and unfocused transparency, respectively. One number only will be used for both values. value is an integer between 0 and 255.

## CLIENT PATTERNS
A pattern looks like this

([propertyname[!]=]regexp) ...

Match definitions are enclosed in parentheses (...), and if no propertyname is given then Name is assumed. The regexp can contain any regular expression, or the special value [current], which matches the corresponding value of the currently focused window. See regex(7) for more information on acceptable regular expressions.

propertyname is not case sensitive, whereas the regexp is.

If you specify multiple (pattern) arguments, this implies an AND condition - All specified patterns must match.

You can use = to test for equality or != to test for inequality.

The following values are accepted for propertyname

Name

A string, corresponding to the CLASSNAME property (The first field of WM_CLASS from the output of the xprop(1) utility).

Class

A string, corresponding to the CLASSCLASS property (The second field of WM_CLASS from the output of the xprop(1) utility).

Title

A string, corresponding to the window title (WM_NAME from xprop(1)).

Role

A string, corresponding to the ROLE property (WM_WINDOW_ROLE from xprop(1)).

Transient

Either yes or no, depending on whether the window is transient (typically, a popup dialog) or not.

Maximized

Either yes or no, depending on whether the window is maximized or not.

MaximizedHorizontal

Either yes or no, depending on whether the window is maximized horizontally or not.

MaximizedVertical

Either yes or no, depending on whether the window is maximized vertically or not.

Minimized

Either yes or no, depending on whether the window is minimized (iconified) or not.

Fullscreen

Either yes or no, depending on whether the window is fullscreen or not.

Shaded

Either yes or no, depending on whether the window is shaded or not.

Stuck

Either yes or no, depending on whether the window is sticky (on all workspaces) or not.

FocusHidden

Either yes or no, depending on whether the window has asked to be left off the focus list (or, the alt-tab list), or not.

IconHidden

Either yes or no, depending on whether the window has asked to be left off the icon list (or, the taskbar), or not.

Urgent

Either yes or no, depending on whether the window has the urgent hint set.

Workspace

A number corresponding to the workspace number to which the window is attached. The first workspace here is 0. You may also use [current] to match the currently visible workspace.

WorkspaceName

A string corresponding to the name of the workspace to which the window is attached.

Head

The number of the display head to which the window is attached. You may match this against the special value [mouse] which refers to the head where the mouse pointer currently resides.

Layer

The string name of the window’s layer, which is one of AboveDock, Dock, Top, Normal, Bottom, Desktop

Screen

The number of the currently used screen. If the setup of the running xserver involves independent screens (not Xinerama), the $DISPLAY environment contains something like :0.1 or :1.0. The part after the dot (.) is the number of the screen.

@XPROP

A string, corresponding to any xproperty (Use either the xprop(1) utility or the SetXProp command to set a xproperty to a window)

Matches any windows with the CLASSNAME of "xterm".

```
(xterm)
```

Matches any windows with the same CLASSNAME as the currently focused window.

```
(Name=[current])
```

Matches any windows on the same head as the mouse but on a different layer than the currently focused window.

```
(Head=[mouse]) (Layer!=[current])
```

Matches any windows having a xproperty named FOO with "bar" in it.

```
(@FOO=.*bar.*)
```

## FILES
~/.fluxbox/apps

This is the default location for the application settings.

## RESOURCES
session.appsFile: location

This may be set to override the location of the application settings.

## EXAMPLES
Here are some interesting and/or useful examples you can do with your apps file.

```
# Put the first two windows which end with 'term' on workspace 1
[app] (name=.*[tT]erm) {2}

  [Workspace]   {1}
[end]
# Center kate with a specific size, and update these values when the window is
# closed.
[app] (name=kate)

  [Dimensions]  {1022 747}

  [Position]    (CENTER) {0 0}

  [Close]       {yes}
[end]
# When starting konqueror, jump to workspace 1 first and start it there.
[app] (name=konqueror)

  [Workspace]   {1}

  [Jump]        {yes}
[end]
# start all aterm without decorations
[app] (name=aterm)

  [Deco]        {NONE}
[end]
# a group with the gimp dock and toolbox
# appears on layer 4 (bottom)
[group]

  [app] (name=gimp) (role=gimp-dock)

  [app] (name=gimp) (role=gimp-toolbox)

  [Layer]       {4}
[end]
```

## AUTHORS
•Jim Ramsay <i.am at jimramsay com> (>fluxbox-1.0.0)

•Curt Micol <asenchi at asenchi com> (>fluxbox-0.9.11)

•Tobias Klausmann <klausman at users sourceforge net> (⟨fluxbox-0.9.11)

•Grubert <grubert at users sourceforge net> (fluxbox)

•Matthew Hawkins <matt at mh dropbear id au> (blackbox)

•Wilbert Berendsen <wbsoft at xs4all nl> (blackbox)

## SEE ALSO
fluxbox(1) xprop(1) regex(7)

## AUTHOR
Jim Ramsay <i.am@jimramsay.com>

Author.