欢迎来到Flatpak文档¶

本文档覆盖了你需要使用Flatpak构建和分发应用的一切。先对Flatpak，基本概念的背景信息和Flatpak CLI进行一个简单的介绍，然后提供对构建和分发应用的详细信息。

本文档主要针对应用开发者和分发者。对Flatpak感兴趣的人也可以阅读相关内容。

如果你正在查找如何使用Flatpak来安装和运行应用，请参考 Flatpak网站。

目录¶

Flatpak简介¶

Flatpak是一个用于在Linux上分发桌面应用程序的框架。它由具有长期工作在Linux桌面的开发人员创建，并作为独立的开源项目运行。

目标受众¶

Flatpak可以被各种桌面应用程序使用，旨在尽可能与应用程序的构建方式无关。也对编程语言，构建工具，工具包或框架不作要求。

虽然Flatpak只能在Linux上运行，但它可以被针对其他操作系统的应用程序以及特定于Linux的应用程序使用。应用程序可以是开源的或专有的（尽管某些分发服务，如 Flathub ，在这方面可能有限制）。

Flatpak提出的唯一技术要求是应用程序遵循少量的Freedesktop标准，以实现桌面集成（参考要求与规范）。

使用Flatpak的理由¶

与其他在Linux上分发应用程序的方法相比，Flatpak具有一些主要优势。首先，Flatpak允许在几乎任何Linux发行版上安装和运行单个应用程序构建。它还可以与 Flathub 结合使用，Flathub是一种中心化服务，用于在所有发行版上分发应用程序。这使得应用开发者可以从一个地方瞄准整个Linux桌面市场。

Flatpak还为主要Linux桌面提供本机集成，以便用户可以通过现有的桌面环境和工具轻松浏览，安装，运行和使用Flatpak应用程序。

其他开发者可以得益的地方：

向前兼容：相同的Flatpak可以在同一发行版的不同版本上运行，包括尚未发布的版本。这不需要应用程序开发人员进行任何更改或管理。
维护平台：称为运行时，它们包含依赖项集合，可供应用程序使用，并且可以从应用程序开发中完成大量工作。
捆绑：这允许应用程序开发人员将几乎任何依赖项或库作为其应用程序的一部分。这样可以完全控制用于构建应用程序的软件。
一致的应用环境: 因为程序跑在一样的环境中，他们会按预期执行，这使得查找bug和测试变得容易。

最后，虽然Flatpak确实为分发应用程序提供了中心化服务，但它还允许分布式托管和分发，以便应用开发者或下游可以托管他们自己的应用和应用仓库。

关于Flatpak的更多信息可以参考 Flatpak原理。

开始使用¶

这部分包含对Flatpak概念的简单介绍，一份Flatpak CLI教程，以及一个构建简单应用的教程。

为了完成这部分，需要先安装Flatpak，启用Flathub。Flatpak官网提供了一份快速开始的教程。

基本概念¶

可以通过很少的关键概念来理解Flatpak，在学习如何使用Flatpak的命令行或者用它构建应用之前熟悉他们是很有用的。

运行时（runtime）¶

运行时提供应用程序使用的基本依赖项。每个应用程序都必须针对运行时构建，并且这个运行时必须安装在主机系统上，以便应用程序运行(Flatpak可以自动安装应用程序所需的运行时)。可以同时安装多个不同的运行时以及同一运行时的不同版本。

运行时是发行版无关的，而且不依赖发行版的特定版本。这意味着他们为应用程序提供了一个稳定、跨发行版的基础，这使得应用程序可以不管操作系统的升级

捆绑库¶

如果一个应用程序要求的依赖不在他的运行时里，这些依赖可以作为应用程序的一部分。这给了应用程序开发人员关于他们使用的依赖关系的灵活性，包括使用：

某个发行版或运行时不可用的库
某个发行版或运行时包含的库的另一版本
某个库的补丁版本

沙箱¶

使用Flatpak，每个应用程序都构建和运行在被称为“沙箱”的独立环境。每个沙箱包含一个应用和它的运行时。默认的，这个应用只能访问沙箱里面的内容。要访问用户文件、网络、图形套接字、总线上的子系统和设备必须被显式地授权。访问其它的东西，比如其它进程，是故意被设计成不可能的

一些沙箱的内部资源需要对外暴露，被宿主操作系统使用。这些被称为“导出”，因为它们是从沙箱中导出的文件，包括应用程序的“.desktop”文件和图标

门户¶

门户是一种机制，通过它，应用程序可以在沙箱中与宿主环境进行交互。它们提供了与数据、文件和服务交互的能力，这不需要添加沙箱权限

可以通过门户访问的功能示例包括通过文件选择器对话框打开文件或打印。接口工具包可以实现对门户的直接支持，从而实现对沙箱外资源的安全、便捷的访问。

更多关于门户的学习资源可以在沙箱权限找到

仓库¶

Flatpak应用和运行时通常使用仓库存储和发布，这个仓库和git仓库类似。一个Flatpak仓库可以包含单个或者多个对象，而且每个对象都是版本化的，可以升级和降级。

每个使用Flatpak的系统都可以配置多个远程仓库。一旦一个系统被配置成可以访问某个远程仓库，这个远程仓库的内容就可以被检测和搜索，它也可以被用作应用和运行时的源

执行更新时，应用和runtime会从相关的远程下载。和git一样，只有不同的部分会下载，使得升级过程十分高效。

使用Flatpak¶

这个页面介绍flatpak CLI，解释必要的技术约定和常用的命令。

最终用户不应该使用Flatpak CLI，因为Flatpak在有图形界面的软件管理器中非常容易使用。当然咯，如果他们更喜欢使用命令行的话，也可以使用Flatpak CLI。

flatpak命令¶

flatpak 是Flatpak的主命令, 其他的命令都跟在它后面。例如, 用 flatpak install 安装，用 flatpak uninstall 卸载。

标识符¶

Flatpak通过唯一的三元组标识应用和运行时，如 com.company.App 。地址的最后一段是对象名，前面的部分标识了开发者，所以同一个开发者可以开发多个应用，如 com.company.App1 和 com.company.App2 。

标识符三元组¶

一般来说，使用ID来引用一个对象是高效的。然而，有时候，我们需要指定对象的版本或者架构。例如，有些应用可能会提供稳定版和测试版，这种情况下，指定版本是很必要的。

Flatpak可以使用对象标识符三元组来指定架构和版本。格式是 name/architecture/branch ，如 com.company.App/i386/stable 。（分支是指向同一个版本的术语。这里也可以参考git里的概念）三元组的第一部分是ID，第二部分是架构，第三部分是分支。

标识符三元组也可以通过使用空白来仅指定架构或分支。如 com.company.App//stable 仅指定了分支， com.company.App/i386// 仅指定了架构。

如果架构或者分支需要指定，Flatpak CLI会有相应的反馈的。

System vs user¶

Flatpak命令既可以在系统级运行，也可以在用户级运行。安装在系统级的应用和运行时可以给当前系统的所有用户使用。安装在用户级的应用和运行时仅安装的用户可以使用。

上述原则也可以用于仓库。系统级的仓库可以给所有的用户使用，用户级仓库仅给安装的用户使用。

Flatpak命令默认运行在系统级。如果你安装应用是为了日常使用，我们推荐坚持默认行为。

然而，运行用户级命令对测试和开发很有用，因为用户级安装的对象不会给系统上其他的用户使用。如果使用用户级命令，可以使用 --user 选项，这个选项可以和大多数 flatpak 命令组合使用。

用户级运行命令和系统级运行命令行为一致。

基本命令¶

这本部分涵盖了安装，运行和管理Flatpak应用的基本命令。运行 flatpak --help 查看所有的Flatpak命令，或者参阅 Flatpak命令行参考文档。

列出远程仓库¶

运行下面的命令，列出在系统中已经配置好远程仓库：

$ flatpak remotes

列出已经添加了的远程仓库。列表表明每一个远程仓库是用户级的还是系统级的。

添加远程仓库¶

最方便的方式添加远程仓库是使用 .flatpakrepo 文件，它包含远程仓库的信息和GPG秘钥：

$ flatpak remote-add --if-not-exists flathub https://dl.flathub.org/repo/flathub.flatpakrepo

Here, flathub is the local name that is given to the remote. The URL points to the remote’s .flatpakrepo file. --if-not-exists stops the command from producing an error if the remote already exists.

移除远程仓库¶

运行下面的命令以移除远程仓库：

$ flatpak remote-delete flathub

In this case, flathub is the remote’s local name.

搜索¶

使用 search 命令查找远程仓库中的应用。如：

$ flatpak search gimp

搜索会返回匹配搜索词的应用。每一个搜索结果包含应用ID和应用所在的仓库。在这个例子中，搜索词是 gimp 。

注解

Flatpak 0.11.1以前，在搜索之前需要手动更新远程仓库的元数据。可以通过运行 flatpak update 或 flatpak update --appstream 完成。

安装应用¶

运行下面的明明安装应用：

$ flatpak install flathub org.gimp.GIMP

在这里, flathub 将要安装的远程应用名称, 而 org.gimp.GIMP 则是应用的ID。

有时，应用需要特定的运行时，运行时需要在安装应用前安装。

将要安装的应用的详细信息可以由 .flatpakref 文件提供， .flatpakref 文件可以是本地的，也可以是远程的。运行下面的命令指定 .flatpakref ，而不是手动指定远程仓库和应用ID。

$ flatpak install https://flathub.org/repo/appstream/org.gimp.GIMP.flatpakref

如果 .flatpakref 文件指定从远程仓库中安装的应用已经添加过，在应用安装前，将会被问到，哪一个应用应该添加。

运行应用¶

应用安装后，可以使用 run 命令和应用ID运行应用：

$ flatpak run org.gimp.GIMP

更新¶

运行下面的命令更新所有的应用和运行时到最新版本：

$ flatpak update

列出安装的应用¶

运行下面的命令，列出安装的应用和运行时：

$ flatpak list

运行下面的命令仅列出安装的应用：

$ flatpak list --app

移除应用¶

运行下面的命令移除应用：

$ flatpak uninstall org.gimp.GIMP

构建你的第一个flatpak应用¶

这个教程提供了一个构建flatpak的简单介绍。你可以从它学习到如何创建一个基础的可以被安装和运行的flatpak应用。

为了完成这个教程，你应该阅读 flatpak.org上的安装指南。同时需要安装 flatpak-builder ，它通常可以在 flatpak 包所在的仓库找到。

1.安装runtime和与之相匹配的SDK¶

flatpak要求每个应用指明一个runtime，作为它的基本依赖。每个runtime有一个匹配的SDK（软件开发套件），包含了runtime里面的所有东西，加上头文件和开发工具。构建应用的时候需要这个SDK。

In this tutorial we will use the Freedesktop 18.08 runtime and SDK. To install these, run:

$ flatpak install flathub org.freedesktop.Platform//18.08 org.freedesktop.Sdk//18.08

2.创建应用¶

这个教程要创建的个应用是一个简单的脚本。为了创建它，复制下面的内容:

#!/bin/sh
echo "Hello world, from a sandbox"

现在粘贴它到一个空文件然后保存为 hello.sh 。

3.添加一个清单文件¶

每个flatpak都用一个清单文件来构建，它提供了这个应用的基本信息和如何构建它的指令。为hello world应用添加一个清单文件，添加如下内容到一个空文件：

{
    "app-id": "org.flatpak.Hello",
    "runtime": "org.freedesktop.Platform",
    "runtime-version": "18.08",
    "sdk": "org.freedesktop.Sdk",
    "command": "hello.sh",
    "modules": [
        {
            "name": "hello",
            "buildsystem": "simple",
            "build-commands": [
                "install -D hello.sh /app/bin/hello.sh"
            ],
            "sources": [
                {
                    "type": "file",
                    "path": "hello.sh"
                }
            ]
        }
    ]
}

现在保存这个文件到 hello.sh 旁边，命名为 org.flatpak.Hello.json 。

在一个更加复杂的应用中，这个清单文件会列出多个模块。通常最后一个是应用本身，前面的是要和应用绑定的依赖，因为他们不是runtime的一部分。

4.构建应用¶

现在这个应用有一个清单文件， flatpak-builder 可以用来构建它。通过指明一个清单文件和一个目标目录:

$ flatpak-builder build-dir org.flatpak.Hello.json

这个命令会构建每个列在清单文件里的模块，然后将它安装到 build-dir 的 /app 子目录。

5.测试构建¶

为了确认构建成功，运行:

$ flatpak-builder --run build-dir org.flatpak.Hello.json hello.sh

恭喜，你已经创建了一个应用！

Keep in mind that using --run won’t result in a sandbox with the same permissions as the final app, as such it shouldn’t be relied upon beyond basic testing.

6.将应用放到仓库¶

在你运行和安装这个应用之前，它首先需要被放到一个仓库里。通过传递 --repo 参数给 flatpak-builder

$ flatpak-builder --repo=repo --force-clean build-dir org.flatpak.Hello.json

这将再次进行构建，最后将结果导出到名为 repo `` 的本地目录。注意， ``flatpak-builder 在 .flatpak-builder 子目录下保存了先前构建的缓存，所以像这样进行二次构建非常快。

第二次我们通过 --force-clean ，会在新的构建开始之前删除先前创建的 build-dir 目录。

7.安装应用¶

现在我们准备好添加创建的仓库并安装应用。通过两个命令来完成:

$ flatpak --user remote-add --no-gpg-verify tutorial-repo repo
$ flatpak --user install tutorial-repo org.flatpak.Hello

第一个命令添加先前步骤创建的的仓库。第二个命令从仓库安装应用。

两个命令都使用 --user 参数，表明仓库和应用是按照用户来添加而不是系统范围的。这在测试的时候很管用。

注意创建仓库添加了 --no-gpg-verify 参数，因为应用创建的时候没有指明GPG密钥。测试的时候这样做完全没有问题，但是官方的仓库必须使用一个私有的GPG秘钥签名。

8.运行应用¶

剩下的就是试用应用。通过执行如下命令:

$ flatpak run org.flatpak.Hello

这运行了应用，使它打印“Hello world, from a sandbox”。

构建¶

这个章节包含了如何构建一个Flatpak应用的详细信息。它介绍了构建过程的概况，如何解决应用程序依赖，如何使用 flatpak-builder ，以及书写清单文件的关键的指南和信息。

如果你还没有准备好，推荐在阅读本章节的之前先浏览构建你的第一个flatpak应用。

构建介绍¶

我们已在构建你的第一个flatpak应用一节中展示了如何使用Flatpak构建应用的简单案例。在本节中，我们将概述讨论构建过程涉及到的其他要素。

flatpak-builder¶

flatpak-builder 是构建Flatpak应用的基础工具. 它允许您获取应用程序的源文件，并将其构建为一个Flatpak应用程序。它还允许同时构建多个其他依赖项，这些依赖项被捆绑到构建中。

输入给 flatpak-builder 的是一个清单文件。它指定了要构建应用的参数，例如它的名字和依赖的运行时。这个清单还列出了作为构建过程的一部分构建的所有模块（不是很确定，译者注）。可以指定每个模块的源，包括指向文件存档或版本控制存储库的链接。某个模块（通常是最后一个）是应用代码它本身。

调用 flatpak-builder 的基本格式是:

$ flatpak-builder <build-dir> <manifest>

其中 <build-dir> 是构建应用程序的目标文件夹，<manifest> 是清单文件的路径。<build-dir> 中的内容可以被用来调试和测试应用程序，不过大多数情况下它只是构建过程的中间产物。

当 flatpak-builder 运行的时候：

构建目录如果不存在则进行创建
下载和验证每个模块的源代码
构建和安装每个模块的源代码
设置沙箱的权限并完成构建
构建结果会被导出到仓库（如果不存在将会被创建）

然后这个应用就可以从仓库进行安装和运行了

软件开发套件（SDKs）¶

Flatpak应用是在一个称作SDK的隔离环境中，而不是宿主的环境中构建的。

这些SDK类似与应用所运行在的常规运行时。不同的是，这些SDK还包含了构建一个应用需要的所有开发资源和工具，例如构建和打包工具、头文件、编译器和调试器

每个运行时都有一个附带的SDK。例如，一个GNOME 3.26 runtime和一个GNOME 3.26 SDK同时存在。使用这个运行时的是用这个对应的SDK构建的。

和运行时一样，一般SDK会自动地进行安装。但是如果你需要手动安装他们，他们的安装和运行时的安装一样，例如：

$ flatpak install flathub org.gnome.Sdk//3.26

要求与规范¶

Flatpak尽可能不对应用程序作出限制。不过，开发者应当尽可能遵循标准Linux桌面的规范，这主要是为了应用程序能更好地集成到Linux桌面和应用中心（App Center）。开发者也应尽可能遵循Linux技术规范。

更多有关桌面集成的选项可以参考桌面集成。

应当遵循的标准¶

使用Flatpak构建的应用应当遵循下列标准。一般而言，为Linux桌面设计的应用程序只需做少数改动即可符合这些标准。

应用ID¶

如使用Flatpak 所述，Flatpak要求每个应用都有一个独立的标识符，由三部分构成，例如 org.gnome.Dictionary 。我们在下面和后面的章节也会看到，ID在许多地方会用到。开发者在创建他们自己的ID的时候应该遵守 D-Bus naming conventions （D-Bus命名约定，译者注）标准。这种格式也被 Desktop File specification （Desktop文件规范，译者注）和 Appstream specification （AppStream规范，译者注）所推荐。

AppData文件¶

APPData文件提供了应用的元数据，可以被应用商店使用（例如Flathub、GNOME Software和KDE Discover）。 Freedesktop AppStream specification （APPStream规范）提供了一个AppData的完整参考。

AppData文件应该以应用的ID命名，并以 .appdata.xml 为文件扩展名，应该放在 /app/share/metainfo/ 。举个例子:

/app/share/metainfo/org.gnome.Dictionary.appdata.xml

appstream-util vlidate-relax 命令可以用于检查AppData文件的错误

应用图标¶

应用需要提供一个图标，用于应用启动器。这些图标应当与 Freedesktop icon specification （Freedesktop图标规范）一致。

图标应该以应用ID命名，以PNG或者SVG格式，而且必须放在标准的位置:

/app/share/icons/hicolor/$size/apps/

举个例子，128x128px版本的GNOME Dictionary的图标的路径应该是：

/app/share/icons/hicolor/128x128/apps/org.gnome.Dictionary.png

desktop文件¶

desktop文件用于向桌面环境报告每个应用程序的相关信息。Freedesktop specification 提供了编写desktop文件的完整指南，您也可以在 ArchLinux Wiki 上找到更多信息。

desktop文件应该以应用的ID命名，以 .desktop 为文件扩展名，而且应该放在 /app/share/applications/ 。举个例子:

/app/share/applications/org.gnome.Dictionary.desktop

一个desktop文件应当至少包含以下字段： name*（应用程序名）、*exec*（启动命令）、*type*（类型）、*icon*（图标名）和 *categories （所属分类）：

[Desktop Entry]
Name=Gnome Dictionary
Exec=org.gnome.Dictionary
Type=Application
Icon=org.gnome.Dictionary
Categories=GNOME;GTK;Office;Dictionary;

desktop-file-validate 命令可以用来检测desktop文件的错误。

技术规范¶

Flatpak和多数Linux桌面都遵循下列标准技术规范。有Linux使用经验的用户对此可能已有了解。首次使用Linux的开发者同样可以在这里找到有用的信息。

D-Bus¶

D-Bus是Linux桌面使用的标准IPC（进程间通讯，译者注）框架。大多数应用程序并不会用到D-Bus；但如果需要，Flatpak也同样提供D-Bus支持。

D-Bus可用于启动应用程序，以及系统服务之间的交互。应用程序也可以实现它们自己的D-Bus服务（此时，D-Bus服务的名称必须与应用程序的ID一致）。

Filesystem layout（文件系统布局，译者注）¶

每个Flatpak沙箱，一个应用运行的环境，包含这个应用的运行时的文件系统。这个准守 standard Linux filesystem conventions （标准Linux文件系统约定，译者注）。

举个例子，沙箱根目录包含 /etc 用于配置文件和 /usr 用于多用户utilities和应用。除此之外，每个沙箱包含一个顶级 /app/ 目录，用于应用自己文件的存放。

XDG基本目录¶

XDG基本目录指定用户应用数据的位置标准。很多工具包都提供了访问XDG基本目录的快捷方法。如:

Electron: 使用 app.getPath 访问XDG基本目录
Glib: 通过 g_get_user_cache_dir (), g_get_user_data_dir (), g_get_user_config_dir () 函数访问XDG基本目录
Qt: 通过 QStandardPaths Class 访问XDG基本目录

如果应用没有使用上述工具包，也可以通过下面的方式找到XDG基本目录：

基本目录	用途	默认位置
XDG_CONFIG_HOME	具体用户配置文件	~/.var/app/<app-id>/config
XDG_DATA_HOME	具体用户数据	~/.var/app/<app-id>/data
XDG_CACHE_HOME	Non-essential user-specific data（非基本具体用户数据，译者注）	~/.var/app/<app-id>/cache

举个例子，GNOME Dictionary会把具体用户数据存放在:

~/.var/org.gnome.Dictionary/data/gnome-dictionary

注意应用可以被配置成使用非默认基本目录（见沙箱权限)。

依赖¶

Flatpak为应用程序如何依赖于其他软件提供了许多不同的选项。在首次开始使用Flatpak构建应用程序时，因此有必要决定如何组织应用程序依赖关系。

此页面概括了这些选项是什么和在何时使用他们。

运行时¶

如基本概念中描述的，运行时提供了应用可以使用的基本依赖。他们提供了应用的运行环境。Flatpack要求每个应用需要指明一个运行时。因此，用Flatpack构建一个应用最先要确定的就是，应用要使用什么运行时。

我们可以在可用的运行时页面找到可用运行时的概览。有意地，只有少量运行时可供选择。通常，运行时是根据应用程序所需的依赖项来选择的。如果存在一个提供您计划使用的库的运行时，这通常是正确的运行时!

小技巧

运行时需要定期维护，应用程序开发人员通常不应该考虑创建自己的运行时。

当用户安装应用程序时，运行时将自动为他们安装，构建工具也可以为您自动安装它们（使用 flatpak-builder 的 --install-deps-from 选项）。但是，如果你想要手动地选择你的运行时，和安装一个应用类似，使用 flatpack install 命令。举个例子，安装GNOME 3.26运行时的命令:

$ flatpak install flathub org.gnome.Platform//3.26

构建¶

Flatpak的关键优势之一是它允许应用程序作者捆绑任何他们想要的库或依赖。这意味着开发人员不受某些库只在特定Linux发行版可用的约束。

当首次构建应用的时候，你需要确定绑定哪些依赖。这包括：

所选运行时不包含的库
所选运行时库的另一版本
打了补丁的库
作为应用一部分的数据或者资源

可以看到，作为构建过程的一部分，捆绑的依赖关系可以自动下载。开发者也可以对他们打补丁，或者作其他的更改。

虽然捆绑非常强大和灵活，但它也给应用程序开发人员带来了更大的维护负担。因此，尽管可以尽可能多地进行打包，但通常建议尽量减少打包模块的数量。如果依赖项作为运行时的一部分并是可用的，通常最好使用该版本，而不是自己打包。

如何捆绑库的细节在 mainifests 可以找到。

框架应用¶

运行时和捆绑是Flatpack处理依赖的两条主要途径。他们一方面允许应用建立在稳定的依赖集合上，另一方面又不失灵活性和控制。

可是，在某些情况下，依赖是一个更大的框架或者工具集，它不适合放进运行时，但手工捆绑成一系列单独的模块也很麻烦。所以有了 base apps 。

base apps包含了一个捆绑好的依赖的集合，这些依赖可以作为应用的一部分被捆绑。他们不会在构建过程中被重建，可以使得构建更快（特别是在构建大型的依赖时）。由于每个base app只构建一次，可以保证无论什么时候使用都是一样的，所以它只在磁盘保存一份。

base apps是一个相对专业的概念，只有一些应用需要使用他们（最常用的base app是用于 Electron applications ）。但是，如果你的应用使用一个巨大的，复杂的或者专用的框架，在开始构建的时候检查是否有可用的base apps是一个好主意。

Flatpak Builder¶

flatpak-builder 在构建你的第一个flatpak应用和构建介绍有过介绍。这个页面提供了更为详尽的 flatpak-builder 命令使用方法，如可用的命令行选项。

导出¶

flatpak-builder 为导出应用提供了两个选项。一个是导出仓库，然后从仓库运行。另一个是自动在本地安装。

导出到仓库¶

--repo 选项指定应用导出的仓库。格式为：

$ flatpak-builder --repo=<repo> <build-dir> <manifest>

<repo> 是仓库路径。如果仓库不存在，将创建一个新的仓库。如果应用在指定的仓库中已经存在， flatpak-builder 将会把当前构建作为已存在应用的一个新的版本。

注解

默认情况下， flatpak-builder 把翻译和调试信息分隔到 .Locale 和 .Debug 扩展中。

直接安装当前构建¶

使用 --install 选项，由 flatpak-builder 产生的Flatpak应用将自动安装到本地，而不是导出到仓库中。

$ flatpak-builder --install <build-dir> <manifest>

这个方式的优点是跳过了导出到仓库中必需的安装步骤。

签名¶

往Flatpak仓库中的每一次提交都需要使用GPG签名。如果用 flatpak-builder 修改或创建仓库，需要传一个GPG秘钥作为参数。使用方式是用 --gpg-sign 选项，如：

$ flatpak-builder --gpg-sign=<key> --repo=<repository> <manifest>

<key> 是使用的GPG秘钥的ID。也可以使用 --gpg-homedir 指定使用的秘钥的家目录。

尽管不推荐，但不使用GPG验证也是可以的。这种情况下，当添加仓库时，使用 --no-gpg-verify 选项。注意，为了更新没有启用GPG验证的仓库，有必要切换到root用户。

清单¶

flatpack-builder 是一个JSON文件，用于描述构建一个应用的参数，以及构建每个模块所用的指令。这个文件被称为清单文件。

这个页面提供了如何使用清单文件的信息和指南，包括需要指定的最常用参数的详解。读这一章节之前要求已经学习过构建你的第一个flatpak应用并且熟悉 Flatpak Builder 。

清单文件应该使用应用ID命名。举个例子：GNOME Dictionary的清单文件应该命名为 org.gnome.Dictionary.json .本页面使用这个清单文件，在构建你的第一个flatpak应用有对整个例子的介绍。

一个完整的属性列表可以在清单文件中指明，可以在 Flatpak Builder命令行参考文档和 flatpak-manifest 找到。

基本属性¶

每个清单文件应该指明要构建应用的基本信息，包括 app-id ， runtime ， runtime-version ， sdk 和 command 。这些属性通常在文件的开头进行声明。

举个例子，GNOME Dictionary的清单文件包含：

"app-id": "org.gnome.Dictionary",
"runtime": "org.gnome.Platform",
"runtime-version": "3.26",
"sdk": "org.gnome.Sdk",
"command": "gnome-dictionary",

指明runtime和runtime版本可以在用户的系统上自动安装你的应用需要的运行时。

文件重命名¶

正如 Flatpak简介中描述的，导出是对主机可用的应用文件，包含像 .desktop 文件和图标文件之类的。

flatpak导出的文件名字必须以应用ID为前缀，例如 org.gnome.Dictionary.desktop 。直接在应用源代码和资源中重命名这些文件是最佳方法。

如果无法使用应用ID重命名导出文件， flatpak-builder 允许在构建过程中重命名。可以通过在清单文件中指明下面的属性来实现：

rename-icon - 重命名应用图标
rename-desktop-file - 重命名 .desktop 文件
rename-appdata-file - 重命名AppData文件

每个属性都可以接受源文件重命名。 flatpak-builder 会自动重命名他们以匹配应用ID。注意这种重命名方法可能产生内部命名冲突，所以在文件树中进行重命名是最可靠的方法。

Finishing¶

flatpak应用默认运行在很有限的主机环境里面，但是应用需要访问沙箱之外的资源。finishing是用于指明应用沙箱权限的一步，用于访问外界资源。

finishing清单节点使用 finish-args 属性，可以在Dictionary的清单文件见到：

"finish-args": [
   "--socket=x11",
   "--share=network"
],

正如构建你的第一个flatpak应用中解释的，这两个属性为应用授予X11显示服务和网络的权限。权限的使用指南可以参考沙箱权限 , 所有的 finish-args 选项可以查看沙盒权限。

cleanup¶

cleanup属性用于移除构建过程中产生的，却不想保留的文件，例如头文件或者开发文档。清单文件中两个参数用于这个操作。第一个，一个文件名模板列表:

"cleanup": [ "/include", "/bin/foo-*", "*.a" ]

第二个cleanup属性是一系列命令，在cleanup阶段执行:

"cleanup-commands": [ "sed s/foo/bar/ /bin/app.sh" ]

cleanup属性可以根据每个模块进行设置，在这种情况下，只会匹配该特定的模块产生的文件名。

模块¶

这个模块列表作为构建过程的一部分，指明了每个模块。其中一个模块是应用本身，其他的是依赖和库，作为flatpak的一部分进行绑定。当应用比较简单的时候，只有一到两个模块，因此有较短的模块节点，一些应用会有大量的模块需要绑定，因此会有较长的模块节点。

GNOME Dictionary的模块节点是较短的，因为它仅仅包含应用本身，大概如下所示：

"modules": [
  {
    "name": "gnome-dictionary",
    "sources": [
      {
        "type": "archive",
        "url": "https://download.gnome.org/sources/gnome-dictionary/3.26/gnome-dictionary-3.26.0.tar.xz",
        "sha256": "387ff8fbb8091448453fd26dcf0b10053601c662e59581097bc0b54ced52e9ef"
      }
    ]
  }
]

可以看出，每个列出的模块有一个 name （可以自由分配）和一个 sources 列表。每个source都有一个 type ，可用的type有：

archive - .tar or .zip 归档文件

git - Git 仓库

bzr - Bazaar 仓库

file - 本地文件（这些复制到源码目录）

dir - 本地目录 (这些将复制到源码目录)

script - 一个shell命令数组（这些都被放在shell脚本文件里）

shell - 再源码抽取期间运行的一组shell命令

patch - 补丁（用于源代码目录）

extra-data - 在安装时下载的数据；可以包含归档文件或者package文件

每种source类型有不同的属性，在 Flatpak Builder命令行参考文档列出了。

受支持的构建系统¶

模块可以用多种构建系统构建，包含：

一个“简单的”构建方法，需要指定一系列命令。

实例清单文件¶

一个完整的GNOME Dictionary清单文件 . 你也可以浏览 Flathub托管的所有清单文件。

沙箱权限¶

flatpak的一个主要目标就是通过应用间的隔离来提高桌面系统的安全性。这通过使用沙箱来实现，默认地，应用运行的环境对主机的访问很有限。这包括：

无法访问除runtime、app目录和 ~/.var/app/$APPID 目录以外的文件。而且只有最后一个目录（译者注：即 ~/.var/app/$APPID 目录）有写权限。
无法访问网络。
无法访问任何设备节点的（除了 /dev/null ，等等）。（译者注：可能有访问所有null设备的权限）
无法访问沙箱之外进程
有限的系统调用。举个例子，应用无法使用非标准的网络socket或者ptrace其他进程。
有限地访问D-Bus实例的session——一个应用在总线上只能拥有它自己的名字。
无法访问主机服务，像X11，system D-Bus或PulseAudio这些。

大部分应用需要访问这些资源。这些主要是在finishing构建步骤完成的，通过清单文件（查看清单）的 finish-args 部分来配置。

门户（译者注：英文portals）¶

门户已经在 Flatpak简介提到过。他们是一个提供沙箱外资源访问的框架。包括这些资源：

用一个本地的文件选择对话框打开文件
打开URL
打印
显示通知
截取屏幕
禁止用户会话结束、暂停、空转或切换。
获取网络状态信息

在许多情况下，门户通过使用系统组件在获取访问某些特定资源的权限之前隐式地向用户获得了许可。举个例子，在打开一个文件的时候，用户用文件选择对话框进行文件选择，可以理解为隐式地授予了应用对选中文件的访问。

这种方式使得应用在需要访问大量数据或服务时避免重复配置，也让用户可以掌控（译者注：知悉，了解）他们的应用的访问权限。

像GTK3和Qt5这样的接口工具包实现了对门户的透明支持，这意味着应用程序不需要做任何额外的工作来使用它们(每个工具包支持哪些门户值得了解)。没有使用受支持工具包的应用可以参考 xdg-desktop-portal API 文档。

权限手册¶

虽然应用程序开发人员可以控制他们想要配置的沙箱权限，但是鼓励进行良好的实践。举个例子，Flathub主机托管服务对权限的使用提出了要求，如果使用了某些权限，主机上的软件可能会警告用户。

后面的手册描述了哪些权限可以任意使用，哪些可以根据需要使用，哪些应该避免使用。

标准权限¶

以下权限提供了应用通常需要访问的基本资源，因此可以自由使用：

--share=network - 访问网络
--socket=x11 - show windows using X11
--socket=fallback-x11 - 如果Wayland不可用，使用X11显示窗口
--share=ipc - 和主机共享IPC命名空间 (对于X11是必要的)
--socket=wayland - 使用Wayland显示窗口
--device=dri - OpenGL 渲染
--socket=pulseaudio - 使用PulseAudio播放音频

D-Bus访问¶

避免使用 --socket=system-bus 或 --socket=session-bus 访问整个总线，除非应用是一个开发工具。

Ownership

应用会自动为他们自己命名空间授予访问权限，通常不需要有所有权，尽管如此还是有少量的例外，例如使用 MPRIS来提供媒体控制。

Talk

Talk权限可以自由使用，尽管如此还是推荐使用应用所需的最小权限。

文件系统访问¶

应用要求范围主机文件系统的不同部分是很正常的，flatpak为此提供了一套灵活的选项。下面是一些例子：

--filesystem=host - 访问主机的常规文件，不包含一下提到的主机操作系统或者系统内部
--filesystem=home - 访问用户home目录
--filesystem=/path/path - 访问特定路径
--filesystem=xdg-download - 访问特定的XDG文件夹

作为一个通用规则，对文件系统的访问应该尽可能地进行限制。这包括：

尽量使用门户来代替文件系统访问。
尽量使用读取权限来访问，使用 :ro 选项。
如果一定要访问home目录，只使用XDG目录访问。

完整的文件系统可用选项列表可以在沙盒权限找到。其它文件系统访问指南包含：

--persist=path 选项可以用来将用户目录映射到沙箱的文件系统。这可以避免配置整个home目录访问权限。并且对于在硬编码使用 ~/ 文件路径的应用程序非常有用。
If an application uses $TMPDIR to contain lock files you may want to add --env=TMPDIR=/var/tmp or if it uses $TMPDIR to share with processes outside the sandbox you will want a wrapper script that sets it to $XDG_CACHE_HOME.
应该避免与非flatpak安装的应用共享配置。

如上所述， host 选项实际上没有提供主机文件系统的完整访问。主要的规则是：

这些目录是屏蔽掉的： /lib , /lib32 , /lib64 , /bin , /sbin , /usr , /boot , /root , /tmp , /etc , /app , /run , /proc , /sys , /dev , /var
/run/media 例外
这些目录被挂载到 /var/run/host : /etc ， /usr

许多目录被屏蔽的原因是他们已经在沙箱里存在了：例如 /usr 或者是一些在沙箱中不可用的目录。

设备访问¶

尽管不理想， --device=all 可以用来访问控制器和网络摄像头之类的设备。

dconf访问¶

在沙箱兼容后端可用之前，需要访问dconf的应用程序可以使用以下选项:

--filesystem=xdg-run/dconf
--filesystem=~/.config/dconf:ro
--talk-name=ca.desrt.dconf
--env=DCONF_USER_CONFIG_DIR=.config/dconf

教程¶

Flatpak提供了一系列选项和辅助工具，允许使用最常用的编程语言和开发平台构建应用。下面的页面提供了一些信息，旨在补充在文档其他地方的标准指南。

Python¶

使用受支持的构建系统（如Meson，CMake或Autotools）的Python应用程序可以使用标准方法构建。但是，许多Python应用程序使用自定义安装脚本，或者希望通过Setuptools和``pip`` 安装。

对于这些情况，flatpak-builder 提供了 simple 构建系统。和自动化构建过程不同， simple 接受一个 build`-commands 的字符数组，将按顺序执行。

举个例子，用如下的JSON构建流行的模块非常简单：

{
  "name": "requests",
  "buildsystem": "simple",
  "build-commands": [
    "pip3 install --prefix=/app --no-deps ."
  ],
  "sources": [
    {
      "type": "archive",
      "url": "https://files.pythonhosted.org/packages/source/r/requests/requests-2.18.4.tar.gz",
      "sha256": "9c443e7324ba5b85070c4a818ade28bfabedf16ea10206da1132edaa6dda237e"
    }
  ]
}

这里，build-commands 是一个数组，包含了构建和安装模块的命令。可以看到，在这种情况下 pip 被用来安装模块。--prefix=/app 选项很重要，因为原本 pip 会尝试将模块安装到 /usr/ 目录下，又由于 /usr/ 在沙箱中是挂载为只读的，安装会失败。

注意 --no-deps 仅仅用于实例——一旦依赖的模块有它自己的依赖，构建就会失败。如果存在许多依赖，最好是用下一章节的方法来安装。

构建多个python依赖¶

尽管上述的例子被安装了，它实际上也不能正常运行。正式因为它有大量的依赖没有安装：

certifi
chardet
idna
urllib3

四个依赖不是很多，可以用上述的 simple 的方法来安装。但是，任何比这个复杂的很快都会变得冗长。

在这种情况下，flatpak-pip-generator 可以用来产生必要的清单JSON。这是一个Python脚本，可以获取包名和使用``pip``来确定依赖，以及依赖包的压缩包URL和hashes值。

使用 flatpak-pip-generator 是简单的:

$ python3 flatpak-pip-generator requests

这将输出一个名为 python3-requests.json 的文件，包含了必要的清单JSON，这个JSON可以放在应用的清单文件里。

Electron¶

由于Electron的性质，与其他应用相比，将Electron应用构建为Flatpak应用需要一些额外的步骤。值得庆幸的是，有几种工具和资源可以使这些步骤更容易。

本教程提供有关如何构建Electron应用程序与其他应用程序不同的信息。它还包括有关构建Electron应用程序的工具以及如何使用它的信息。

该指南介绍了清单文件，来自示例Electron Flatpak应用程序。在开始之前，最好先在线查看或下载该应用程序。

构建示例应用程序¶

虽然并非绝对必要，但最好自己尝试构建和运行示例应用程序。

要获取构建的设置，请从GitHub下载或克隆示例应用程序，然后导航到终端中的 /flatpak 目录。您还必须安装Electron基础应用程序：

$ flatpak install flathub io.atom.electron.BaseApp//stable

然后运行构建命令：

$ flatpak-builder build org.flathub.electron-sample-app.json --install

最后，运行应用：

$ flatpak run org.flatpak.electron-sample-app

基本配置¶

示例应用清单文件的第一部分指定了应用ID、runtime和SDK：

"app-id": "org.flathub.electron-sample-app",
"runtime": "org.freedesktop.Platform",
"runtime-version": "1.6",
"branch": "stable",
"sdk": "org.freedesktop.Sdk",

Freedesktop运行时通常是与Electron应用程序一起使用的最佳运行时，因为它是最小的运行时，其他依赖项将特定于Electron本身。

Electron base应用¶

然后，清单文件通过 base 和 base-version 属性指明了Electron要使用的的base app:

"base": "io.atom.electron.BaseApp",
"base-version": "stable",

base app在 building-basics 有介绍。使用Electron的base app比手动构建Electron和它的依赖要方便和快速得多。也有在用户的机器上减少大量副本文件的优点，因为这意味着Electron在磁盘上只保存一份。

注意这个项目的base app是使用的Electron1.x.x，是写这个项目时最通用的版本。Electron2.x.x的应用应该用 org.electronjs.Electron2.Baseapp 代替。

命令¶

这个 command 表明执行一个名为 run.sh 的脚本用来运行这个应用。这会在后续详细介绍。

"command": "run.sh",

沙箱权限¶

标准的指南可以用于Electron应用。可是Electron还不支持Wayland，所以只能使用X11进行显示。示例的应用也为声音配置了pulseaudio和开启了网络的访问：

"finish-args": [
    "--share=ipc",
    "--socket=x11",
    "--socket=pulseaudio",
    "--share=network"
],

构建选项¶

构建选项不是必要的，但是在发生一些错误的时候很有用。 env 允许设置一个环境变量数组，这时将 NPM_CONFIG_LOGLEVEL 设置为 info 可以让 npm 给我们更多关于错误的详情。

"build-options" : {
    "cflags": "-O2 -g",
    "cxxflags": "-O2 -g",
    "env": {
        "NPM_CONFIG_LOGLEVEL": "info"
    }
},

构建Node.js¶

清单文件的下一部分是模块列表。Electron base app不包含Node.js，所以有必要将Node.js作为一个模块进行构建。教程构建了Node.js 8.11.1，在写这个教程的时候这个版本可以在大多数项目上正常工作，但是请确保使用在你的项目工作得最好的版本。

{
    "name": "nodejs",
    "cleanup": [
        "/include",
        "/share",
        "/app/lib/node_modules/npm/changelogs",
        "/app/lib/node_modules/npm/doc",
        "/app/lib/node_modules/npm/html",
        "/app/lib/node_modules/npm/man",
        "/app/lib/node_modules/npm/scripts"
    ],
    "sources": [
        {
            "type": "archive",
            "url": "https://nodejs.org/dist/v8.11.1/node-v8.11.1.tar.xz",
            "sha256": "40a6eb51ea37fafcf0cfb58786b15b99152bec672cccf861c14d1cca0ad4758a"
        }
    ]
}

清理步骤也不是必要的。但是，移除文档可以帮助我们减少绑定所占用的空间。

应用模块¶

清单文件的最后一部分是定义应用模块如何构建。可以找到一些Electron和Node.js的一些附加逻辑。

"name": "electron-sample-app",
"build-options" : {
    "env": {
        "electron_config_cache": "/run/build/electron-sample-app/npm-cache"
    }
},

flatpak-builder 默认不能访问网络。这意味着依赖于下载资源的工具无法工作。因此，Node.js包必须在构建之前提前下载好。设置环境变量 electron_config_cache 表明这些包会在构建的时候被找到。

清单文件的下一部分描述了怎样构建应用。使用了简单构建系统的选项，允许指定一系列命令来构建。下载地址和应用的hash也会进行指定。

"buildsystem": "simple",
"sources": [
  {
      "type": "archive",
      "url": "https://github.com/flathub/electron-sample-app/archive/1.0.1.tar.gz",
      "sha256": "a2feb3f1cf002a2e4e8900f718cc5c54db4ad174e48bfcfbddcd588c7b716d5b",
      "dest": "main"
  },

绑定NPM包¶

下一行是NPM模块如何作为flatpak的一部分进行绑定：

"generated-sources.json",

Since even simple Node.js applications depend on dozens of packages, it would be impractical to specify all of them as part of a manifest file. A Python script has therefore been developed to download Node.js packages with NPM and include them in an application’s sources.

这个Python NPM脚本需要一个 package-lock.json 文件。它包含了应用依赖包的信息，可以在应用根目录运行 npm install --package-lock-only 生成（示例包含了一个 package-lock.json 供参考）。下面运行这个脚本:

$ python3 flatpak-npm-generator.py package-lock.json

这生成了为应用构建NPM包的JSON清单（译者注：区别于应用的清单文件），输出一个名为 generated-sources.json 的文件。这个文件的内容可以拷贝到应用的清单文件中，但是因为通常它非常长，最好是从主要的清单链接它。如上所示，可以在清单文件中添加一行 generated-source.json 来实现链接。

启动应用¶

Electron应用通过一个简单的脚本文件运行。可以用任何名字，但是必须在清单文件中 “command": 属性指明。

/* Wrapper to launch the app */
{
  "type": "script",
  "dest-filename": "run.sh",
  "commands": [ "npm start --prefix=/app/main" ]
}

构建命令¶

最后但不是不重要，因为使用了简单构建选项，必须要提供一个构建命令列表。可以看到，npm 以 --offline 选项运行，使用的包已经缓存好了。这些被拷贝到了 /app/main/ 。最后 run.sh 脚本安装到了 /app/bin/ ，所以最后它会在 $PATH ：

"build-commands": [
    /* Install npm dependencies */
    "npm install --prefix=main --offline --cache=/run/build/electron-sample-app/npm-cache/",
    /* Bundle app and dependencies */
    "mkdir -p /app/main /app/bin",
    "cp -ra main/* /app/main/",
    /* Install app wrapper */
    "install run.sh /app/bin/"
]

调试¶

这部分文档包含如何调试Flatpak应用。

运行调试工具¶

因为Flatpak在沙盒中运行应用，调试工具不能以通常的方式使用，而必须运行在沙盒中。为了在应用沙盒中运行shell，需要使用 --command 选项运行：

$ flatpak run --command=sh --devel <application-id>

为给定ID的应用创建一个沙盒，而不是运行应用，在沙盒中运行shell。根据shell的提示，然后可以运行应用。也可以使用任何你想用的调试工具。如，通过 gdb 运行应用：

$ gdb /app/bin/<application-binary>

这是如何工作的呢？ --devel 选项告诉Flatpak使用SDK作为运行时，而SDK含有像 gdb 这样的调试工具。 --devel 选项也让沙盒初始化时启动调试。

注解

Freedesktop SDK（许多其他的SDK基于这个）含有许多调试工具，如： gdb , strace , nm , dbus-send , dconf 等等。

当有权限调试应用和使用的运行时时， gdb 是很有用的。Flatpak会把调试信息分离到扩展中，你在调试前需要安装这些扩展：

$ flatpak install <runtime-id>.Debug

当使用 --devel 选项时，Flatpak将自动使用任何它能找到的匹配的调试扩展。

在没有安装调试扩展的情况下，也可以在应用沙盒中运行shell。这通过使用 flatpak-builder 的 --run 选项完成：

$ flatpak-builder --run <build-dir> <manifest> sh

启动一个含有构建结果的沙盒，然后在沙盒里运行shell。

创建调试扩展¶

像其他的包系统一样，Flatpak也把笨重的调试信息和常规内容分离，作为 .Debug 扩展单独使用。

当构建一个应用时， flatpak-builder 自动创建一个 .Debug 扩展。可以使用 no-debuginfo 选项禁止这个行为。

覆盖沙盒权限¶

当调试的时候，使用额外的权限有时是很有用的。这可以通过使用运行命令接受的各种选项实现。如：

$ flatpak run --devel --command=sh --system-talk-name=org.freedesktop.login1 <application-id>

此命令在给定应用程序的沙箱中运行shell，授予它访问logind对应的D-Bus服务的权限。

发布¶

Flatpak提供了多种方式分发应用给用户。对大多数应用来说，最方便最高效的方法是使用 Flathub , 它为Flatpak应用提供了一个大型中心化的仓库。

除此以外，也可以自己托管仓库或者使用单文件分发Flatpak应用。

仓库¶

Flatpak存储库是发布应用程序的主要机制，因此可以由用户安装。

存储库的某些方面由文档的其他部分解决。可以在使用Flatpak 部分中找到用于添加，删除和检查存储库的基本命令。此外， Flatpak Builder 上的部分介绍了将应用程序添加到存储库的最常用方法。

要使用存储库发布应用程序，可以托管您自己的(在下一节中介绍, 托管一个仓库) 或者使用 Flathub, 它是Flatpak应用程序的主要发布和托管服务。

GNOME软件或KDE Discover等软件中心应用程序允许浏览存储库，还可以动态地推广新的或流行的应用程序。如果使用Flathub，则用户通常已添加存储库，因此向存储库添加应用程序足以使其可用。

.flatpakref 文件¶

.flatpakref 文件可以与存储库结合使用，为用户安装应用程序提供额外的简便方法，通常是通过单击文件或下载链接。

在内部， .flatpakref 文件是简单的描述文件，其中包含有关Flatpak应用程序的信息。一个例子：

[Flatpak Ref]
Name=fr.free.Homebank
Branch=stable
Title=fr.free.Homebank from flathub
Url=https://dl.flathub.org/repo/
RuntimeRepo=https://dl.flathub.org/repo/flathub.flatpakrepo
IsRuntime=false
GPGKey=mQINBFlD2sABEADsiUZUO...

如你所见，该文件包括应用程序的ID以及包含它的存储库的位置，以及指向提供应用程序运行时存储库信息的链接。 .flatpakref 文件包含安装应用程序所需的所有信息。

注解

.flatpakref 文件应包含用于对存储库进行签名的GPG密钥的base64编码版本。这可以使用以下命令获得：

$ base64 --wrap=0 < key.gpg

.flatpakref 文件的一个优点是，即使用户尚未添加其存储库，它们也可用于安装应用程序。在这种情况下，将自动安装包含应用程序的存储库，或者将提示用户安装它。如果不存在必要的运行时，也会发生这种情况。

.flatpakref 可用于从命令行以及图形软件安装程序安装应用程序。这是通过标准的 flatpak install 命令完成的，该命令接受本地和远程 .flatpakref 文件。例如：

$ flatpak install https://flathub.org/repo/appstream/fr.free.Homebank.flatpakref

或者是下载好的文件：

$ flatpak install fr.free.Homebank.flatpakref

发布更新¶

Flatpak存储库类似于Git存储库，因为它们通过记录每个版本之间的差异来存储应用程序的每个版本。这使得更新有效，因为在执行更新时仅需要下载两个版本之间的差异（或“增量”）。

将新版本的应用程序添加到存储库时，它立即可供用户使用。软件中心能够自动检查并安装新版本。那些使用命令行的人必须手动运行flatpak update来检查并安装他们已安装的任何应用程序的新版本。

托管一个仓库¶

Flatpak Builder 这部分描述了如何生成仓库。生成的仓库可以托管到一个web服务器供用户使用。

重要的细节¶

flatpak仓库使用archive-z2，意味着将所有文件打包成单个文件。拉取（译者注：pull）操作发起许多HTTP请求。因为新请求会很慢，所以在仓库所在web服务器开启HTTP keep-alive是很重要的。

Flatpak支持所谓的静态增量。这些是单个文件，包含在两个修订(或从无到修订)之间所需的所有数据。创建这样的增量会占用服务器上更多的空间，但下载速度会更快。这可以通过 `` build-update-repo –generate-static-delta `` 选项来完成。

.flatpckrepo 文件¶

.flatpakrepo 文件是用户添加一个仓库的方便的方法。这些是包含仓库信息的简单描述文件。举个例子：Flathub的repo文件像这样:

[Flatpak Repo]
Title=Flathub
Url=https://dl.flathub.org/repo/
Homepage=https://flathub.org/
Comment=Central repository of Flatpak applications
Description=Central repository of Flatpak applications
Icon=https://dl.flathub.org/repo/logo.svg
GPGKey=mQINBFlD2sABEADsiUZUO...

你可以看到repo文件包含描述性的元数据，例如仓库名字、描述、图标和网站。也包含了需要添加到仓库的信息，一个下载URL和仓库的GPG密钥。

可以通过用命令行用 .flatpakrepo 文件添加仓库。举个例子，使用repo文件添加Flathub的命令是:

$ flatpak remote-add --if-not-exists flathub https://dl.flathub.org/repo/flathub.flatpakrepo

使用 .flatpakrepo 文件不是添加仓库的唯一方法，添加一个仓库只是点击一个repo文件或者指向一个下载链接的问题。

注解

.flatpakrepo 文件应该包含base64-encoded GPG密钥版本，用于对仓库进行签名。可以通过如下命令获得:

$ base64 --wrap=0 < key.gpg

单文件包¶

托管仓库是一个很好的方式分发应用，因为仓库允许应用更新。然而，有时候使用单文件包是很合适的。单文件包可以直接下载，使用可移动媒介分发应用或者作为邮件附件发送。

Flatpak可以使用 build-bundle 和 build-import-bundle 命令创建单文件包。它们可以将仓库转换为单文件包，也可以将单文件包转换为仓库。

$ flatpak build-bundle [OPTION...] LOCATION FILENAME NAME [BRANCH]
$ flatpak build-import-bundle [OPTION...] LOCATION FILENAME

例如：从仓库~/repositories/apps中创建一个含有GNOME字典应用名为 dictionary.flatpak 单文件包。

$ flatpak build-bundle ~/repositories/apps dictionary.flatpak org.gnome.Dictionary

可以在单文件包中设置runtime仓库:

$ flatpak build-bundle ~/repositories/apps dictionary.flatpak org.gnome.Dictionary --runtime-repo=https://flathub.org/repo/flathub.flatpakrepo

运行下面的命令，将单文件包导入到另外一个机器的仓库中：

$ flatpak build-import-bundle ~/my-apps dictionary.flatpak

不导入的话，单文件包也可以直接安装：

$ flatpak install dictionary.flatpak

桌面集成¶

要求与规范涵盖了Linux桌面集成的必要方面。这个页面提供了更多可选的桌面集成特性的信息。它也提供了一个指南，便于开发者让程序的用户界面兼容多数Linux桌面和发行版。

这些信息主要是为刚接触Linux的开发者准备的。不过它也适用于那些希望把特定应用推广到更多Linux发行版的开发者。

开发适用于Linux生态的应用可能是一项挑战性的任务，但现有的标准和指南会帮助开发者更方便地适配大多数Linux环境。

检测区域设置¶

应用程序的工具集（如Electron、GTK和Qt）默认提供了检测区域的功能。除此此外，你也可以使用 setlocale 。

门户¶

门户是用于安全访问沙箱外资源的框架。沙箱内程序可以使用的特性包括：

检测网络状态
使用文件选择器来打开文件
打开URI
阻止设备关机、休眠或进入待机状态
打印
发送邮件
显示通知
截取屏幕或录屏

GTK和Qt等工具集默认提供了对门户的支持。如果您使用的不是这类工具集，也可以直接使用门户的API来实现上述功能。请参考 portals API documentation 以获取更多信息。

通知¶

A number of toolkits and frameworks provide transparent support for Linux desktop notificatoions. This includes Electron, GTK, KDE and QML.

状态图标¶

状态图标对应于Windows系统中的系统托盘/任务栏图标，或者Mac系统中的菜单栏图标。大多数Linux发行版通过libappindicator提供对状态图标的支持。

部分Linux发行版不显示状态图标；不过您仍然可以设置一个图标，以便它可以在其他发行版中显示出来。出于对兼容性的考虑，建议您只把状态图标作为应用交互逻辑的补充，而不是用于实现特定功能或显示特定信息的唯一入口（包括“最小化到托盘”这一功能）。

系统内搜索¶

使用GNOME桌面的发行版，如CentOS、Fedora、Red Hat Enterprise Linux和Ubuntu整合了系统范围内搜索的功能： search provider 。这使得应用程序可以将特定内容添加到沙箱外 Activities Overview（活动列表，译者注）并显示给用户。

窗口控制¶

窗口控件是关闭、最大化、最小化窗口的按钮。这些在不同的Linux桌面是不同的，特别是在要显示哪些控件方面。应用程序是否试图遵循这些变化取决于它们的判断力。提供与特定桌面环境所使用的完全相同的控件不应该被视为硬性要求。

从用户体验的角度来看，确保窗口控件出现在窗口的同一侧与其他桌面是很重要的。在Linux上，这是窗口的右侧(就像Windows一样)。

如果应用程序不想绘制自己的窗口控件，则可以依赖Linux上系统提供的标题栏。

窗口美化¶

如果您的应用程序使用深色视觉样式以及系统提供的窗口装饰，那么应该使用 GTK_THEME_VARIANT=dark 这个X11窗口属性，以确保窗口装饰与应用程序窗口的其余部分匹配。通过运行:

xprop -f _GTK_THEME_VARIANT 8u -set _GTK_THEME_VARIANT dark

已废弃的选项¶

以下桌面集成选项不再使用，可以安全地忽略：

应用程序菜单——这些是特定于GNOME桌面的。然而，它们可能会在未来逐步淘汰。
全局菜单栏——这是一个类似于Mac菜单栏的功能，它是Ubuntu Unity桌面的一部分。这个已经退休了。所有Linux桌面和发行版都希望在应用程序窗口中显示菜单栏(而不是像Mac那样依赖全局菜单栏)。

参考文档¶

Reference documentation for flatpak, flatpak-builder and libflatpak.

Flatpak命令行参考文档¶

Flatpak Command Reference

Version 0.99.3

Important

The command reference is generated from the flatpak repo; see https://github.com/flatpak/flatpak/tree/master/doc

Flatpak comes with a rich commandline interface.

Table of Contents

Executables

flatpak — Build, install and run applications and runtimes

Commands

flatpak build-bundle — Create a single-file bundle from a local repository
flatpak build-commit-from — Create new commits based on existing one (possibly from another repository)
flatpak build-export — Create a repository from a build directory
flatpak build-finish — Finalize a build directory
flatpak build-import-bundle — Import a file bundle into a local repository
flatpak build-init — Initialize a build directory
flatpak build-sign — Sign an application or runtime
flatpak build-update-repo — Create a repository from a build directory
flatpak build — Build in a directory
flatpak config — Manage configuration
flatpak create-usb — Copy apps and/or runtimes onto removable media.
flatpak document-export — Export a file to a sandboxed application
flatpak document-info — Show information about exported files
flatpak document-list — List exported files
flatpak document-unexport — Stop exporting a file
flatpak permission-remove — List permissions
flatpak permission-list — List permissions
flatpak permission-show — List permissions
flatpak permission-reset — Reset permissions
flatpak enter — Enter an application
flatpak info — Show information about an installed application or runtime
flatpak install — Install an application or runtime
flatpak list — List installed applications and/or runtimes
flatpak make-current — Make a specific version of an app current
flatpak override — Override application requirements
flatpak remote-add — Add a remote repository
flatpak remote-delete — Delete a remote repository
flatpak remote-info — Show information about an application or runtime in a remote
flatpak remote-ls — Show available runtimes and applications
flatpak remote-modify — Modify a remote repository
flatpak remotes — List remote repositories
flatpak repair — Repair a flatpak installation
flatpak repo — Show information about a local repository
flatpak run — Run an application or open a shell in a runtime
flatpak search — Search for applications and runtimes
flatpak uninstall — Uninstall an application or runtime
flatpak update — Update an application or runtime

File Formats

flatpakrepo — Reference to a remote
flatpakref — Reference to a remote for an application or runtime
flatpak installation — Configuration for an installation location
flatpak metadata — Information about an application or runtime
flatpak remote — Configuration for a remote

Executables

Table of Contents

flatpak — Build, install and run applications and runtimes

Name

flatpak — Build, install and run applications and runtimes

Synopsis

flatpak [OPTION...] {COMMAND}

Description

flatpak is a tool for managing applications and the runtimes they use. In the flatpak model, applications can be built and distributed independently from the host system they are used on, and they are isolated from the host system ('sandboxed') to some degree, at runtime.

flatpak can operate in system-wide or per-user mode. The system-wide data (runtimes, applications and configuration) is located in $prefix/var/lib/flatpak/, and the per-user data is in $HOME/.local/share/flatpak/. Below these locations, there is a local repository in the repo/ subdirectory and installed runtimes and applications are in the corresponding runtime/ and app/ subdirectories.

System-wide remotes can be statically preconfigured by dropping config fragments into /etc/flatpak/remotes.d/.

In addition to the system-wide installation in $prefix/var/lib/flatpak/, which is always considered the default one unless overridden, more system-wide installations can be defined via configuration files in /etc/flatpak/installations.d/, which must define at least the id of the installation and the absolute path to it. Other optional parameters like DisplayName , Priority or StorageType are also supported.

flatpak uses OSTree to distribute and deploy data. The repositories it uses are OSTree repositories and can be manipulated with the ostree utility. Installed runtimes and applications are OSTree checkouts.

Options

The following options are understood:

-h, --help: Show help options and exit.
-v, --verbose: Print debug information during command processing. Use -vv for more detail.
--ostree-verbose: Print OSTree debug information during command processing.
--version: Print version information and exit.
--default-arch: Print the default arch and exit.
--supported-arches: Print the supported arches in priority order and exit.
--gl-drivers: Print the list of active gl drivers and exit.

Commands

Commands for managing installed applications and runtimes:

flatpak-install(1): Install an application or a runtime from a remote or bundle.
flatpak-update(1): Update an installed application or runtime.
flatpak-uninstall(1): Uninstall an installed application or runtime.
flatpak-list(1): List installed applications and/or runtimes.
flatpak-info(1): Show information for an installed application or runtime.
flatpak-config(1): Manage flatpak configuration.
flatpak-repair(1): Repair flatpak installation.
flatpak-create-usb(1): Copy apps and/or runtimes onto removable media.

Commands for finding applications and runtimes:

flatpak-search(1): Search for applications and runtimes.

Commands for running applications:

flatpak-run(1): Run an application.
flatpak-override(1): Override permissions for an application.
flatpak-make-current(1): Specify the default version to run.
flatpak-enter(1): Enter the namespace of a running application.

Commands for managing file access:

flatpak-document-export(1): Grant an application access to a specific file.
flatpak-document-unexport(1): Revoke access to a specific file.
flatpak-document-info(1): Show information about a specific file.
flatpak-document-list(1): List exported files.

Commands for managing the dynamic permission store:

flatpak-permission-remove(1): Remove item from permission store.
flatpak-permission-list(1): List permissions.
flatpak-permission-show(1): Show app permissions.
flatpak-permission-reset(1): Reset app permissions.

Commands for managing remote repositories:

flatpak-remotes(1): List all configured remote repositories.
flatpak-remote-add(1): Add a new remote repository.
flatpak-remote-modify(1): Modify properties of a configured remote repository.
flatpak-remote-delete(1): Delete a configured remote repository.
flatpak-remote-ls(1): List contents of a configured remote repository.
flatpak-remote-info(1): Show information about a ref in a configured remote repository.

Commands for building applications:

flatpak-build-init(1): Initialize a build directory.
flatpak-build(1): Run a build command in a build directory.
flatpak-build-finish(1): Finalizes a build directory for export.
flatpak-build-export(1): Export a build directory to a repository.
flatpak-build-bundle(1): Create a bundle file from a ref in a local repository.
flatpak-build-import-bundle(1): Import a file bundle into a local repository.
flatpak-build-sign(1): Sign an application or runtime after its been exported.
flatpak-build-update-repo(1): Update the summary file in a repository.
flatpak-build-commit-from(1): Create a new commit based on an existing ref.
flatpak-repo(1): Print information about a repo.

Environment

Besides standard environment variables such as XDG_DATA_DIRS and XDG_DATA_HOME, flatpak is consulting some of its own.

FLATPAK_USER_DIR: The location of the per-user installation. If this is not set, $XDG_DATA_HOME/flatpak is used.
FLATPAK_SYSTEM_DIR: The location of the default system-wide installation. If this is not set, /var/lib/flatpak is used (unless overridden at build time by --localstatedir or --with-system-install-dir).
FLATPAK_CONFIG_DIR: The location of flatpak site configuration. If this is not set, /etc/flatpak is used (unless overridden at build time by --sysconfdir).

Commands

Table of Contents

flatpak build-bundle — Create a single-file bundle from a local repository
flatpak build-commit-from — Create new commits based on existing one (possibly from another repository)
flatpak build-export — Create a repository from a build directory
flatpak build-finish — Finalize a build directory
flatpak build-import-bundle — Import a file bundle into a local repository
flatpak build-init — Initialize a build directory
flatpak build-sign — Sign an application or runtime
flatpak build-update-repo — Create a repository from a build directory
flatpak build — Build in a directory
flatpak config — Manage configuration
flatpak create-usb — Copy apps and/or runtimes onto removable media.
flatpak document-export — Export a file to a sandboxed application
flatpak document-info — Show information about exported files
flatpak document-list — List exported files
flatpak document-unexport — Stop exporting a file
flatpak permission-remove — List permissions
flatpak permission-list — List permissions
flatpak permission-show — List permissions
flatpak permission-reset — Reset permissions
flatpak enter — Enter an application
flatpak info — Show information about an installed application or runtime
flatpak install — Install an application or runtime
flatpak list — List installed applications and/or runtimes
flatpak make-current — Make a specific version of an app current
flatpak override — Override application requirements
flatpak remote-add — Add a remote repository
flatpak remote-delete — Delete a remote repository
flatpak remote-info — Show information about an application or runtime in a remote
flatpak remote-ls — Show available runtimes and applications
flatpak remote-modify — Modify a remote repository
flatpak remotes — List remote repositories
flatpak repair — Repair a flatpak installation
flatpak repo — Show information about a local repository
flatpak run — Run an application or open a shell in a runtime
flatpak search — Search for applications and runtimes
flatpak uninstall — Uninstall an application or runtime
flatpak update — Update an application or runtime

Name

flatpak-build-bundle — Create a single-file bundle from a local repository

Synopsis

flatpak build-bundle [OPTION...] LOCATION FILENAME NAME [BRANCH]

Description

Creates a single-file named FILENAME for the application (or runtime) named NAME in the repository at LOCATION . If a BRANCH is specified, this branch of the application is used.

The collection ID set on the repository at LOCATION (if set) will be used for the bundle.

The format of the bundle file is that of an ostree static delta (against an empty base) with some flatpak specific metadata for the application icons and appdata.

Options

The following options are understood:

-h, --help: Show help options and exit.
--runtime: Export a runtime instead of an application.
--arch=ARCH: The arch to create a bundle for.
--repo-url=URL: The URL for the repository from which the application can be updated. Installing the bundle will automatically configure a remote for this URL.
--runtime-repo=URL: The URL for a .flatpakrepo file that contains the information about the repository that supplies the runtimes required by the app.
--gpg-keys=FILE: Add the GPG key from FILE (use - for stdin).
--gpg-homedir=PATH: GPG Homedir to use when looking for keyrings.
--oci: Export to an OCI image instead of a Flatpak bundle.
-v, --verbose: Print debug information during command processing.
--ostree-verbose: Print OSTree debug information during command processing.

Name

flatpak-build-commit-from — Create new commits based on existing one (possibly from another repository)

Synopsis

flatpak build-commit-from [OPTION...] DST-REPO DST-REF...

Description

Creates new commits on the DST-REF branch in the DST-REPO , with the contents (and most of the metadata) taken from another branch, either from another repo, or from another branch in the same repository.

The collection ID set on DST-REPO (if set) will be used for the newly created commits.

This command is very useful when you want to maintain a branch with a clean history that has no unsigned or broken commits. For instance, you can import the head from a different repository from an automatic builder when you've verified that it worked. The new commit will have no parents or signatures from the autobuilder, and can be properly signed with the official key.

Any deltas that affect the original commit and that match parent commits in the destination repository are copied and rewritten for the new commit id.

Options

The following options are understood:

-h, --help: Show help options and exit.
--src-repo=SRC-REPO: The (local) repository to pull the source branch from. Defaults to the destination repository.
--src-ref=SRC-REF: The branch to use as the source for the new commit. Defaults to the same as the destination ref, which is useful only if a different source repo has been specified.
--untrusted: The source repostory is not trusted, all objects are copied (not hardlinked) and all checksums are verified.
-s, --subject=SUBJECT: One line subject for the commit message. If not specified, will be taken from the source commit.
-b, --body=BODY: Full description for the commit message. If not specified, will be taken from the source commit.
--update-appstream: Update the appstream branch after the build.
--no-update-summary: Don't update the summary file after the new commit is added. This means the repository will not be useful for serving over http until build-update-repo has been run. This is useful is you want to do multiple repo operations before finally updating the summary.
--force: Create new commit even if the content didn't change from the existing branch head.
--gpg-sign=KEYID: Sign the commit with this GPG key. This option can be used multiple times.
--gpg-homedir=PATH: GPG Homedir to use when looking for keyrings
-v, --verbose: Print debug information during command processing.
--ostree-verbose: Print OSTree debug information during command processing.

Examples

To revert a commit to the commit before:

$ flatpak build-commit-from --timestamp=NOW --src-ref=app/org.gnome.gedit/x86_64/master^ repo app/org.gnome.gedit/x86_64/master

Name

flatpak-build-export — Create a repository from a build directory

Synopsis

flatpak build-export [OPTION...] LOCATION DIRECTORY [BRANCH]

Description

Creates or updates a repository with an application build. LOCATION is the location of the repository. DIRECTORY must be a finalized build directory. If BRANCH is not specified, it is assumed to be "master".

If LOCATION exists, it is assumed to be an OSTree repository, otherwise a new OSTree repository is created at this location. The repository can be inspected with the ostree tool.

The contents of DIRECTORY are committed on the branch with name app/APPNAME/ARCH/BRANCH, where ARCH is the architecture of the runtime that the application is using. A commit filter is used to enforce that only the contents of the files/ and export/ subdirectories and the metadata file are included in the commit, anything else is ignored.

When exporting a flatpak to be published to the internet, --collection-id=COLLECTION-ID should be specified as a globally unique reverse DNS value to identify the collection of flatpaks this will be added to. Setting a globally unique collection ID allows the apps in the repository to be shared over peer to peer systems without needing further configuration.

The build-update-repo command should be used to update repository metadata whenever application builds are added to a repository.

Options

The following options are understood:

-h, --help: Show help options and exit.
-s, --subject=SUBJECT: One line subject for the commit message.
-b, --body=BODY: Full description for the commit message.
--collection-id=COLLECTION-ID: Set as the collection ID of the repository. 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 exporting to an existing repository, the collection ID must match the existing configured collection ID for that repository.
--arch=ARCH: Specify the architecture component of the branch to export. Only host compatible architectures can be specified.
--exclude=PATTERN: Exclude files matching PATTERN from the commit. This option can be used multiple times.
--include=PATTERN: Don't exclude files matching PATTERN from the commit, even if they match the --export patterns. This option can be used multiple times.
--metadata=FILENAME: Use the specified filename as metadata in the exported app instead of the default file (called metadata). This is useful if you want to commit multiple things from a single build tree, typically used in combination with --files and --exclude.
--files=SUBDIR: Use the files in the specified subdirectory as the file contents, rather than the regular files directory.
--timestamp=DATE: Use the specified ISO 8601 formatted date in the commit metadata and, if --update-appstream is used, the appstream data.
--update-appstream: Update the appstream branch after the build.
--no-update-summary: Don't update the summary file after the new commit is added. This means the repository will not be useful for serving over http until build-update-repo has been run. This is useful is you want to do multiple repo operations before finally updating the summary.
--gpg-sign=KEYID: Sign the commit with this GPG key. This option can be used multiple times.
--gpg-homedir=PATH: GPG Homedir to use when looking for keyrings
-r, --runtime: Export a runtime instead for an app (this uses the usr subdir as files).
-v, --verbose: Print debug information during command processing.
--ostree-verbose: Print OSTree debug information during command processing.

Examples

$ flatpak build-export ~/repos/gnome-calculator/ ~/build/gnome-calculator/ org.gnome.Calculator

Commit: 9d0044ea480297114d03aec85c3d7ae3779438f9d2cb69d717fb54237acacb8c
Metadata Total: 605
Metadata Written: 5
Content Total: 1174
Content Written: 1
Content Bytes Written: 305

Name

flatpak-build-finish — Finalize a build directory

Synopsis

flatpak build-finish [OPTION...] DIRECTORY

Description

Finalizes a build directory, to prepare it for exporting. DIRECTORY is the name of the directory.

The result of this command is that desktop files, icons and D-Bus service files from the files subdirectory are copied to a new export subdirectory. In the metadata file, the command key is set in the [Application] group, and the supported keys in the [Environment] group are set according to the options.

You should review the exported files and the application metadata before creating and distributing an application bundle.

It is an error to run build-finish on a directory that has not been initialized as a build directory, or has already been finalized.

Options

The following options are understood:

-h, --help

Show help options and exit.

--command=COMMAND

The command to use. If this option is not specified, the first executable found in files/bin is used.

--require-version=MAJOR.MINOR.MICRO

Require this version of later of flatpak to install/update to this build.

--share=SUBSYSTEM

Share a subsystem with the host session. This updates the [Context] group in the metadata. SUBSYSTEM must be one of: network, ipc. This option can be used multiple times.

--unshare=SUBSYSTEM

Don't share a subsystem with the host session. This updates the [Context] group in the metadata. SUBSYSTEM must be one of: network, ipc. This option can be used multiple times.

--socket=SOCKET

Expose a well known socket to the application. This updates the [Context] group in the metadata. SOCKET must be one of: x11, wayland, fallback-x11, pulseaudio, system-bus, session-bus, ssh-auth. This option can be used multiple times.

--nosocket=SOCKET

Don't expose a well known socket to the application. This updates the [Context] group in the metadata. SOCKET must be one of: x11, wayland, fallback-x11, pulseaudio, system-bus, session-bus, ssh-auth. This option can be used multiple times.

--device=DEVICE

Expose a device to the application. This updates the [Context] group in the metadata. DEVICE must be one of: dri, kvm, all. This option can be used multiple times.

--nodevice=DEVICE

Don't expose a device to the application. This updates the [Context] group in the metadata. DEVICE must be one of: dri, kvm, all. This option can be used multiple times.

--allow=FEATURE

Allow access to a specific feature. This updates the [Context] group in the metadata. FEATURE must be one of: devel, multiarch, bluetooth. This option can be used multiple times.

The devel feature allows the application to access certain syscalls such as ptrace(), and perf_event_open().

The multiarch feature allows the application to execute programs compiled for an ABI other than the one supported natively by the system. For example, for the x86_64 architecture, 32-bit x86 binaries will be allowed as well.

The bluetooth feature allows the application to use bluetooth (AF_BLUETOOTH) sockets. Note, for bluetooth to fully work you must also have network access.

--disallow=FEATURE

Disallow access to a specific feature. This updates the [Context] group in the metadata. FEATURE must be one of: devel, multiarch, bluetooth. This option can be used multiple times.

--filesystem=FS

Allow the application access to a subset of the filesystem. This updates the [Context] group in the metadata. FS can be one of: home, host, xdg-desktop, xdg-documents, xdg-download xdg-music, xdg-pictures, xdg-public-share, xdg-templates, xdg-videos, xdg-run, xdg-config, xdg-cache, xdg-data, an absolute path, or a homedir-relative path like ~/dir or paths relative to the xdg dirs, like xdg-download/subdir. The optional :ro suffix indicates that the location will be read-only. The optional :create suffix indicates that the location will be read-write and created if it doesn't exist. This option can be used multiple times.

--nofilesystem=FILESYSTEM

Remove access to the specified subset of the filesystem from the application. This overrides to the Context section from the application metadata. FILESYSTEM can be one of: home, host, xdg-desktop, xdg-documents, xdg-download xdg-music, xdg-pictures, xdg-public-share, xdg-templates, xdg-videos, an absolute path, or a homedir-relative path like ~/dir. This option can be used multiple times.

--add-policy=SUBSYSTEM.KEY=VALUE

Add generic policy option. For example, "--add-policy=subsystem.key=v1 --add-policy=subsystem.key=v2" would map to this metadata:

[Policy subsystem]
key=v1;v2;

This option can be used multiple times.

--remove-policy=SUBSYSTEM.KEY=VALUE

Remove generic policy option. This option can be used multiple times.

--env=VAR=VALUE

Set an environment variable in the application. This updates the [Environment] group in the metadata. This overrides to the Context section from the application metadata. This option can be used multiple times.

--own-name=NAME

Allow the application to own the well known name NAME on the session bus. If NAME ends with .*, it allows the application to own all matching names. This updates the [Session Bus Policy] group in the metadata. This option can be used multiple times.

--talk-name=NAME

Allow the application to talk to the well known name NAME on the session bus. If NAME ends with .*, it allows the application to talk to all matching names. This updates the [Session Bus Policy] group in the metadata. This option can be used multiple times.

--system-own-name=NAME

Allow the application to own the well known name NAME on the system bus. If NAME ends with .*, it allows the application to own all matching names. This updates the [System Bus Policy] group in the metadata. This option can be used multiple times.

--system-talk-name=NAME

Allow the application to talk to the well known name NAME on the system bus. If NAME ends with .*, it allows the application to talk to all matching names. This updates the [System Bus Policy] group in the metadata. This option can be used multiple times.

--persist=FILENAME

If the application doesn't have access to the real homedir, make the (homedir-relative) path FILENAME a bind mount to the corresponding path in the per-application directory, allowing that location to be used for persistent data. This updates the [Context] group in the metadata. This option can be used multiple times.

--runtime=RUNTIME, --sdk=SDK

Change the runtime or sdk used by the app to the specified partial ref. Unspecified parts of the ref are taken from the old values or defaults.

--metadata=GROUP=KEY[=VALUE]

Set a generic key in the metadata file. If value is left out it will be set to "true".

--extension=NAME=VARIABLE[=VALUE]

Add extension point info.

--remove-extension=NAME

Remove extension point info.

--extension-priority=VALUE

Set the priority (library override order) of the extension point. Only useful for extensions. 0 is the default, and higher value means higher priority.

--extra-data=NAME:SHA256:DOWNLOAD-SIZE:INSTALL-SIZE:URL

Adds information about extra data uris to the app. These will be downloaded and verified by the client when the app is installed and placed in the /app/extra directory. You can also supply an /app/bin/apply_extra script that will be run after the files are downloaded.

--no-exports

Don't look for exports in the build.

-v, --verbose

Print debug information during command processing.

--ostree-verbose

Print OSTree debug information during command processing.

Examples

$ flatpak build-finish /build/my-app --socket=x11 --share=ipc

Exporting share/applications/gnome-calculator.desktop
Exporting share/dbus-1/services/org.gnome.Calculator.SearchProvider.service
More than one executable
Using gcalccmd as command
Please review the exported files and the metadata

Name

flatpak-build-import-bundle — Import a file bundle into a local repository

Synopsis

flatpak build-import-bundle [OPTION...] LOCATION FILENAME

Description

Imports a bundle from a file named FILENAME into the repository at LOCATION .

The format of the bundle file is that generated by build-bundle.

Options

The following options are understood:

-h, --help: Show help options and exit.
-v, --verbose: Print debug information during command processing.
--ostree-verbose: Print OSTree debug information during command processing.
--ref=REF: Override the ref specified in the bundle.
--oci: Import an OCI image instead of a Flatpak bundle.
--update-appstream: Update the appstream branch after the build.
--no-update-summary: Don't update the summary file after the new commit is added. This means the repository will not be useful for serving over http until build-update-repo has been run. This is useful is you want to do multiple repo operations before finally updating the summary.
--gpg-sign=KEYID: Sign the commit with this GPG key. This option can be used multiple times.
--gpg-homedir=PATH: GPG Homedir to use when looking for keyrings

Name

flatpak-build-init — Initialize a build directory

Synopsis

flatpak build-init [OPTION...] DIRECTORY APPNAME SDK RUNTIME [BRANCH]

Description

Initializes a directory for building an application. DIRECTORY is the name of the directory. APPNAME is the application id of the app that will be built. SDK and RUNTIME specify the sdk and runtime that the application should be built against and run in.

The result of this command is that a metadata file is created inside the given directory. Additionally, empty files and var subdirectories are created.

It is an error to run build-init on a directory that has already been initialized as a build directory.

Options

The following options are understood:

-h, --help: Show help options and exit.
--arch=ARCH: The architecture to use.
-v, --var=RUNTIME: Initialize var from the named runtime.
-w, --writable-sdk: Initialize /usr with a copy of the sdk, which is writable during flatpak build. This can be used if you need to install build tools in /usr during the build. This is stored in the usr subdirectory of the app dir, but will not be part of the final app.
--tag=TAG: Add a tag to the metadata file. This option can be used multiple times.
--sdk-extension=EXTENSION: When using --writable-sdk, in addition to the sdk, also install the specified extension. This option can be used multiple times.
--extension=NAME=VARIABLE[=VALUE]: Add extension point info.
--sdk-dir: Specify a custom subdirectory to use instead of usr for --writable-sdk.
--update: Re-initialize the sdk and var, don't fail if already initialized.
--base=APP: Initialize the application with files from another specified application.
--base-version=VERSION: Specify the version to use for --base. If not specified, will default to "master".
--base-extension=EXTENSION: When using --base, also install the specified extension from the app. This option can be used multiple times.
--type=TYPE: This can be used to build different types of things. The default is "app" which is a regular app, but "runtime" creates a runtime based on an existing runtime, and "extension" creates an extension for an app or runtime.
--extension-tag=EXTENSION_TAG: If building an extension, the tag to use when searching for the mount point of the extension.
--verbose: Print debug information during command processing.
--ostree-verbose: Print OSTree debug information during command processing.

Examples

$ flatpak build-init /build/my-app org.gnome.Sdk org.gnome.Platform 3.16

Name

flatpak-build-sign — Sign an application or runtime

Synopsis

flatpak build-sign [OPTION...] LOCATION ID [BRANCH]

Description

Signs the commit for a specified application or runtime in a local repository. LOCATION is the location of the repository. ID is the name of the application, or runtime if --runtime is specified. If BRANCH is not specified, it is assumed to be "master".

Applications can also be signed during build-export, but it is sometimes useful to add additional signatures later.

Options

The following options are understood:

-h, --help: Show help options and exit.
--gpg-sign=KEYID: Sign the commit with this GPG key. This option can be used multiple times.
--gpg-homedir=PATH: GPG Homedir to use when looking for keyrings
--runtime: Sign a runtime instead of an app.
--arch=ARCH: The architecture to use.
-v, --verbose: Print debug information during command processing.
--ostree-verbose: Print OSTree debug information during command processing.

Examples

$ flatpak build-sign --gpg-sign=D8BA6573DDD2418027736F1BC33B315E53C1E9D6 /some/repo org.my.App

Name

flatpak-build-update-repo — Create a repository from a build directory

Synopsis

flatpak build-update-repo [OPTION...] LOCATION

Description

Updates repository metadata for the repository at LOCATION . This command generates an OSTree summary file that lists the contents of the repository. The summary is used by flatpak remote-ls and other commands to display the contents of remote repositories.

After this command, LOCATION can be used as the repository location for flatpak remote-add, either by exporting it over http, or directly with a file: url.

Options

The following options are understood:

-h, --help: Show help options and exit.
--redirect-url=URL: Redirect this repo to a new URL.
--title=TITLE: A title for the repository, e.g. for display in a UI. The title is stored in the repository summary.
--default-branch=BRANCH: A default branch for the repository, mainly for use in a UI.
--gpg-import=FILE: Import a new default GPG public key from the given file.
--collection-id=COLLECTION-ID: The globally unique identifier of the remote repository, to allow mirrors to be grouped. This must be set to a globally unique reverse DNS string if the repository is to be made publicly available. If a collection ID is already set on an existing repository, this will update it. If not specified, the existing collection ID will be left unchanged.
--deploy-collection-id: Deploy the collection ID (set using --collection-id in the static remote configuration for all clients. This is irrevocable once published in a repository. Use it to decide when to roll out a collection ID to users of an existing repository. If constructing a new repository which has a collection ID, you should typically always pass this option.
--gpg-sign=KEYID: Sign the commit with this GPG key. This option can be used multiple times.
--gpg-homedir=PATH: GPG Homedir to use when looking for keyrings
--generate-static-deltas: Generate static deltas for all references. This generates from-empty and delta static files that allow for faster download.
--prune: Remove unreferenced objects in repo.
--prune-depth: Only keep at most this number of old versions for any particular ref. Default is -1 which means infinite.
-v, --verbose: Print debug information during command processing.
--ostree-verbose: Print OSTree debug information during command processing.

Name

flatpak-build — Build in a directory

Synopsis

flatpak build [OPTION...] DIRECTORY [COMMAND [ARG...]]

Description

Runs a build command in a directory. DIRECTORY must have been initialized with flatpak build-init.

The sdk that is specified in the metadata file in the directory is mounted at /usr and the files and var subdirectories are mounted at /app and /var, respectively. They are writable, and their contents are preserved between build commands, to allow accumulating build artifacts there.

Options

The following options are understood:

-h, --help

Show help options and exit.

-v, --verbose

Print debug information during command processing.

--ostree-verbose

Print OSTree debug information during command processing.

-r, --runtime

Use the non-devel runtime that is specified in the application metadata instead of the devel runtime.

-p, --die-with-parent

Kill the build process and all children when the launching process dies.

--bind-mount=DEST=SOURCE

Add a custom bind mount in the build namespace. Can be specified multiple times.

--build-dir=PATH

Start the build in this directory (default is in the current directory).

--share=SUBSYSTEM

Share a subsystem with the host session. This overrides the Context section from the application metadata. SUBSYSTEM must be one of: network, ipc. This option can be used multiple times.

--unshare=SUBSYSTEM

Don't share a subsystem with the host session. This overrides the Context section from the application metadata. SUBSYSTEM must be one of: network, ipc. This option can be used multiple times.

--socket=SOCKET

Expose a well-known socket to the application. This overrides to the Context section from the application metadata. SOCKET must be one of: x11, wayland, fallback-x11, pulseaudio, system-bus, session-bus, ssh-auth. This option can be used multiple times.

--nosocket=SOCKET

Don't expose a well-known socket to the application. This overrides to the Context section from the application metadata. SOCKET must be one of: x11, wayland, fallback-x11, pulseaudio, system-bus, session-bus, ssh-auth. This option can be used multiple times.

--device=DEVICE

Expose a device to the application. This overrides to the Context section from the application metadata. DEVICE must be one of: dri, kvm, all. This option can be used multiple times.

--nodevice=DEVICE

Don't expose a device to the application. This overrides to the Context section from the application metadata. DEVICE must be one of: dri, kvm, all. This option can be used multiple times.

--allow=FEATURE

Allow access to a specific feature. This updates the [Context] group in the metadata. FEATURE must be one of: devel, multiarch, bluetooth. This option can be used multiple times.

See flatpak-build-finish(1) for the meaning of the various features.

--disallow=FEATURE

Disallow access to a specific feature. This updates the [Context] group in the metadata. FEATURE must be one of: devel, multiarch, bluetooth. This option can be used multiple times.

--filesystem=FILESYSTEM[:ro|:create]

Allow the application access to a subset of the filesystem. This overrides to the Context section from the application metadata. FILESYSTEM can be one of: home, host, xdg-desktop, xdg-documents, xdg-download xdg-music, xdg-pictures, xdg-public-share, xdg-templates, xdg-videos, xdg-run, xdg-config, xdg-cache, xdg-data, an absolute path, or a homedir-relative path like ~/dir or paths relative to the xdg dirs, like xdg-download/subdir. The optional :ro suffix indicates that the location will be read-only. The optional :create suffix indicates that the location will be read-write and created if it doesn't exist. This option can be used multiple times.

--nofilesystem=FILESYSTEM

Remove access to the specified subset of the filesystem from the application. This overrides to the Context section from the application metadata. FILESYSTEM can be one of: home, host, xdg-desktop, xdg-documents, xdg-download xdg-music, xdg-pictures, xdg-public-share, xdg-templates, xdg-videos, an absolute path, or a homedir-relative path like ~/dir. This option can be used multiple times.

--with-appdir

Expose and configure access to the per-app storage directory in $HOME/.var/app. This is not normally useful when building, but helps when testing built apps.

--add-policy=SUBSYSTEM.KEY=VALUE

Add generic policy option. For example, "--add-policy=subsystem.key=v1 --add-policy=subsystem.key=v2" would map to this metadata:

[Policy subsystem]
key=v1;v2;

This option can be used multiple times.

--remove-policy=SUBSYSTEM.KEY=VALUE

Remove generic policy option. This option can be used multiple times.

--env=VAR=VALUE

Set an environment variable in the application. This overrides to the Context section from the application metadata. This option can be used multiple times.

--own-name=NAME

Allow the application to own the well-known name NAME on the session bus. This overrides to the Context section from the application metadata. This option can be used multiple times.

--talk-name=NAME

Allow the application to talk to the well-known name NAME on the session bus. This overrides to the Context section from the application metadata. This option can be used multiple times.

--system-own-name=NAME

Allow the application to own the well-known name NAME on the system bus. This overrides to the Context section from the application metadata. This option can be used multiple times.

--system-talk-name=NAME

Allow the application to talk to the well-known name NAME on the system bus. This overrides to the Context section from the application metadata. This option can be used multiple times.

--persist=FILENAME

If the application doesn't have access to the real homedir, make the (homedir-relative) path FILENAME a bind mount to the corresponding path in the per-application directory, allowing that location to be used for persistent data. This overrides to the Context section from the application metadata. This option can be used multiple times.

--sdk-dir=DIR

Normally if there is a usr directory in the build dir, this is used for the runtime files (this can be created by --writable-sdk or --type=runtime arguments to build-init). If you specify --sdk-dir this directoryname will be used instead. Use this if you passed --sdk-dir to build-init.

--readonly

Mount the normally writable destination directories read-only. This can be useful if you want to run something in the sandbox but guarantee that it doesn't affect the build results. For example tests.

--metadata=FILE

Use the specified filename as metadata in the exported app instead of the default file (called metadata). This is useful if you build multiple things from a single build tree (such as both a platform and a sdk).

--log-session-bus

Log session bus traffic. This can be useful to see what access you need to allow in your D-Bus policy.

--log-system-bus

Log system bus traffic. This can be useful to see what access you need to allow in your D-Bus policy.

Examples

$ flatpak build /build/my-app rpmbuild my-app.src.rpm

Name

flatpak-config — Manage configuration

Synopsis

flatpak config [OPTION...] KEY VALUE

Description

Show and modify current configuration

Options

The following options are understood:

-h, --help: Show help options and exit.
--list: Print all keys and their values
--set: Set key KEY to VALUE
--unset: Unset key KEY
--get: Print value of KEY.
--user: Configure per-user installation.
--system: Configure system-wide installation.
--installation=NAME: Configure the system-wide installation specified by NAME among those defined in /etc/flatpak/installations.d/. Using --installation=default is equivalent to using --system .
-v, --verbose: Print debug information during command processing.
--ostree-verbose: Print OSTree debug information during command processing.

Examples

$ flatpak config --set language sv;en;fi

Name

flatpak-create-usb — Copy apps and/or runtimes onto removable media.

Synopsis

flatpak create-usb [OPTION...] MOUNT-PATH REF...

Description

Copies the specified apps and/or runtimes REF s onto the removable media mounted at MOUNT-PATH , along with all the dependencies and metadata needed for installing them. This is one way of transferring flatpaks between computers that doesn't require an Internet connection. After using this comand, the USB drive can be connected to another computer and flatpak install will prefer to install from it rather than the Internet if the refs are the newest available. For this process to work a collection ID must be configured on the relevant remotes on both the source and destination computers, and on the remote server.

Each REF argument is a full or partial indentifier in the flatpak ref format, which looks like "(app|runtime)/ID/ARCH/BRANCH". All elements except ID are optional and can be left out, including the slashes, so most of the time you need only specify ID. Any part left out will be matched against what is installed, and if there are multiple matches an error message will list the alternatives.

By default this looks for both installed apps and runtimes with the given REF , but you can limit this by using the --app or --runtime option.

All REF s must be in the same installation (user, system, or other). Otherwise it's ambiguous which repository metadata refs to put on the USB drive.

This command relies on the summary file in the source repo, so you may want to run ostree summary -u before running this command. Since appstream data is copied to the USB when it's available, you might also want to run flatpak update --appstream before updating the summary file.

By default flatpak create-usb uses .ostree/repo as the destination directory under MOUNT-PATH but if you specify another location using --destination-repo a symbolic link will be created for you in .ostree/repos.d. This ensures that either way the repository will be found by flatpak (and other consumers of libostree) for install/update operations.

Unless overridden with the --system, --user, or --installation options, this command searches both the system-wide installation and the per-user one for REF and errors out if it exists in more than one.

Options

The following options are understood:

-h, --help: Show help options and exit.
--user: Uninstalls from a per-user installation.
--system: Uninstalls from the default system-wide installation.
--installation=NAME: Copies refs from a system-wide installation specified by NAME among those defined in /etc/flatpak/installations.d/. Using --installation=default is equivalent to using --system .
--app: Assume that all REF s are apps if not explicitly specified.
--runtime: Assume that all REF s are runtimes if not explicitly specified.
--destination-repo=DEST: Create the repository in DEST under MOUNT-PATH, rather than the default location.
-v, --verbose: Print debug information during command processing.
--ostree-verbose: Print OSTree debug information during command processing.

Examples

$ flatpak create-usb /run/media/mwleeds/1a9b4cb2-a7ef-4d9b-91a5-6eaf8fdd2bf6/ com.endlessm.wiki_art.en

Name

flatpak-document-export — Export a file to a sandboxed application

Synopsis

flatpak document-export [OPTION...] FILE

Description

Creates a document id for a local file that can be exposed to sandboxed applications, allowing them access to files that they would not otherwise see. The exported files are exposed in a fuse filesystem at /run/user/$UID/doc/.

This command also lets you modify the per-application permissions of the documents, granting or revoking access to the file on a per-application basis.

Options

The following options are understood:

-h, --help: Show help options and exit.
-u, --unique: Don't reuse an existing document id for the file. This makes it safe to later remove the document when you're finished with it.
-t, --transient: The document will only exist for the length of the session. This is useful for temporary grants.
-n, --noexist: Don't require the file to exist already.
-a, --app=APPID: Grant read access to the specified application. The --allow and --forbid options can be used to grant or remove additional privileges. This option can be used multiple times.
-r, --allow-read: Grant read access to the applications specified with --app. This defaults to TRUE.
--forbid-read: Revoke read access for the applications specified with --app.
-w, --allow-write: Grant write access to the applications specified with --app.
--forbid-write: Revoke write access for the applications specified with --app.
-d, --allow-delete: Grant the ability to remove the document from the document portal to the applications specified with --app.
--forbid-delete: Revoke the ability to remove the document from the document portal from the applications specified with --app.
-g, --allow-grant-permission: Grant the ability to grant further permissions to the applications specified with --app.
--forbid-grant-permission: Revoke the ability to grant further permissions for the applications specified with --app.
-v, --verbose: Print debug information during command processing.
--ostree-verbose: Print OSTree debug information during command processing.

Examples

$ flatpak document-export --app=org.gnome.GEdit ~/test.txt

/run/user/1000/doc/e52f9c6a/test.txt

Name

flatpak-document-info — Show information about exported files

Synopsis

flatpak document-info [OPTION...] FILE

Description

Shows information about an exported file, such as the document id, the fuse path, the original location in the filesystem, and the per-application permissions.

FILE can either be a file in the fuse filesystem at /run/user/$UID/doc/, or a file anywhere else.

Options

The following options are understood:

-h, --help: Show help options and exit.
-v, --verbose: Print debug information during command processing.
--ostree-verbose: Print OSTree debug information during command processing.

Examples

$ flatpak document-info ~/Sources/gtk/gail-3.0.pc

id: dd32c34a
path: /run/user/1000/doc/dd32c34a/gail-3.0.pc
origin: /home/mclasen/Sources/gtk/gail-3.0.pc
permissions:
        org.gnome.gedit read, write

Name

flatpak-document-list — List exported files

Synopsis

flatpak document-list [OPTION...] [APPID]

Description

Lists exported files, with their document id and the full path to their origin. If an APPID is specified, only the files exported to this app are listed.

Options

The following options are understood:

-h, --help: Show help options and exit.
-v, --verbose: Print debug information during command processing.
--ostree-verbose: Print OSTree debug information during command processing.

Name

flatpak-document-unexport — Stop exporting a file

Synopsis

flatpak document-unexport [OPTION...] FILE

Description

Removes the document id for the file from the document portal. This will make the document unavailable to all sandboxed applications.

Options

The following options are understood:

-h, --help: Show help options and exit.
-v, --verbose: Print debug information during command processing.
--ostree-verbose: Print OSTree debug information during command processing.

Name

flatpak-permission-remove — List permissions

Synopsis

flatpak permission-remove [OPTION...] TABLE ID

Description

Removes an entry for the object with id ID to the permission store table TABLE. The ID must be in a suitable format for the table.

The permission store is used by portals. Each portal generally has its own table in the permission store, and the format of the table entries is specific to each portal.

Options

The following options are understood:

-h, --help: Show help options and exit.
-v, --verbose: Print debug information during command processing.
--ostree-verbose: Print OSTree debug information during command processing.

Name

flatpak-permission-list — List permissions

Synopsis

flatpak permission-list [OPTION...] [TABLE] [ID]

Description

Lists dynamic permissions which are stored in the Flatpak permission store.

When called without arguments, lists all the entries in all permission store tables. When called with one argument, lists all the entries in the named table. When called with two arguments, lists the entry in the named table for the given object ID.

The permission store is used by portals. Each portal generally has its own table in the permission store, and the format of the table entries is specific to each portal.

Options

The following options are understood:

-h, --help: Show help options and exit.
-v, --verbose: Print debug information during command processing.
--ostree-verbose: Print OSTree debug information during command processing.

Name

flatpak-permission-show — List permissions

Synopsis

flatpak permission-show [OPTION...] APP_ID

Description

Lists dynamic permissions for the given app which are stored in the Flatpak permission store.

When called without arguments, lists all the entries in all permission store tables. When called with one argument, lists all the entries in the named table. When called with two arguments, lists the entry in the named table for the given object ID.

The permission store is used by portals. Each portal generally has its own table in the permission store, and the format of the table entries is specific to each portal.

Options

The following options are understood:

-h, --help: Show help options and exit.
-v, --verbose: Print debug information during command processing.
--ostree-verbose: Print OSTree debug information during command processing.

Name

flatpak-permission-reset — Reset permissions

Synopsis

flatpak permission-reset [OPTION...] APP_ID

Description

Removes all permissions for the given app from the Flatpak permission store.

The permission store is used by portals. Each portal generally has its own table in the permission store, and the format of the table entries is specific to each portal.

Options

The following options are understood:

-h, --help: Show help options and exit.
-v, --verbose: Print debug information during command processing.
--ostree-verbose: Print OSTree debug information during command processing.

Name

flatpak-enter — Enter an application

Synopsis

flatpak enter [OPTION...] MONITORPID COMMAND [ARG...]

Description

Enter a running sandbox. SANDBOXEDPID must be the pid of a process running in a flatpak sandbox. COMMAND is the command to run in the sandbox. Extra arguments are passed on to the command.

This creates a new process within the running sandbox, with the same environment. This is useful when you want to debug a problem with a running application.

This command requires extra privileges, so must be run as root or via e.g. sudo.

Options

The following options are understood:

-h, --help: Show help options and exit.
-v, --verbose: Print debug information during command processing.
--ostree-verbose: Print OSTree debug information during command processing.

Examples

$ flatpak enter 15345 sh

Name

flatpak-info — Show information about an installed application or runtime

Synopsis

flatpak info [OPTION...] NAME [BRANCH]

Description

Show info about an installed application or runtime.

By default, the output is formatted in a friendly format. If you specify one of the options --show-ref, --show-origin, --show-commit, --show-size, --show-metadata, --show-permissions, --file-access, --show-location, --show-runtime or --show-sdk, the output is instead formatted in a machine-readable format.

By default, both per-user and system-wide installations are queried. Use the --user, --system or --installation options to change this.

Options

The following options are understood:

-h, --help: Show help options and exit.
--user: Query per-user installations.
--system: Query the default system-wide installation.
--installation=NAME: Query a system-wide installation by NAME among those defined in /etc/flatpak/installations.d/. Using --installation=default is equivalent to using --system .
--arch=ARCH: Query for this architecture.
-r, --show-ref: Show the installed ref.
-o, --show-origin: Show the remote the ref is installed from.
-c, --show-commit: Show the installed commit id.
-s, --show-size: Show the installed size.
-m, --show-metadata: Show the metadata.
--show-runtime: Show the runtime.
--show-sdk: Show the SDK.
-M, --show-permissions: Show the permissions.
--file-access=PATH: Show the level of access to the given path.
-e, --show-extensions: Show the matching extensions.
-v, --verbose: Print debug information during command processing.
--ostree-verbose: Print OSTree debug information during command processing.

Examples

$ flatpak info org.gnome.Builder//master

Name

flatpak-install — Install an application or runtime

Synopsis

Install from a configured remote:

flatpak install [OPTION...] REMOTE-NAME REF...

Install from a .flatpakref file:

flatpak install [OPTION...] [--from] LOCATION

Install from a .flatpak bundle:

flatpak install [OPTION...] [--bundle] FILENAME

Description

Installs an application or runtime. The primary way to install is to specify a [REMOTE] name as the source and one ore more [REF]s to specify the application or runtime to install.

Each REF argument is a full or partial indentifier in the flatpak ref format, which looks like "(app|runtime)/ID/ARCH/BRANCH". All elements except ID are optional and can be left out, including the slashes, so most of the time you need only specify ID. Any part left out will be matched against what is in the remote, and if there are multiple matches an error message will list the alternatives.

By default this looks for both apps and runtimes with the given REF in the specified REMOTE , but you can limit this by using the --app or --runtime option, or by supplying the initial element in the REF.

If REMOTE is a uri or a path (absolute or relative starting with ./) to a local repository, then that repository will be used as the source, and a temporary remote will be created for the lifetime of the REF .

If the specified REMOTE has a collection ID configured on it, flatpak will search mounted filesystems such as USB drives as well as Avahi services advertised on the local network for the needed refs, in order to support offline updates. See ostree-find-remotes(1) for more information.

The alternative form of the command ([--from] or [--bundle] allows you to install directly from a source such as a .flatpak single-file bundle, a .flatpakref app description. The options are optional if the first argument has the right extension.

Note that flatpak allows one to have multiple branches of an application and runtimes installed and used at the same time. However, only one version of an application can be current, meaning its exported files (for instance desktop files and icons) are visible to the host. The last installed version is made current by default, but you can manually change with make-current.

Unless overridden with the --user or the --installation option, this command installs the application or runtime in the default system-wide installation.

Options

The following options are understood:

-h, --help: Show help options and exit.
--bundle: Assume LOCATION is a .flatpak single-bundle file. This is optional if the arguments ends with .flatpak.
--from: Assume LOCATION is a .flatpakref file containing the details of the app to be installed. This is optional if the arguments ends with .flatpakref.
--reinstall: Uninstall first if already installed.
--user: Install the application or runtime in a per-user installation.
--system: Install the application or runtime in the default system-wide installation.
--installation=NAME: Install the application or runtime in a system-wide installation specified by NAME among those defined in /etc/flatpak/installations.d/. Using --installation=default is equivalent to using --system .
--arch=ARCH: The default architecture to install for, if not given explicitly in the REF .
--subpath=PATH: Install only a subpath of the ref. This is mainly used to install a subset of locales. This can be added multiple times to install multiple subpaths.,
--gpg-file=FILE: Check bundle signatures with GPG key from FILE (- for stdin).
--no-deploy: Download the latest version, but don't deploy it.
--no-pull: Don't download the latest version, deploy whatever is locally available.
--no-related: Don't download related extensions, such as the locale data.
--no-deps: Don't verify runtime dependencies when installing.
--app: Assume that all REF s are apps if not explicitly specified.
--runtime: Assume that all REF s are runtimes if not explicitly specified.
-y, --assumeyes: Automatically answer yes to all questions (or pick the most prioritized answer). This is useful for automation.
-v, --verbose: Print debug information during command processing.
--ostree-verbose: Print OSTree debug information during command processing.

Examples

$ flatpak install gnome org.gnome.gedit2

$ flatpak --installation=default install gnome org.gnome.gedit2

$ flatpak --user install gnome org.gnome.gedit//3.22

$ flatpak --user install https://sdk.gnome.org/gedit.flatpakref

Name

flatpak-list — List installed applications and/or runtimes

Synopsis

flatpak list [OPTION...]

Description

Lists the names of the installed applications and/or runtimes.

By default, both per-user and system-wide installations are shown. Use the --user, --installation or --system options to change this.

By default this lists both installed apps and runtimes, but you can change this by using the --app or --runtime option.

Options

The following options are understood:

-h, --help: Show help options and exit.
--user: List per-user installations.
--system: List the default system-wide installations.
--installation=NAME: List a system-wide installation specified by NAME among those defined in /etc/flatpak/installations.d/. Using --installation=default is equivalent to using --system .
--arch=ARCH: List installations for this architecture.
-d, --show-details: Show origin, sizes and other extra information.
--app: List applications.
--runtime: List runtimes.
--all, -a: List all installed runtimes, including locale and debug extensions. These are hidden by default.
-v, --verbose: Print debug information during command processing.
--ostree-verbose: Print OSTree debug information during command processing.

Examples

$ flatpak --user list

org.gnome.Builder
org.freedesktop.glxgears
org.gnome.MyApp
org.gnome.GEdit

Name

flatpak-make-current — Make a specific version of an app current

Synopsis

flatpak make-current [OPTION...] APP BRANCH

Description

Makes a particular branch of an application current. Only the current branch of an app has its exported files (such as desktop files and icons) made visible to the host.

When a new branch is installed it will automatically be made current, so this command is often not needed.

Unless overridden with the --user or --installation options, this command changes the default system-wide installation.

Options

The following options are understood:

-h, --help: Show help options and exit.
--user: Update a per-user installation.
--system: Update the default system-wide installation.
--installation=NAME: Updates a system-wide installation specified by NAME among those defined in /etc/flatpak/installations.d/. Using --installation=default is equivalent to using --system .
--arch=ARCH: The architecture to install for.
-v, --verbose: Print debug information during command processing.
--ostree-verbose: Print OSTree debug information during command processing.

Examples

$ flatpak --user make-current org.gnome.GEdit 3.14

Name

flatpak-override — Override application requirements

Synopsis

flatpak override [OPTION...] [APP]

Description

Overrides the application specified runtime requirements. This can be used to grant a sandboxed application more or less resources than it requested.

By default the application gets access to the resources it requested when it is started. But the user can override it on a particular instance by specifying extra arguments to flatpak run, or every time by using flatpak override.

If the application id is not specified then the overrides affect all applications, but the per-application overrides can override the global overrides.

Unless overridden with the --user or --installation options, this command changes the default system-wide installation.

Options

The following options are understood:

-h, --help

Show help options and exit.

--user

Update a per-user installation.

--system

Update the default system-wide installation.

--installation=NAME

Updates a system-wide installation specified by NAME among those defined in /etc/flatpak/installations.d/. Using --installation=default is equivalent to using --system .

--share=SUBSYSTEM

Share a subsystem with the host session. This overrides the Context section from the application metadata. SUBSYSTEM must be one of: network, ipc. This option can be used multiple times.

--unshare=SUBSYSTEM

Don't share a subsystem with the host session. This overrides the Context section from the application metadata. SUBSYSTEM must be one of: network, ipc. This option can be used multiple times.

--socket=SOCKET

Expose a well-known socket to the application. This overrides to the Context section from the application metadata. SOCKET must be one of: x11, wayland, fallback-x11, pulseaudio, system-bus, session-bus, ssh-auth. This option can be used multiple times.

--nosocket=SOCKET

Don't expose a well-known socket to the application. This overrides to the Context section from the application metadata. SOCKET must be one of: x11, wayland, fallback-x11, pulseaudio, system-bus, session-bus, ssh-auth. This option can be used multiple times.

--device=DEVICE

Expose a device to the application. This overrides to the Context section from the application metadata. DEVICE must be one of: dri, kvm, all. This option can be used multiple times.

--nodevice=DEVICE

Don't expose a device to the application. This overrides to the Context section from the application metadata. DEVICE must be one of: dri, kvm, all. This option can be used multiple times.

--allow=FEATURE

Allow access to a specific feature. This updates the [Context] group in the metadata. FEATURE must be one of: devel, multiarch, bluetooth. This option can be used multiple times.

See flatpak-build-finish(1) for the meaning of the various features.

--disallow=FEATURE

Disallow access to a specific feature. This updates the [Context] group in the metadata. FEATURE must be one of: devel, multiarch, bluetooth. This option can be used multiple times.

--filesystem=FS

Allow the application access to a subset of the filesystem. This overrides to the Context section from the application metadata. FS can be one of: home, host, xdg-desktop, xdg-documents, xdg-download xdg-music, xdg-pictures, xdg-public-share, xdg-templates, xdg-videos, xdg-run, xdg-config, xdg-cache, xdg-data, an absolute path, or a homedir-relative path like ~/dir or paths relative to the xdg dirs, like xdg-download/subdir. The optional :ro suffix indicates that the location will be read-only. The optional :create suffix indicates that the location will be read-write and created if it doesn't exist. This option can be used multiple times.

--nofilesystem=FILESYSTEM

Remove access to the specified subset of the filesystem from the application. This overrides to the Context section from the application metadata. FILESYSTEM can be one of: home, host, xdg-desktop, xdg-documents, xdg-download xdg-music, xdg-pictures, xdg-public-share, xdg-templates, xdg-videos, an absolute path, or a homedir-relative path like ~/dir. This option can be used multiple times.

--add-policy=SUBSYSTEM.KEY=VALUE

Add generic policy option. For example, "--add-policy=subsystem.key=v1 --add-policy=subsystem.key=v2" would map to this metadata:

[Policy subsystem]
key=v1;v2;

This option can be used multiple times.

--remove-policy=SUBSYSTEM.KEY=VALUE

Remove generic policy option. This option can be used multiple times.

--env=VAR=VALUE

Set an environment variable in the application. This overrides to the Context section from the application metadata. This option can be used multiple times.

--own-name=NAME

Allow the application to own the well-known name NAME on the session bus. This overrides to the Context section from the application metadata. This option can be used multiple times.

--talk-name=NAME

Allow the application to talk to the well-known name NAME on the session bus. This overrides to the Context section from the application metadata. This option can be used multiple times.

--system-own-name=NAME

Allow the application to own the well known name NAME on the system bus. If NAME ends with .*, it allows the application to own all matching names. This overrides to the Context section from the application metadata. This option can be used multiple times.

--system-talk-name=NAME

Allow the application to talk to the well known name NAME on the system bus. If NAME ends with .*, it allows the application to talk to all matching names. This overrides to the Context section from the application metadata. This option can be used multiple times.

--persist=FILENAME

If the application doesn't have access to the real homedir, make the (homedir-relative) path FILENAME a bind mount to the corresponding path in the per-application directory, allowing that location to be used for persistent data. This overrides to the Context section from the application metadata. This option can be used multiple times.

-v, --verbose

Print debug information during command processing.

--ostree-verbose

Print OSTree debug information during command processing.

Examples

$ flatpak override --nosocket=wayland org.gnome.GEdit

$ flatpak override --filesystem=home org.mozilla.Firefox

Name

flatpak-remote-add — Add a remote repository

Synopsis

Add from a .flatpakrepo file:

flatpak remote-add [OPTION...] [--from] NAME LOCATION

Manually specify repo uri and options:

flatpak remote-add [OPTION...] NAME LOCATION

Description

Adds a remote repository to the flatpak repository configuration. [NAME] is the name for the new remote, and [LOCATION] is a url or pathname. The [LOCATION] is either a flatpak repository, or a .flatpakrepo file which describes a repository. In the former case you may also have to specify extra options, such as the gpg key for the repo.

Unless overridden with the --user or --installation options, this command changes the default system-wide installation.

Options

The following options are understood:

-h, --help: Show help options and exit.
--from: Assume the URI is a .flatpakrepo file rather than the repository itself. This is enabled by default if the extension is .flatpakrepo, so generally you don't need this option.
--user: Modify the per-user configuration.
--system: Modify the default system-wide configuration.
--installation=NAME: Modify a system-wide installation specified by NAME among those defined in /etc/flatpak/installations.d/. Using --installation=default is equivalent to using --system .
--no-gpg-verify: Disable GPG verification for the added remote.
--prio=PRIO: Set the priority for the remote. Default is 1, higher is more prioritized. This is mainly used for graphical installation tools.
--no-enumerate: Mark the remote as not enumerated. This means the remote will not be used to list applications, for instance in graphical installation tools.
--no-use-for-deps: Mark the remote as not to be used for automatic runtime dependency resolution.
--if-not-exists: Do nothing if the provided remote already exists.
--disable: Disable the added remote.
--title=TITLE: A title for the remote, e.g. for display in a UI.
--default-branch=BRANCH: A default branch for the remote, mainly for use in a UI.
--gpg-import=FILE: Import gpg keys from the specified keyring file as trusted for the new remote. If the file is - the keyring is read from standard input.
--oci: This is a OCI format registry rather than a regular flatpak repository.
-v, --verbose: Print debug information during command processing.
--ostree-verbose: Print OSTree debug information during command processing.

Examples

$ flatpak remote-add gnome https://sdk.gnome.org/gnome.flatpakrepo

$ flatpak --user remote-add --no-gpg-verify test-repo https://people.gnome.org/~alexl/gnome-sdk/repo/

Name

flatpak-remote-delete — Delete a remote repository

Synopsis

flatpak remote-delete [OPTION...] NAME

Description

Removes a remote repository from the flatpak repository configuration. NAME is the name of an existing remote.

Unless overridden with the --system, --user, or --installation options, this command uses either the default system-wide installation or the per-user one, depending on which has the specified REMOTE .

Options

The following options are understood:

-h, --help: Show help options and exit.
--user: Modify the per-user configuration.
--system: Modify the default system-wide configuration.
--installation=NAME: Modify a system-wide installation specified by NAME among those defined in /etc/flatpak/installations.d/. Using --installation=default is equivalent to using --system .
--force: Remove remote even if its in use by installed apps or runtimes.
-v, --verbose: Print debug information during command processing.
--ostree-verbose: Print OSTree debug information during command processing.

Examples

$ flatpak --user remote-delete dried-raisins

Name

flatpak-remote-info — Show information about an application or runtime in a remote

Synopsis

flatpak remote-info [OPTION...] REMOTE REF

Description

Shows information about the runtime or application REF from the remote repository with the name REMOTE . You can find all configured remote repositories with flatpak remotes.

By default, the output is formatted in a friendly format. If you specify one of the options --show-ref, --show-commit, --show-parent, or --show-metadata, the output is instead formatted in a machine-readable format.

Unless overridden with the --system, --user, or --installation options, this command uses either the default system-wide installation or the per-user one, depending on which has the specified REMOTE .

Options

The following options are understood:

-h, --help: Show help options and exit.
--user: Use the per-user configuration.
--system: Use the default system-wide configuration.
--installation=NAME: Use a system-wide installation specified by NAME among those defined in /etc/flatpak/installations.d/. Using --installation=default is equivalent to using --system .
--runtime: Assume that REF is a runtime if not explicitly specified.
--app: Assume that REF is an app if not explicitly specified.
--arch=ARCH: The default architecture to look for, if not given explicitly in the REF .
--commit=COMMIT: Show information about the specific commit, rather than the latest version.
--log: Display a log of previous versions.
-r, --show-ref: Show the matched ref.
-c, --show-commit: Show the commit id.
-p, --show-parent: Show the parent commit id.
-m, --show-metadata: Show the metadata.
-v, --verbose: Print debug information during command processing.
--ostree-verbose: Print OSTree debug information during command processing.

Examples

$ flatpak --user remote-info flathub org.gnome.gedit

Ref: app/org.gnome.gedit/x86_64/stable
ID: org.gnome.gedit
Arch: x86_64
Branch: stable
Date: 2017-07-31 16:05:22 +0000
Subject: Build org.gnome.gedit at 3ec291fc1ce4d78220527fa79576f4cc1481ebe5
Commit: 3de7e9dde3bb8382aad9dfbbff20eccd9bf2100bc1887a3619ec0372e8066bf7
Parent: -
Download size: 3,4 MB
Installed size: 11,1 MB
Runtime: org.gnome.Platform/x86_64/3.24

Name

flatpak-remote-ls — Show available runtimes and applications

Synopsis

flatpak remote-ls [OPTION...] [REMOTE]

Description

Shows runtimes and applications that are available in the remote repository with the name REMOTE , or all remotes if one isn't specified. You can find all configured remote repositories with flatpak-remotes(1).

REMOTE can be a file:// URI pointing to a local repository instead of a remote name.

Unless overridden with the --system, --user, or --installation options, this command uses either the default system-wide installation or the per-user one, depending on which has the specified REMOTE .

Options

The following options are understood:

-h, --help: Show help options and exit.
--user: Use the per-user configuration.
--system: Use the default system-wide configuration.
--installation=NAME: Use a system-wide installation specified by NAME among those defined in /etc/flatpak/installations.d/. Using --installation=default is equivalent to using --system .
-d, --show-details: Show arches, branches and commit ids, in addition to the names.
--runtime: Show only runtimes, omit applications.
--app: Show only applications, omit runtimes.
--all, -a: Show everything. By default locale and debug extensions as well as secondary arches when the primary arch is available are hidden.
--updates: Show only those which have updates available.
--arch=ARCH: Show only those matching the specied architecture. By default, only supported architectures are shown. Use --arch=* to show all archtectures.
-v, --verbose: Print debug information during command processing.
--ostree-verbose: Print OSTree debug information during command processing.

Examples

$ flatpak --user remote-ls --app testrepo

Ref
org.gnome.Builder
org.freedesktop.glxgears

$ flatpak remote-ls file:///run/media/mwleeds/d4d37026-cde2-4e5e-8bcc-d23ebbf231f9/.ostree/repo

Ref
org.kde.Khangman

Name

flatpak-remote-modify — Modify a remote repository

Synopsis

flatpak remote-modify [OPTION...] NAME

Description

Modifies options for an existing remote repository in the flatpak repository configuration. NAME is the name for the remote.

Unless overridden with the --system, --user, or --installation options, this command uses either the default system-wide installation or the per-user one, depending on which has the specified REMOTE .

Options

The following options are understood:

-h, --help: Show help options and exit.
--user: Modify the per-user configuration.
--system: Modify the default system-wide configuration.
--installation=NAME: Modify a system-wide installation specified by NAME among those defined in /etc/flatpak/installations.d/. Using --installation=default is equivalent to using --system .
--no-gpg-verify: Disable GPG verification for the added remote.
--gpg-verify: Enable GPG verification for the added remote.
--prio=PRIO: Set the priority for the remote. Default is 1, higher is more prioritized. This is mainly used for graphical installation tools.
--no-enumerate: Mark the remote as not enumerated. This means the remote will not be used to list applications, for instance in graphical installation tools.
--no-use-for-deps: Mark the remote as not to be used for automatic runtime dependency resolution.
--disable: Disable the remote. Disabled remotes will not be automatically updated from.
--enable: Enable the remote.
--enumerate: Mark the remote as enumerated. This means the remote will be used to list applications, for instance in graphical installation tools.
--use-for-deps: Mark the remote as to be used for automatic runtime dependency resolution.
--title=TITLE: A title for the remote, e.g. for display in a UI.
--default-branch=BRANCH: A default branch for the remote, mainly for use in a UI.
--collection-id=COLLECTION-ID: The globally unique identifier of the remote repository, to allow mirrors to be grouped. This must only be set to the collection ID provided by the remote, and must not be set if the remote does not provide a collection ID.
--url=URL: Set a new URL.
--update-metadata: Update the remote's extra metadata from the OSTree repository's summary file. Only xa.title and xa.default-branch are supported at the moment.
--gpg-import=FILE: Import gpg keys from the specified keyring file as trusted for the new remote. If the file is - the keyring is read from standard input.
-v, --verbose: Print debug information during command processing.
--ostree-verbose: Print OSTree debug information during command processing.

Examples

$ flatpak --user remote-modify --no-gpg-verify test-repo

Name

flatpak-remotes — List remote repositories

Synopsis

flatpak remotes [OPTION...]

Description

Lists the known remote repositories, in priority order.

By default, both per-user and system-wide installations are shown. Use the --user, --system or --installation options to change this.

Options

The following options are understood:

-h, --help: Show help options and exit.
--user: Show the per-user configuration.
--system: Show the default system-wide configuration.
--installation=NAME: Show a system-wide installation by NAME among those defined in /etc/flatpak/installations.d/. Using --installation=default is equivalent to using --system .
-d, --show-details: Show more information for each repository in addition to the name.
--show-disabled: Show disabled repos.
-v, --verbose: Print debug information during command processing.
--ostree-verbose: Print OSTree debug information during command processing.

Examples

$ flatpak remotes --user --show-details

testrepo	Test Repository	 http://209.132.179.91/repo/ no-gpg-verify

Name

flatpak-repair — Repair a flatpak installation

Synopsis

flatpak repair [OPTION...]

Description

Repair a flatpak installation by pruning and reinstalling invalid objects. The repair command does all of the following:

Scan all locally available refs, removing any that don't correspond to a deployed ref.
Verify each commit they point to, removing any invalid objects and noting any missing objects.
Remove any refs that had an invalid object, and any non-partial refs that had missing objects.
Prune all objects not referenced by a ref, which gets rid of any possibly invalid non-scanned objects.
Enumerate all deployed refs and re-install any that are not in the repo (or are partial for a non-subdir deploy).

Options

The following options are understood:

-h, --help: Show help options and exit.
--user: Repair per-user installation.
--system: Repair system-wide installation.
--installation=NAME: Repair the system-wide installation specified by NAME among those defined in /etc/flatpak/installations.d/. Using --installation=default is equivalent to using --system .
-v, --verbose: Print debug information during command processing.
--ostree-verbose: Print OSTree debug information during command processing.

Examples

$ sudo flatpak repair

$ flatpak repair --user

Name

flatpak-repo — Show information about a local repository

Synopsis

flatpak repo [OPTION...] LOCATION

Description

Show information about a local repository.

Options

The following options are understood:

-h, --help: Show help options and exit.
--info: Print general information about a local repository.
--branches: List the branches in a local repository.
--metadata=BRANCH: Print metadata for a branch in the repository.
-v, --verbose: Print debug information during command processing.
--ostree-verbose: Print OSTree debug information during command processing.

Examples

$ flatpak repo --info ~/my-repo

Name

flatpak-run — Run an application or open a shell in a runtime

Synopsis

flatpak run [OPTION...] REF [ARG...]

Description

If REF names an installed application, flatpak runs the application in a sandboxed environment. Extra arguments are passed on to the application.

If REF names a runtime, a shell is opened in the runtime. This is useful for development and testing.

flatpak creates a sandboxed environment for the application to run in by mounting the right runtime at /usr and a writable directory at /var, whose content is preserved between application runs. The application itself is mounted at /app.

The details of the sandboxed environment are controlled by the application metadata and various options like --share and --socket that are passed to the run command: Access is allowed if it was requested either in the application metadata file or with an option and the user hasn't overridden it.

The remaining arguments are passed to the command that gets run in the sandboxed environment. See the --file-forwarding for handling of file arguments.

Options

The following options are understood:

-h, --help

Show help options and exit.

-v, --verbose

Print debug information during command processing.

--ostree-verbose

Print OSTree debug information during command processing.

--arch=ARCH

The architecture to install for.

--command=COMMAND

The command to run instead of the one listed in the application metadata.

--branch=BRANCH

The branch to use.

-d, --devel

Use the devel runtime that is specified in the application metadata instead of the regular runtime, and use a seccomp profile that is less likely to break development tools.

--runtime=RUNTIME

Use this runtime instead of the one that is specified in the application metadata. This is a full tuple, like for example org.freedesktop.Sdk/x86_64/1.2 , but partial tuples are allowed. Any empty or missing parts are filled in with the corresponding values specified by the app.

--runtime-version=VERSION

Use this version of the runtime instead of the one that is specified in the application metadata. This overrides any version specified with the --runtime option.

--share=SUBSYSTEM

Share a subsystem with the host session. This overrides the Context section from the application metadata. SUBSYSTEM must be one of: network, ipc. This option can be used multiple times.

--unshare=SUBSYSTEM

Don't share a subsystem with the host session. This overrides the Context section from the application metadata. SUBSYSTEM must be one of: network, ipc. This option can be used multiple times.

--socket=SOCKET

Expose a well known socket to the application. This overrides to the Context section from the application metadata. SOCKET must be one of: x11, wayland, fallback-x11, pulseaudio, system-bus, session-bus, ssh-auth. This option can be used multiple times.

--nosocket=SOCKET

Don't expose a well known socket to the application. This overrides to the Context section from the application metadata. SOCKET must be one of: x11, wayland, fallback-x11, pulseaudio, system-bus, session-bus, ssh-auth. This option can be used multiple times.

--device=DEVICE

Expose a device to the application. This overrides to the Context section from the application metadata. DEVICE must be one of: dri, kvm, all. This option can be used multiple times.

--nodevice=DEVICE

Don't expose a device to the application. This overrides to the Context section from the application metadata. DEVICE must be one of: dri, kvm, all. This option can be used multiple times.

--allow=FEATURE

Allow access to a specific feature. This overrides to the Context section from the application metadata. FEATURE must be one of: devel, multiarch, bluetooth. This option can be used multiple times.

See flatpak-build-finish(1) for the meaning of the various features.

--disallow=FEATURE

Disallow access to a specific feature. This overrides to the Context section from the application metadata. FEATURE must be one of: devel, multiarch, bluetooth. This option can be used multiple times.

--filesystem=FS

Allow the application access to a subset of the filesystem. This overrides to the Context section from the application metadata. FS can be one of: home, host, xdg-desktop, xdg-documents, xdg-download, xdg-music, xdg-pictures, xdg-public-share, xdg-templates, xdg-videos, xdg-run, xdg-config, xdg-cache, xdg-data, an absolute path, or a homedir-relative path like ~/dir or paths relative to the xdg dirs, like xdg-download/subdir. The optional :ro suffix indicates that the location will be read-only. The optional :create suffix indicates that the location will be read-write and created if it doesn't exist. This option can be used multiple times.

--nofilesystem=FILESYSTEM

Remove access to the specified subset of the filesystem from the application. This overrides to the Context section from the application metadata. FILESYSTEM can be one of: home, host, xdg-desktop, xdg-documents, xdg-download xdg-music, xdg-pictures, xdg-public-share, xdg-templates, xdg-videos, an absolute path, or a homedir-relative path like ~/dir. This option can be used multiple times.

--add-policy=SUBSYSTEM.KEY=VALUE

Add generic policy option. For example, "--add-policy=subsystem.key=v1 --add-policy=subsystem.key=v2" would map to this metadata:

[Policy subsystem]
key=v1;v2;

This option can be used multiple times.

--remove-policy=SUBSYSTEM.KEY=VALUE

Remove generic policy option. This option can be used multiple times.

--env=VAR=VALUE

Set an environment variable in the application. This overrides to the Context section from the application metadata. This option can be used multiple times.

--own-name=NAME

Allow the application to own the well known name NAME on the session bus. If NAME ends with .*, it allows the application to own all matching names. This overrides to the Context section from the application metadata. This option can be used multiple times.

--talk-name=NAME

Allow the application to talk to the well known name NAME on the session bus. If NAME ends with .*, it allows the application to talk to all matching names. This overrides to the Context section from the application metadata. This option can be used multiple times.

--system-own-name=NAME

Allow the application to own the well known name NAME on the system bus. If NAME ends with .*, it allows the application to own all matching names. This overrides to the Context section from the application metadata. This option can be used multiple times.

--system-talk-name=NAME

Allow the application to talk to the well known name NAME on the system bus. If NAME ends with .*, it allows the application to talk to all matching names. This overrides to the Context section from the application metadata. This option can be used multiple times.

--persist=FILENAME

If the application doesn't have access to the real homedir, make the (homedir-relative) path FILENAME a bind mount to the corresponding path in the per-application directory, allowing that location to be used for persistent data. This overrides to the Context section from the application metadata. This option can be used multiple times.

--log-session-bus

Log session bus traffic. This can be useful to see what access you need to allow in your D-Bus policy.

--log-system-bus

Log system bus traffic. This can be useful to see what access you need to allow in your D-Bus policy.

--file-forwarding

If this option is specified, the remaining arguments are scanned, and all arguments that are enclosed between a pair of '@@' arguments are interpreted as file paths, exported in the document store, and passed to the command in the form of the resulting document path. Arguments between '@@u' and '@@' are considered uris, and any file: uris are exported. The exports are non-persistent and with read and write permissions for the application.

Examples

$ flatpak run org.gnome.GEdit

$ flatpak run --devel --command=bash org.gnome.Builder

$ flatpak run --command=bash org.gnome.Sdk

Name

flatpak-search — Search for applications and runtimes

Synopsis

flatpak search TEXT

Description

Searches for applications and runtimes matching TEXT . Note that this uses appstream data that can be updated with flatpak-update(1). The appstream data is updated automatically only if it's at least a day old.

Options

The following options are understood:

--user: Only search through remotes in the per-user installation.
--system: Only search through remotes in the default system-wide installation.
--installation=NAME: Show a system-wide installation by NAME among those defined in /etc/flatpak/installations.d/. Using --installation=default is equivalent to using --system .
-h, --help: Show help options and exit.
-v, --verbose: Print debug information during command processing.
--ostree-verbose: Print OSTree debug information during command processing.

Name

flatpak-uninstall — Uninstall an application or runtime

Synopsis

flatpak uninstall [OPTION...] [REF...]

Description

Uninstalls an application or runtime. REF is a reference to the application or runtime to uninstall.

Each REF argument is a full or partial indentifier in the flatpak ref format, which looks like "(app|runtime)/ID/ARCH/BRANCH". All elements except ID are optional and can be left out, including the slashes, so most of the time you need only specify ID. Any part left out will be matched against what is installed, and if there are multiple matches an error message will list the alternatives.

By default this looks for both installed apps and runtimes with the given REF , but you can limit this by using the --app or --runtime option, or by supplying the initial element in the REF.

Normally, this command removes the ref for this application/runtime from the local OSTree repository and purges any objects that are no longer needed to free up disk space. If the same application is later reinstalled, the objects will be pulled from the remote repository again. The --keep-ref option can be used to prevent this.

If all branches of the application/runtime are removed, this command also purges the data directory for the application.

Unless overridden with the --system, --user, or --installation options, this command searches both the system-wide installation and the per-user one for REF and errors out if it exists in more than one.

Options

The following options are understood:

-h, --help: Show help options and exit.
--keep-ref: Keep the ref for the application and the objects belonging to it in the local repository.
--user: Uninstalls from a per-user installation.
--system: Uninstalls from the default system-wide installation.
--installation=NAME: Uninstalls from a system-wide installation specified by NAME among those defined in /etc/flatpak/installations.d/. Using --installation=default is equivalent to using --system .
--arch=ARCH: The architecture to uninstall, instead of the architecture of the host system.
--all: Remove all refs on the system.
--unused: Remove unused refs on the system.
-y, --assumeyes: Automatically answer yes to all questions. This is useful for automation.
--app: Only look for an app with the given name.
--runtime: Only look for a runtime with the given name.
--no-related: Don't uninstall related extensions, such as the locale data.
--force-remove: Remove files even if they're in use by a running application.
-v, --verbose: Print debug information during command processing.
--ostree-verbose: Print OSTree debug information during command processing.

Examples

$ flatpak --user uninstall org.gnome.GEdit

Name

flatpak-update — Update an application or runtime

Synopsis

flatpak update [OPTION...] [REF...]

flatpak update [OPTION...] --appstream [REMOTE]

Description

Updates applications and runtimes. REF is a reference to the application or runtime to update. If no REF is given, everything is updated, as well as appstream info for all remotes.

Each REF argument is a full or partial indentifier in the flatpak ref format, which looks like "(app|runtime)/ID/ARCH/BRANCH". All elements except ID are optional and can be left out, including the slashes, so most of the time you need only specify ID. Any part left out will be matched against what is installed, and if there are multiple matches an error message will list the alternatives.

By default this looks for both apps and runtimes with the given REF , but you can limit this by using the --app or --runtime option, or by supplying the initial element in the REF.

Normally, this command updates the application to the tip of its branch. But it is possible to check out another commit, with the --commit option.

If the configured remote for a ref being updated has a collection ID configured on it, flatpak will search mounted filesystems such as USB drives as well as Avahi services advertised on the local network for the needed refs, in order to support offline updates. See ostree-find-remotes(1) for more information.

Note that updating a runtime is different from installing a different branch, and runtime updates are expected to keep strict compatibility. If an application update does cause a problem, it is possible to go back to the previous version, with the --commit option.

Unless overridden with the --user, --system or --installation option, this command updates any matching refs in the standard system-wide installation and the per-user one.

Options

The following options are understood:

-h, --help: Show help options and exit.
--user: Update a per-user installation.
--system: Update the default system-wide installation.
--installation=NAME: Updates a system-wide installation specified by NAME among those defined in /etc/flatpak/installations.d/. Using --installation=default is equivalent to using --system .
--arch=ARCH: The architecture to update for.
--subpath=PATH: Install only a subpath of the ref. This is mainly used to install a subset of locales. This can be added multiple times to install multiple subpaths. If this is not specified the subpaths specified at install time are reused.
--commit=COMMIT: Update to this commit, instead of the tip of the branch. You can find commits using flatpak remote-info --log REMOTE REF.
--no-deploy: Download the latest version, but don't deploy it.
--no-pull: Don't download the latest version, deploy whatever is locally available.
--no-related: Don't download related extensions, such as the locale data.
--no-deps: Don't update or install runtime dependencies when installing.
--app: Only look for an app with the given name.
--appstream: Update appstream for REMOTE , or all remotes if no remote is specified.
--runtime: Only look for a runtime with the given name.
-y, --assumeyes: Automatically answer yes to all questions (or pick the most prioritized answer). This is useful for automation.
--force-remove: Remove old files even if they're in use by a running application.
-v, --verbose: Print debug information during command processing.
--ostree-verbose: Print OSTree debug information during command processing.

Examples

$ flatpak --user update org.gnome.GEdit

File Formats

Table of Contents

flatpakrepo — Reference to a remote
flatpakref — Reference to a remote for an application or runtime
flatpak installation — Configuration for an installation location
flatpak metadata — Information about an application or runtime
flatpak remote — Configuration for a remote

Name

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

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

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=
CollectionID=org.gnome.Apps

Name

flatpak-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 that is used by the 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.
CollectionID (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.
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.
RuntimeRepo (string): The url for a .flatpakref file for the runtime.

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=

Name

flatpak-installation — Configuration for an installation location

Description

flatpak can operate in system-wide or per-user mode. The system-wide data is located in $prefix/var/lib/flatpak/, and the per-user data is in $HOME/.local/share/flatpak/.

In addition to the default installation locations, more system-wide installations can be defined via configuration files /etc/flatpak/installations.d/, which must have the .conf extension and follow the format described below.

File format

The installation config file format is using the same .ini file format that is used for systemd unit files or application .desktop files.

[Installation …]

All the configuration for the the installation location with name NAME is contained in the [Installation "NAME"] group.

The following keys are recognized:

Path (string): The path for this installation. This key is mandatory.
DisplayName (string): The name to use when showing this installation in the UI.
Priority (integer): A priority for this installation.
StorageType (string): The type of storage used for this installation. Possible values include: network, mmc, sdcard, harddisk.

Examples

[Installation "extra"]
Path=/location/of/sdcard
DisplayName=Extra Installation
StorageType=sdcard

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): 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.
tags (string list): Tags to include in AppStream XML. 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.

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

shared (list)

List of subsystems to share with the host system. Possible subsystems: network, ipc. Available since 0.3.

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

devices (list)

List of devices to make available in the sandbox. Possible values:

dri: Graphics direct rendering (/dev/dri). Available since 0.3.
kvm: Virtualization (/dev/kvm). Available since 0.6.12.
all: All device nodes in /dev. Available since 0.6.6.

filesystems (list)

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

home

The entire home directory. Available since 0.3.

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.

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

Available since 0.3.

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

freedesktop.org special directories. 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. 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.

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.

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

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

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.
branch (string): The branch of the app, for example stable. Available since 0.6.10.
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.
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 and subnames. For instance if the app is called "org.my.App", it can only own "org.my.App" and "org.my.App.*". Its also only allowed to talk to the bus itself (org.freedesktop.DBus) and the portal APIs 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 entry are, in increasing order or access:

none: The bus name or names in question is invisible to the application. Available since 0.2.
see: The bus name or names can be enumerated by the application. Available since 0.2.
talk: The application can send messages/ and receive replies and signals from the bus name or names. Available since 0.2.
own: The application can own the bus name or names (as well as all the above). 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.

[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. 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.9.1, and backported to the 0.8.x branch in 0.8.3.
enable-if (string): A condition that must be true for the extension to be enabled. 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.9.1, and backported to the 0.8.x branch in 0.8.3.
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.
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.

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

[Extension org.gnome.Calculator.Locale]
directory=share/runtime/locale
subdirectories=true

[Extension org.gnome.Calculator.Debug]
directory=lib/debug

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 config fragments 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.

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. Defaults to 1.
xa.noenumerate (boolean): Whether this remote should be used when presenting available contents. Defaults to true.
xa.nodeps (boolean): Whether this remote should be used when searching for dependencies. Defaults to true.
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.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.oci (boolean): Whether this is an OCI remote. Defaults to false.

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

Flatpak Builder Command Reference

Version 0.99.3

Important

The command reference is generated from the flatpak-builder repo; see https://github.com/flatpak/flatpak-builder/tree/master/doc

Flatpak-builder is a tool to build flatpak applications.

Table of Contents

Executables

flatpak-builder — Help build application dependencies

File Formats

flatpak manifest — Information for building an application

Executables

Table of Contents

flatpak-builder — Help build application dependencies

Name

flatpak-builder — Help build application dependencies

Synopsis

flatpak-builder [OPTION...] DIRECTORY MANIFEST

flatpak-builder --run [OPTION...] DIRECTORY MANIFEST COMMAND

flatpak-builder --show-deps [OPTION...] MANIFEST

Description

flatpak-builder is a wrapper around the flatpak build command that automates the building of applications and their dependencies. It is one option you can use to build applications.

The goal of flatpak-builder is to push as much knowledge about how to build modules to the individual upstream projects. It does this by assuming that the modules adhere to the Build API specified at https://github.com/cgwalters/build-api. This essentially means that it follows the ./configure && make && make install scheme with an optional autogen script. If the upstream does not adhere to the API you can make it do so by adding patches and extra files.

An invocation of flatpak-builder proceeds in these stages, each being specified in detail in json format in MANIFEST :

Download all sources
Initialize the application directory with flatpak build-init
Build and install each module with flatpak build
Clean up the final build tree by removing unwanted files and e.g. stripping binaries
Finish the application directory with flatpak build-finish

After this you will end up with a build of the application in DIRECTORY , which you can export to a repository with the flatpak build-export command. If you use the --repo option, flatpak-builder will do the export for you at the end of the build process. When flatpak-builder does the export, it also stores the manifest that was used for the build in /app/manifest.json. The manifest is 'resolved', i.e. git branch names are replaced by the actual commit IDs that were used in the build.

At each of the above steps flatpak caches the result, and if you build the same file again, it will start at the first step where something changes. For instance the first version controlled source that had new commits added, or the first module where some changes to the MANIFEST file caused the build environment to change. This makes flatpak-builder very efficient for incremental builds.

When building a flatpak to be published to the internet, --collection-id=COLLECTION-ID should be specified as a globally unique reverse DNS value to identify the collection of flatpaks this will be added to. Setting a globally unique collection ID allows the apps in the repository to be shared over peer to peer systems without needing further configuration.

Manifest

The manifest file is a json file whose format is described in detail in its own manual page.

Options

The following options are understood:

-h, --help

Show help options and exit.

-v, --verbose

Print debug information during command processing.

--version

Print version information and exit.

--arch=ARCH

Specify the machine architecture to build for. If no architecture is specified, the host architecture will be automatically detected. Only host compatible architectures can be specified.

--default-branch=BRANCH

Set the default branch to BRANCH. This is used if the manifest does not specify a branch. The default is master.

--disable-cache

Don't look at the existing cache for a previous build, instead always rebuild modules.

--disable-rofiles-fuse

Disable the use of rofiles-fuse to optimize the cache use via hardlink checkouts.

--disable-download

Don't download any sources. This only works if some version of all sources are downloaded already. This is useful if you want to guarantee that no network i/o is done. However, the build will fail if some source is not locally available.

--disable-updates

Download missing sources, but don't update local mirrors of version control repos. This is useful to rebuild things but without updating git, bzr or svn repositories from the remote repository.

--disable-tests

Don't run any of the tests.

--run

Run a command in a sandbox based on the build dir. This starts flatpak build, with some extra arguments to give the same environment as the build, and the same permissions the final app will have. The command to run must be the last argument passed to flatpak-builder, after the directory and the manifest.

Only the --arch=ARCH, --ccache and --verbose options can be combined with this option.

--build-shell=MODULENAME

Extract and prepare the sources for the named module, and then start a shell in a sandbox identical to the one flatpak-builder would use for building the module. This is useful to debug a module.

--show-deps

List all the (local) files that the manifest depends on.

Only the --verbose option can be combined with this option.

--download-only

Exit successfully after downloading the required sources.

--bundle-sources

Create an additional runtime with the source code for this module. It will be named app-id.Sources, for example org.gnome.Maps.Sources.

--build-only

Don't do the cleanup and finish stages, which is useful if you want to build more things into the app.

--finish-only

Only do the cleanup, finish and export stages, picking up where a --build-only command left off.

--export-only

Only do the export stages, picking up the build result from a previous build. This can be used to split the build and export/signature into two calls by leaving out --repo in the first call.

--require-changes

Do nothing, leaving a non-existent DIRECTORY if nothing changes since last cached build. If this is not specified, the latest version from the cache will be put into DIRECTORY .

--state-dir=PATH

Use this directory for storing state (downloads, build dirs, build cache, etc) rather than .flatpak-builder. This can be an absolute or relative path, but must be on the same filesystem as the specified target DIRECTORY .

--keep-build-dirs

Don't remove the sources and build after having built and installed each module. This also creates a symlink to the build directory with a stable name ("build-modulename").

--delete-build-dirs

Always remove the sources and build after having built each module, even if the build failed. The default is to keep failed build directories but remove successful ones. This is useful in e.g. automatic build systems.

--ccache

Enable use of ccache in the build (needs ccache in the sdk)

--stop-at=MODULENAME

Stop at the specified module, ignoring it and all the following ones in both the "download" and "build" phases. This is useful for debugging and development. For instance, you can build all the dependencies, but stop at the main application so that you can then do a build from a pre-existing checkout. Implies --build-only.

--repo=DIR

When build is done, run export the result to this repository.

-s, --subject=SUBJECT

One line subject for the commit message. Used when exporting the build results.

-b, --body=BODY

Full description for the commit message. Used when exporting the build results.

--collection-id=COLLECTION-ID

Set as the collection ID of the repository. 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.

--gpg-sign=KEYID

Sign the commit with this GPG key. Used when exporting the build results. This option can be used multiple times.

--gpg-homedir=PATH

GPG Homedir to use when looking for keyrings. Used when exporting the build results.

--jobs=JOBS

Limit the number of parallel jobs during the build. The default is the number of CPUs on the machine.

--force-clean

Erase the previous contents of DIRECTORY if it is not empty.

--sandbox

Disable the possibility to specify build-args that are passed to flatpak build. This means the build process can't break out of its sandbox, and is useful when building less trusted software.

--allow-missing-runtimes

Do not immediately fail if the sdk or platform runtimes are not installed on this system. Attempting to build any manifest modules will still fail if the sdk is missing, but may be useful for apps that install files without a sandbox build.

--rebuild-on-sdk-change

Record the exact version of the sdk in the cache, and rebuild everything if it changes. This is useful if you're building against an API-unstable runtime, like a nightly build.

--skip-if-unchanged

If the json is unchanged since the last build of this filename, then do nothing, and return exit code 42.

--mirror-screenshots-url=URL

Mirror any screenshots in the appstream and rewrite the appstream xml as if they were on the specified URL. The resulting files will be stored in the "screenshots" subdirectory in the app directory and needs to be copied to the specified URL for the appdata to work.

--extra-sources=SOURCE-DIR

When downloading sources (archives, files, git, bzr, svn), look in this directory for pre-existing copies and use them instead of downloading.

--extra-sources-url=URL

When downloading sources (archives, files, git, bzr, svn), look at this url for mirrored downloads before downloading from the original url.

--from-git=GIT

Look for the manifest in the given git repository. If this option is given, MANIFEST is interpreted as a relative path inside the repository.

--from-git-branch=BRANCH

The branch to use with --from-git.

--no-shallow-clone

Don't use shallow clones when mirroring git repos.

--install-deps-from=REMOTE

Install/update build required dependencies from the specified remote.

--install-deps-only

Stop after downloading dependencies.

--install

When the build is finished, install the result locally.

--user

Install the dependencies in a per-user installation.

--system

Install the dependencies in the default system-wide installation.

--installation=NAME

Install the dependencies in a system-wide installation specified by NAME among those defined in /etc/flatpak/installations.d/. Using --installation=default is equivalent to using --system .

Caching

flatpak-builder caches sources and partial build results in the state directory (defaulting to the .flatpak-builder subdirectory of the current directory). If you use --keep-build-dirs, build directories for each module are also stored here.

It is safe to remove the state directory. This will force a full build the next time you build.

Examples

$ flatpak-builder my-app-dir manifest.json

Example manifest file:

{
    "id": "org.test.TestApp",
    "runtime": "org.freedesktop.Platform",
    "runtime-version": "1.2",
    "sdk": "org.freedesktop.Sdk",
    "command": "test",
    "clean": [ "/include", "*.la" ],
    "build-options" : {
        "cflags": "-O2 -g",
        "cxxflags": "-O2 -g",
        "env": {
            "V": "1"
        },
        "arch": {
            "x86_64": {
                "cflags": "-O3 -g",
            }
        }
    },
    "modules": [
        {
            "name": "pygobject",
            "config-opts": [ "--disable-introspection" ],
            "sources": [
                {
                    "type": "archive",
                    "url": "http://ftp.gnome.org/pub/GNOME/sources/pygobject/2.28/pygobject-2.28.6.tar.xz",
                    "sha256": "fb8a1d4f665130a125011659bd347c7339c944232163dbb9a34fd0686577adb8"
                },
                {
                    "type": "patch",
                    "path": "required-pygobject-fix.patch"
                },
                {
                    "type": "file",
                    "path": "pygobject-extra-file",
                    "dest-filename": "extra-file"
                }
            ]
        },
        {
            "name": "babl",
            "build-options" : { "cxxflags": "-O2 -g -std=c++11" },
            "cleanup": [ "/bin" ],
            "sources": [
                {
                    "type": "git",
                    "url": "git://git.gnome.org/babl"
                }
            ]
        },
        {
            "name": "testapp",
            "sources": [
                {
                    "type": "bzr",
                    "url": "lp:testapp"
                }
            ]
        }
    ]
}

File Formats

Table of Contents

flatpak manifest — Information for building an application

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 of the application, defaults to master.
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.
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.
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 extensions points from the base application or sdk when finishing the build.
inherit-sdk-extensions (array of strings): Inherit these extra extensions 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 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 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.
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.
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.
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 properies 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.

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.
config-opts (array of strings): An array of options that will be passed to configure
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.

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

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 the basename of path.

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
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.
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.
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 allows 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": "git://git.gnome.org/babl"
                }
            ]
        },
        {
            "name": "testapp",
            "sources": [
                {
                    "type": "bzr",
                    "url": "lp:testapp"
                }
            ]
        }
    ]
}

ID	描述
org.freedesktop.Platform	运行时
org.freedesktop.Platform.Locale	运行时翻译（扩展）
org.freedesktop.Sdk	SDK
org.freedesktop.Sdk.Debug	SDK调试信息（扩展）
org.freedesktop.Sdk.Locale	SDK翻译（扩展）
org.freedesktop.Sdk.Docs	SDK文档（扩展）

ID	描述
org.gnome.Platform	运行时
org.gnome.Platform.Locale	运行时翻译（扩展）
org.gnome.Sdk	SDK
org.gnome.Sdk.Debug	SDK调试信息（扩展）
org.gnome.Sdk.Locale	SDK翻译（扩展）
org.gnome.Sdk.Docs	SDK文档（扩展）

ID	描述
org.kde.Platform	运行时
org.kde.Platform.Locale	运行时翻译（扩展）
org.kde.Sdk	SDK
org.kde.Sdk.Debug	SDK调试信息（扩展）
org.kde.Sdk.Locale	SDK翻译（扩展）
org.kde.Sdk.Docs	SDK文档（扩展）

`host`	访问所有文件
`home`	访问home目录
`/some/dir`	访问任意路径
`~/some/dir`	访问任意相对home目录的路径
`xdg-desktop`	访问XDG桌面目录
`xdg-documents`	访问XDG文档目录
`xdg-download`	访问XDG下载目录
`xdg-music`	访问XDG音乐目录
`xdg-pictures`	访问XDG图片目录
`xdg-public-share`	访问XDG公共目录
`xdg-videos`	访问XDG视频目录
`xdg-templates`	访问XDG模板目录

`--socket=x11`	使用X11显示窗口
`--share=ipc`	与主机共享IPC命名空间 [#f1]
`--device=dri`	OpenGL渲染
`--socket=wayland`	通过Wayland显示窗口
`--socket=pulseaudio`	使用PulseAudio播放音频
`--share=network`	访问网络 [#f2]
`--talk-name=org.freedesktop.secrets`	在会话总线中与命名服务通信
`--system-talk-name=org.freedesktop.GeoClue2`	在系统总线中与命名服务通信
`--socket=system-bus`	对所有的D-Bus无限制访问