flatpak-remote

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 flatpakref files into /etc/flatpak/remotes.d/.

## 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.

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.

## 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)


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.

branch (string)

The branch to use when exporting the application. If this is unset the defaults come 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, because you can then override the default using --default-branch when building for instance a test build.

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 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. 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 appstream-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.

rename-appdata-file (string)

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

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 filenames, so it should not include a filename extension.

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 a array defining which host environment variables is transfered to 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 to pass to configure.

secret-opts (array of strings)

This is 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 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 a separate files and puts this in an extension. If you want to disable this, set no-debuginfo to true.

no-debuginfo-compression (boolean)

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

arch (object)

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

### Extension
Extension define extension points in the app/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 during 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, 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.

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

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

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.

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.

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.

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

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.

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.

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). 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.


fluxbox-keys

title: fluxbox-keys(5)

text:
# fluxbox-keys(5)

## NAME
fluxbox-keys - keyboard shortcuts configuration for fluxbox(1)

## SYNOPSIS
~/.fluxbox/keys

## SYNTAX
Variable parameters are shown in emphasis: argument

Optional parameters are shown in square brackets: [argument]

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

## DESCRIPTION
The keys file defines the keyboard shortcuts for fluxbox(1).

You can customize fluxbox’s key handling through the ~/.fluxbox/keys file. The file consists of lines of the basic format:

[modifiers] key :'command' [arguments ...]

The space between the key and the : before the command is mandatory.

All modifiers and commands are case-insensitive. Some command arguments (especially those that will be passed to the shell) are case-sensitive. Some key names are case-sensitive.

Lines beginning with a # or ! are considered comments and are unread by fluxbox.

You will need to “reload” fluxbox after editing the keys file so it picks up your change.

## MODIFIERS
You can get a list of possible modifiers by calling ‘xmodmap -pm’. This also shows you to which keys the modifiers are mapped, but the following modifiers are most commonly used:

Shift Control Mod1 Mod4

where Mod1 is the Alt key on the PC keyboard and Mod4 is usually a key branded with a familiar company logo.

There are also some special modifiers that refer to mouse button events

OnDesktop

The mouse cursor is over the desktop (root window), and not any window.

OnToolbar

The mouse cursor is over the toolbar (which is normally at the bottom of the screen).

OnWindow

The mouse cursor is over a window.

OnTitlebar

The mouse cursor is over a window’s titlebar.

OnTab

The mouse cursor is over a tab.

Double

Limits this action to double-clicks only.

### Combining Modifiers
To combine two or more modifiers, just list them (space-delimited) in any order.

## KEYS
You may specify a key by its key name (for example, a or space) or by its numeric keycode (for example, 38 or 0xf3).

If you don’t know the name of a key, you can run xev(1) in a terminal, push the key, and see the name in the output. If you have some "special" keys that do not produce a key name in the output of xev(1), you can just use the keycode (NOT the keysym!) in your keys file.

Commands can also be bound to mouse events (N denotes the number of the button, eg. 1 is the primary button, 4/5 are the wheel buttons):

MouseN

The mouse button N is pressed down and held.

ClickN

The mouse button N is clicked (pressed and released with no movement in between)

MoveN

The mouse button N is currently held, the bound action is triggered as often as the mouse moves.

There are some special "keys" that let you bind events to non-keyboard events:

ChangeWorkspace

Fires when the workspace changes. This can be used to change backgrounds or do anything else you like when you switch to a new workspace. See the EXAMPLES below for one idea.

Warning Use caution with this event! For example, do NOT bind this to any action that changes your current workspace. If you break your fluxbox with this feature, you get to keep the pieces.

## CHAINING
Key bindings can be chained in a fashion similar to Emacs key bindings using the syntax:

modifiers-1 key-1 modifiers-2 key-2 :'command' [arguments ...]*

To abort a chained command part-way through typing it, press the <ESC> key.

To Bind CTRL+C CTRL+X (Which means, press CTRL+C then CTRL+X) to quit fluxbox.

```
Control c Control x :Quit
```

## KEYMODES
A specific set of key mappings can be activated and de-activated on-the-fly using what are called keymodes. The syntax to define a mapping in a keymode is:

keymode: modifiers key :'command' [arguments ...]

Where keymode is any alpha-numeric string name.

When this keymode is activated (see the KeyMode command below), all bindings prefaced by that keymode name become active (and all other keybindings will be deactivated) until the keymode changes again.

## COMMANDS
Some commands have multiple names which are shown below as

CMD1 | CMD2

Related commands have been grouped below as

CMD1 / CMD2

The commands are broken up into sections as follows

•Mouse Commands

•Window Commands

•Workspace Commands

•Menu Commands

•Window Manager Commands

•Special Commands

### Mouse Commands
These commands may only be bound to mouse buttons (plus modifiers), not keystrokes. In all cases, the action finishes when the mouse button is released.

StartMoving

Start dragging to move the window.

StartResizing [corner]

Start dragging to resize the window as if you had grabbed the window at the specified corner. By default corner is BottomRight, but may be overridden with one of:

NearestCorner NearestEdge NearestCornerOrEdge Center TopLeft Top TopRight Left Right BottomLeft Bottom BottomRight

If NearestCornerOrEdge is specified the size of the corner can also be specified to be the larger of one or two following numbers: [pixel-size [percent-size]] or percent-size%, where percent-size is the percentage of half the window width or height. If no size is given, it defaults to 50 pixels and 30%.

StartTabbing

Start dragging to add this window to another’s tabgroup.

ActivateTab

Activates the tab underneath the mouse.

### Window Commands
These commands ordinarily affect only the currently focused window. The OnWindow modifier and ForEach command may affect the window that is used.

Minimize | MinimizeWindow | Iconify

Minimize the current window, equivalent to the window button.

Maximize | MaximizeWindow

Maximize the current window, equivalent to the window button.

MaximizeHorizontal / MaximizeVertical

Maximize the current window in one direction only, leaving the other dimension unchanged.

Fullscreen

Resize the window’s content to fit the whole screen, without any window decoration.

Raise / Lower

Reorder this window to the top or bottom of the window stack, within its current layer. See fluxbox(1) for a discussion of layers.

RaiseLayer / LowerLayer [offset]

Raise the window up to the layer above, or lower it to the layer below. See fluxbox(1) for a discussion of layers.

SetLayer layer

Move the window to the specified layer. layer should be one of AboveDock, Dock, Top, Normal, Bottom, Desktop. See fluxbox(1) for a discussion of layers.

Close

Close the current window, equivalent to the window button.

Kill | KillWindow

Close a window that’s not responding to Close, like using xkill(1).

Shade | ShadeWindow

Toggle the shaded state of the current window, equivalent to the window button. A shaded window appears as only the title bar.

ShadeOn / ShadeOff

Set the shaded state of the window to On / Off.

Stick | StickWindow

Toggle the sticky state of the current window, equivalent to the window button. A sticky window is visible on all workspaces.

SetDecor decor

Sets which window decorations will be shown. decor has the same format as the ‘[Deco]’ parameter in the apps file. See fluxbox-apps(5) for more info.

ToggleDecor

Toggles the presence of the window decorations (title bar, window buttons, and resize bar).

NextTab / PrevTab

Cycle to the next / previous tab in the current tab group.

Tab number

Cycle to the given tab in the current tab group, where 1 is the first tab. A negative number counts from the end of the tab group (-1 is the last tab, -2 is the next-to-last, etc.).

MoveTabRight / MoveTabLeft

Reorder the tabs in the current tab group, swapping the current tab with the one to the right / left.

DetachClient

Remove the current tab from the tab group, placing it in its own window.

ResizeTo width[%] height[%]

Resizes the window to the given width and height. If the value is given in percent, then the window size will be based on the current screen’s size.

Resize delta-width[%] delta-height[%]

Resizes the window relative to the current width and height. If the value is given in percent, then the window size will be based on the current window’s size.

ResizeHorizontal delta-width[%] / ResizeVertical delta-height[%]

Resizes the window in one dimension only. If the value is given in percent, then the window size will be based on the current window’s size.

MoveTo x[%] y[%] [anchor]

Moves the window to the given coordinates, given in pixels or relatively to the current screen size if % is specified after the value. If either x or y is set to \*, that coordinate will be ignored, and the movement will only take place in one dimension.

The default anchor is the upper left corner, but this may be overridden with one of:

TopLeft Left BottomLeft Top Center Bottom TopRight Right BottomRight

Move delta-x delta-y

Moves the window relative to its current position. Positive numbers refer to right and down, and negative to left and up, respectively.

MoveRight d / MoveLeft d / MoveUp d / MoveDown d

Moves the window relative to its current position by the number of pixels specified in d. If the number is negative, it moves in the opposite direction.

TakeToWorkspace workspace / SendToWorkspace workspace

Sends you along with the current window to the selected workspace. SendToWorkspace just sends the window. The first workspace is number 1, not 0.

TakeToNextWorkspace [offset] / TakeToPrevWorkspace [offset]

Sends you along with the current window to the next or previous workspace. If you set offset to a value greater than the default of 1, it will move you that number of workspaces ahead or behind. If you go beyond the end of the currently defined workspaces, it will wrap around to the other end automatically.

SendToNextWorkspace [offset] / SendToPrevWorkspace [offset]

Identical to the "TakeTo..." commands, but again this sends only the window, and does not move you away from your current workspace.

SetAlpha [alpha [unfocused-alpha]]

Sets the alpha value of a window. Putting a + or - in front of the value adds or subtracts from the current value. A plain integer sets the value explicitly.

no arguments

Resets both focused and unfocused settings to default opacity.

one argument

Changes both focused and unfocused alpha settings.

two arguments

First value becomes the focused alpha, second becomes the unfocused alpha value.

SetHead number

Moves the window to the given display head. Only available when fluxbox has been compiled with Xinerama support.

SendToNextHead [offset] / SendToPrevHead [offset]

Sends the current window to the next/previous display head. If you specify an offset greater than 1, it will move the window that many heads. If this takes the window beyond the total number of heads, it will wrap around to the beginning.

SetXProp PROP=value

Sets the xproperty PROP of the current window to value. Delete the content of PROP by using PROP=.

### Workspace Commands
These commands affect the entire workspace (or "desktop" as it is sometimes called).

AddWorkspace / RemoveLastWorkspace

Adds or removes a workspace from the end of the list of workspaces.

NextWorkspace [n] / PrevWorkspace [n] / RightWorkspace [n] / LeftWorkspace [n]

Switch to the Next / Previous workspace. All versions accept an offset value n, which defaults to 1 and refers to the number of workspaces to move at one time. {Next,Prev}Workspace wrap around when going past the last workspace, whereas {Right,Left}Workspace do not.

Workspace number

Jumps to the given workspace number. The first workspace is 1.

NextWindow [{options}] [pattern] / PrevWindow [{options}] [pattern]

Focuses the next / previous window in the focus list. options is one or more of the following, space delimited:

static

Instead of moving in order of most-recent focus, move in order of when the window was opened (or, the order shown in the iconbar).

groups

Only include the current tab in windows with multiple tabs.

If pattern arguments are supplied, only windows that match all the patterns are considered - all others are skipped. See the section CLIENT PATTERNS below for more information.

This pair of commands has a special side-effect when the keybinding used has a modifier - It will temporarily raise the cycled window to the front so you can see it, but if you continue holding down the modifier and press the key again (For example, keep holding "Alt" while you tap the "Tab" key a few times), fluxbox will lower the window again when you move on to the next one. This allows you to preview the windows in order, but does not change the order in doing so.

NextGroup [{options}] [pattern] / PrevGroup [{options}] [pattern]

Equivalent to NextWindow / PrevWindow above, but with the groups option forced on.

GotoWindow number [{options}] [pattern]

Focuses and activates the window at position number in the focus list. The options and pattern arguments have the same meaning as NextWindow above.

Activate [pattern] | Focus [pattern]

With pattern, this is an alias for GoToWindow 1 pattern. Without, this behaves like a window command, so that OnWindow events can change the focused window.

Attach pattern

Combines all windows that match the pattern into a single tab group. See CLIENT PATTERNS for more about the pattern arguments.

FocusLeft / FocusRight / FocusUp / FocusDown

Focus to the next window which is located in the direction specified.

ArrangeWindows pattern / ArrangeWindowsVertical pattern / ArrangeWindowsHorizontal pattern

Tries to arrange all windows on the current workspace so that they overlap the least amount possible. ArrangeWindowsVertical prefers vertical splits (windows side by side), whereas ArrangeWindowsHorizontal prefers horizontal splits (windows on top of eachother). See CLIENT PATTERNS for more about the pattern arguments.

ArrangeWindowsStackLeft pattern / ArrangeWindowsStackRight pattern

Similar to ArrangeWindows, these commands arrange windows on the current workspace. The currently focussed window is used as the main window, and will fill half the screen, while the other windows are tiled on the other half of the screen as if they were tiled with ArrangeWindows. ArrangeWindowsStackLeft puts the main window on the RIGHT hand side of the screen, and the tiled windows are on the LEFT hand side of the screen. ArrangeWindowsStackRight puts the main window on the LEFT hand side of the screen, and the tiled windows are on the RIGHT hand side of the screen.

ArrangeWindowsStackTop pattern / ArrangeWindowsStackBottom pattern

Behaves just like ArrangeWindowsStackLeft and ArrangeWindowsStackRight. ArrangeWindowsStackBottom places the main window on the TOP half of the screen, and the tiled windows on the bottom half of the screen. ArrangeWindowsStackTop places the main window on the BOTTOM half of the screen and the tiled windows on the top half of the screen.

ShowDesktop

Minimizes all windows on the current workspace. If they are already all minimized, then it restores them.

Deiconify mode destination

Deiconifies windows (or, restores from a minimized state). Where mode may be one of:

All

All icons across all workspaces.

AllWorkspace

All icons on the current workspace.

Last

The last icon across all workspaces.

LastWorkspace (default)

The last icon on the current workspace.

And destination may be one of:

Current (default)

Deiconify to the current workspace.

OriginQuiet

Deiconify to the window’s original workspace, but does so in the background, without moving you there.

SetWorkspaceName name / SetWorkspaceNameDialog

Sets the name of the current workspace.

CloseAllWindows

Closes all windows on all desktops.

### Menu Commands
These commands open or close fluxbox popup menus. For more information on what these menus contain or how to configure them, see fluxbox(1).

RootMenu

Opens the root menu. See ROOT MENU in fluxbox-menu(5) for details.

WorkspaceMenu

Opens a menu showing all workspaces and windows. See Workspace Menu in fluxbox(1) for details.

WindowMenu

Opens a menu containing actions for the current window. See WINDOW MENU in fluxbox-menu(5) for details. ClientMenu [pattern]

Opens a menu that contains all windows. If you specify a pattern, only matching windows will be in the menu. Selecting a window will jump to that workspace and raise the window. See CLIENT PATTERNS below for more details on the pattern argument.

CustomMenu path

Opens a custom menu file. This path must be a valid menu file in the same format as detailed by the ROOT MENU section of fluxbox-menu(5).

HideMenus

Hide all fluxbox popup menus.

### Window Manager Commands
These commands affect the Window Manager, or more than one window.

Restart [path]

Restarts fluxbox. This does not close any running applications. If the optional path is a path to an executable window manager, that manager is started in place of fluxbox.

Quit | Exit

Exits fluxbox. This will normally cause X to stop as well and terminate all existing applications, returning you to the login manager or console.

Reconfig | Reconfigure

Reloads all fluxbox configuration files including the keys file, apps file, and init file, if they have changed.

SetStyle path

Sets the current style to that given in path, which must be the full path to a fluxbox style.

ReloadStyle

Reloads only the current style. Useful after editing a style which is currently in use.

ExecCommand args ... | Exec args ... | Execute args ...

Probably the most-used binding of all. Passes all the arguments to your $SHELL (or /bin/sh if $SHELL is not set). You can use this to launch applications, run shell scripts, etc. Since all arguments are passed verbatim to the shell, you can use environment variables, pipes, or anything else the shell can do. Note that processes only see environment variables that were set before fluxbox started (such as in ~/.fluxbox/startup), or any that are set via the Export or SetEnv commands, below. See fluxbox(1) for more details on the ENVIRONMENT and \~/.fluxbox/startup file.

CommandDialog

Pops up a dialog box that lets you type in any of these commands manually.

SetEnv name value | Export name=value

Sets an environment variable in Fluxbox. It will be passed to any applications spawned by any future ExecCommand commands.

SetResourceValue resourcename resourcevalue | SetResourceValueDialog

Sets a fluxbox resource value, which are normally stored in the init file. See fluxbox(1) for more details on available resources and allowed values.

### Special Commands
These commands have special meanings or behaviors.

MacroCmd {command1} {command2} {command3} ...

Allows you to execute more than one command with one keybinding. The commands will be executed in series. The {} brackets are literally required, as in the following example:

```
MacroCmd {MoveTo 0 0} {ResizeTo 1280 800}
```

Delay {command} [microseconds]

Delays running command for the given amount of time. If the same key binding is activated again, the timer will be restarted.

ToggleCmd {command1} {command2} ...

Alternates between the commands. On the first press of the bound key, runs command1. On the next press, runs command2.

BindKey keybinding

Adds the given keybinding (which must be a valid key binding as defined in the DESCRIPTION section above) to your keys file.

KeyMode keymode [return-keybinding]

Activates the named keymode (or, all key binding lines prefaced with the same keymode:) and deactivates all others until the return-keybinding (by default Escape) is pressed. The default keymode is named default.

ForEach {command} [{condition}] | Map {command} [{condition}]

Runs the given command (normally one from the Window Commands section above) on each window. If you specify a condition (See Conditions, below) the action will be limited to matching windows.

If {condition} {then-command} [{else-command}] | Cond {condition} {then-command} [{else-command}]

If the condition command returns true, then run the then-command, otherwise run the optional else-command. See Conditions below for more information on the condition argument.

### Conditions
These special commands are used to match windows conditionally. They are commonly used by the If and ForEach command.

Matches pattern

Returns true if the current window matches the given pattern. See CLIENT PATTERNS below for details on the pattern syntax. If your key binding uses the OnWindow modifier, it matches against the window you clicked, not the currently focused window.

To check other windows besides the currently focused one, see the Every and Some conditions below.

Some condition

Returns true if any window on any workspace (not just the currently focused one) matches the condition.

Every condition

Returns true if every window on every workspace (not just the current one) matches the condition.

Not condition

Returns true if condition returns false, and vice-versa.

And {condition1} {condition2} [{condition3} ...]

Returns true if and only if all given conditions return true.

Or {condition1} {condition2} [{condition3} ...]

Returns true if any of the listed conditions return true.

Xor {condition1} {condition2} [{condition3} ...]

Returns the boolean xor of the truth values for all conditions listed.

## CLIENT PATTERNS
Many of the more advanced commands take a pattern argument, which allows you to direct the action at a specific window or set of windows which match the properties specified in the pattern.

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/keys

This is the default location for the keybinding definitions.

/usr/X11R6/include/X11/keysymdef.h

X key names are in this file.

/usr/X11R6/lib/X11/XKeysymDB

X key names are also in this file.

## RESOURCES
session.keyFile: location

This may be set to override the location of the keybinding definitions.

## ENVIRONMENT
Remember that ExecCommand command can take advantage of other environment variables if they are set before fluxbox is started, or via the Export or SetEnv commands. For example, if $TERM is set, it could be use like this:

```
Mod1 x :ExecCommand $TERM
```

For more information about environment variables, see your shell’s manual.

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

```
# Mod4+drag moves a window
OnWindow Mod4 Mouse1 :StartMoving
# If any xterm windows are open, cycle through them. If none are open, open
# one:
Mod4 t :If {Some Matches (xterm)} {NextWindow (xterm)} {Exec xterm}
# Set a different wallpaper on every workspace:
ChangeWorkspace :Exec fbsetbg ~/.fluxbox/bg$(xprop -root _NET_CURRENT_DESKTOP | awk '{print $3}').png
# Focusses the next window with it's xproperty 'PROP' set to 'foo'
Mod4 p Mod4 Tab :NextWindow (@PROP=foo)
```

## 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) xev(1) xkill(1) regex(7)

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

Author.


fluxbox-menu

title: fluxbox-menu(5)

summary: fluxbox(1) menu syntax

text:
# fluxbox-menu(5)

## NAME
fluxbox-menu - fluxbox(1) menu syntax

## SYNOPSIS
/usr/local/share/fluxbox/menu

~/.fluxbox/menu

~/.fluxbox/windowmenu

## 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
There are two types of menus in fluxbox which can be configured.

The first is the root menu, which normally appears when you right-click on the desktop.

The first is the ROOT MENU (Or right-click menu), is usually bound to a right-click on the desktop, though this binding can be changed in the ‘keys’ file (fluxbox-keys(5)). This same syntax is used for the CustomMenu command, also mentioned in fluxbox-keys(5).

Fluxbox installs a default root menu file in /usr/local/share/fluxbox/menu. You can also use fluxbox -i to confirm this location. Of course this system-wide menu can be customized for all users at once, but it is also possible to create an individual menu file for each user. By convention, users create a menu file in ~/.fluxbox/menu. Once you’ve created your own menu file, you’ll want to make sure that you properly declare this location in your ‘init’ file so that fluxbox knows where to look. See RESOURCES, below for details.

The second type is the WINDOW MENU, which defines the contents of the menu which appears when you right-click on a window’s titlebar or iconbar. This opens a menu file as defined by ~/.fluxbox/windowmenu. If this file does not exist, fluxbox will copy in the default from /usr/local/share/fluxbox/windowmenu.

You do not need to “reload” fluxbox after editing the apps file, the changes should be taken into account the next time you open the menu.

## ROOT MENU
The root menu must begin with a [begin] tag and end with an [end] tag, and every tag must be on its own line.

There are up to four fields in a menu line. They are of the form

[tag] (label) {command} <'icon'>

The <'icon'> field is always optional when shown below. If specified, the icon will be scaled down and displayed in the menu alongside the text label of the item. It must be in .xpm or .png format.

Any line that starts with a # or ! is considered a comment and ignored by fluxbox. Also, in the label/command/filename fields you can escape any character. Using \\ inserts a literal back-slash into the label/command/filename field.

You may enter labels, commands, and icons using characters from any iconv(1) language/locale by specifying the encoding used via the [encoding] tag, detailed below.

### Structural Tags
[begin] (title)

This tells fluxbox to start parsing the menu file. This tag is required for fluxbox to read your menu file. If it cannot find it, the system default menu is used in its place. The title appears at the top of the menu. And [end] tag is required to end the menu.

[submenu] (label) {title} <'icon'>

This tells fluxbox to create and parse a new menu, which is inserted as a submenu into the parent menu. These menus are parsed recursively, so there is no limit to the number of levels or nested submenus you can have. The label is the text that will appear in the parent menu, and the title is shown at the top of the submenu. If omitted, the title will be the same as the label. An [end] tag is required to end the submenu.

[end]

This tells fluxbox that it is at the end of a menu. This can either be a [submenu] or the [begin] tag of the main root menu. There must be at least one of these tags in your menu to correspond to the required [begin] tag, and one for each [submenu].

[encoding] {encoding}

This begins an [encoding] section and specifies the string encoding of all strings until the matching [endencoding] tag. For a list of available encodings on your system, run iconv -l.

[endencoding]

This ends an [encoding] section.

[include] (path)

Parses the file specified by filename inline with the current menu. The path can be the full path to a file or it can begin with ~/, which will be expanded into your home directory. If path is a directory, then all files in that directory are included.

[separator]

This will create a nice separation line. Useful for splitting up sections in a “pretty” way. The optional comment is not displayed, but can be useful for internal documentation or script parsing of menu files.

[nop] (label) <'icon'>

Insert a non-operational item into the current menu. This is much like [separator], but instead of a line, it inserts a label. This can be used to help format the menu into blocks or sections if so desired. The label is optional, and if omitted a blank item will be inserted.

### Applications
[exec] (label) {command...} <'icon'>

Inserts a command item into the menu. When you select the menu item from the menu, fluxbox runs command... in your $SHELL (or /bin/sh if $SHELL is not set). You can use this to launch applications, run shell scripts, etc. Since all arguments are passed verbatim to the shell, you can use environment variables, pipes, or anything else the shell can do. Note that processes only see environment variables that were set before fluxbox started (such as in ~/.fluxbox/startup).

### Fluxbox Functions
[config] (label) <'icon'>

Inserts a fluxbox native submenu item, containing numerous configuration options concerning window placement, focus style, window moving style, etc. See Configuration Menu in fluxbox(1) for details.

[reconfig] (label) <'icon'>

When selected this item re-reads the current style and menu files and applies any changes. This is useful for creating a new style or theme, as you don’t have to constantly restart fluxbox every time you save your style. However, fluxbox automatically rereads the menu whenever it changes.

[restart] (label) {command} <'icon'>

This tells fluxbox to restart. If command is supplied, it shuts down and runs the command (which is commonly the name of another window manager). If command is omitted, fluxbox restarts itself.

[exit] (label) <'icon'>

Inserts an item that shuts down and exits fluxbox. Any open windows are reparented to the root window before fluxbox exits.

[style] (label) {filename} <'icon'>

This tells fluxbox to insert an item that, when selected, reads style file named filename and apply the new textures, colors and fonts to the current running session.

[stylesmenu] (directory) <'icon'>

Reads all filenames from the specified directory, assuming that they are all valid style files, and creates inline menu items in the current menu for every filename, that, when selected by the user will apply the selected style file to the current session. The labels that are created in the menu are the filenames of the style files.

[stylesdir] (label) {directory} <'icon'>

Creates a submenu entry with label (that is also the title of the new submenu), and inserts in that submenu all filenames in the specified directory, assuming that they are all valid style files (directories are ignored) in the same way as the [stylesdir] command does. Both [stylesdir] and [stylesmenu] commands make it possible to install style files without editing your init file.

[wallpapers] (directory) {command} <'icon'>

This inserts a menu item to set the wallpaper for each file in the given directory. The command is optional, and defaults to fbsetbg.

[workspaces] (label) <'icon'>

This tells fluxbox to insert a link to the workspaces menu directly into your menu. See Workspace Menu in fluxbox(1) for details.

[command] (label) <'icon'>

In addition to the commands above, any legal keys file command may be used as a menu item. See fluxbox-keys(5) for more information.

## WINDOW MENU
Like the ROOT MENU, this menu file must start with [begin] and end with [end]. However, this file consists of only one [tag] per line with no labels, commands, or icons.

The available tags in this menu are:

[shade]

Provides a menu item to shade or unshade (or, roll-up) the window. This is equivalent to the shade titlebar button.

[stick]

Provides a menu item to stick or unstick the window. Stuck windows are displayed on all workspaces. This is equivalent to the stick titlebar button.

[maximize]

Provides a menu item to maximize or unmaximize the window, equivalent to the maximize titlebar button. The button with which you click alters the behaviour of this item as follows:

•Button 1 (Un)Maximize as normal.

•Button 2 (Un)Maximize window vertically.

•Button 3 (Un)Maximize window horizontally.

[iconify]

Provides a menu item to iconify (or, minimize) the window, equivalent to the iconify titlebar button.

[close]

Closes the window gracefully, equivalent to the titlebar button.

[kill]

Kills the window’s process, like xkill(1).

[raise]

Raise the window to the top of the stack within its layer.

[lower]

Lower the window to the bottom of the stack within its layer.

[settitledialog]

Opens a dialog which can be used to set the window’s title. Some applications may re-set their own title from time-to-time, wiping out your setting.

[sendto]

Sends the window to a different workspace. When you select the workspace with a middle-click, fluxbox will also change to the new workspace. A regular click only sends the window.

[layer]

Adds a “Layer...” submenu which lets you change the layer of this window.

[alpha]

Adds a “Transparency...” submenu which lets you change the focused and unfocused transparency of this window.

[extramenus]

Adds the “Remember...” menu item, which allows you to specify which settings should be stored in the ‘apps’ file (See fluxbox-apps(5) for more details).

[separator]

Adds a horizontal line to the menu

## FILES
~/.fluxbox/menu

This is the default location for the user’s root menu.

/usr/local/share/fluxbox/menu

This is the system-wide root menu file. It will be used if the user’s root menu is missing or unparseable.

~/.fluxbox/windowmenu

This is the user’s window menu definition file

/usr/local/share/fluxbox/menu

This is the default window menu. If the user does not have this file, it will be copied to ~/.fluxbox/windowmenu on fluxbox startup.

## RESOURCES
session.menuFile: location

This may be set to override the location of the user’s root menu.

## ENVIRONMENT
The comand... field of the [exec] tag can take advantage of other environment variables if they are set before fluxbox is started.

## EXAMPLES
Root Menu.

```
# fluxbox menu file
[begin] (fluxbox)

    [exec] (rxvt) {rxvt -ls} </usr/X11R6/share/icons/terminal.xpm>

    [exec] (netscape) {netscape -install}

    [exec] (The GIMP) {gimp}

    [exec] (XV) {xv}

    [exec] (Vim) {rxvt -geometry 132x60 -name VIM -e screen vim}

    [exec] (Mutt) {rxvt -name mutt -e mutt}

    [submenu] (mozilla)

        [exec] (browser) {mozilla -browser}

        [exec] (news) {mozilla -news}

        [exec] (mail) {mozilla -mail}

        [exec] (edit) {mozilla -edit}

        [exec] (compose) {mozilla -compose}

    [end]

    [submenu] (Window Manager)

        [exec] (Edit Menus) {nedit ~/.fluxbox/menu}

        [submenu] (Style) {Which Style?}

            [stylesdir] (~/.fluxbox/styles)

            [stylesmenu] (fluxbox Styles) {/usr/local/share/fluxbox/styles}

        [end]

        [config] (Config Options)

        [reconfig] (Reconfigure)

        [restart] (Restart)

    [end]

    [exit] (Log Out)
[end]
```

Default Window Menu.

```
[begin]

  [shade]

  [stick]

  [maximize]

  [iconify]

  [raise]

  [lower]

  [settitledialog]

  [sendto]

  [layer]

  [alpha]

  [extramenus]

  [separator]

  [close]
[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) fluxbox-keys(5) fluxbox-apps(5) xkill(1) iconv(1)

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

Author.