清单#

The input to flatpak-builder is a JSON or YAML file that describes the parameters for building an application, as well as instructions for each of the modules that are to be built. This file is called the manifest.

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

Manifest files should be named using the application ID. For example, the manifest file for GNOME Dictionary is named org.gnome.Dictionary.yml. This page uses this manifest file for all its examples.

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

基本属性#

Each manifest file should specify basic information about the application that is to be built, including the id, runtime, runtime-version, sdk and command parameters. These properties are typically specified at the beginning of the file.

举个例子,GNOME Dictionary的清单文件包含:

id: org.gnome.Dictionary
runtime: org.gnome.Platform
runtime-version: '45'
sdk: org.gnome.Sdk
command: gnome-dictionary

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

文件重命名#

Exports are application files that are made available to the host, and include things like the application’s .desktop file and icon.

The names of files that are exported by a Flatpak must be prefixed using the application ID, such as org.gnome.Dictionary.desktop. The best way to do this is to rename these files directly in the application’s source.

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

  • rename-icon - 重命名应用图标

  • rename-desktop-file - 重命名 .desktop 文件

  • rename-appdata-file - rename the MetaInfo file

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

Finishing#

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

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

finish-args:
  # X11 + XShm access
  - --share=ipc
  - --socket=fallback-x11
  # Wayland access
  - --socket=wayland
  # GPU acceleration if needed
  - --device=dri
  # Needs to talk to the network:
  - --share=network
  # Needs to save files locally
  - --filesystem=xdg-documents

Guidance on which permissions to use can be found in the 沙箱权限, and a full list of finish-args options can be found in Sandbox Permissions Reference.

If you’re wondering about the last finish arg, see this blog post.

cleanup#

The cleanup property can be used to remove files produced by the build process that are not wanted as part of the application, such as headers or developer documentation. Two properties in the manifest file are used for this.

First, a list of filename patterns can be included:

cleanup:
  - '/include'
  - '/bin/foo-*'
  - '*.a'

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

cleanup-commands:
  - 'sed s/foo/bar/ /bin/app.sh'

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

模块#

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

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

modules:
  - name: gnome-dictionary
    buildsystem: meson
    config-opts:
      - -Dbuild_man=false
    sources:
      - type: archive
        url: https://download.gnome.org/sources/gnome-dictionary/3.26/gnome-dictionary-3.26.1.tar.xz
        sha256: 16b8bc248dcf68987826d5e39234b1bb7fd24a2607fcdbf4258fde88f012f300
      - type: patch
        path: appdata_oars.patch

可以看出,每个列出的模块有一个 name (可以自由分配)和一个 sources 列表。每个source都有一个 type ,可用的type有:

  • archive - .tar or .zip 归档文件

  • git - Git 仓库

  • bzr - Bazaar 仓库

  • file - local/remote files (these are copied into the source directory)

  • dir - local directories (these are copied into the source directory)

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

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

  • patch - 补丁(用于源代码目录)

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

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

受支持的构建系统#

模块可以用多种构建系统构建,包含:

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

Shared Modules#

Shared Modules (or shared-modules) is a repository containing various manifests to build common libraries. It is intended to be used as a git submodule.

To add it to your repository, run this command:

git submodule add https://github.com/flathub/shared-modules.git

Then, add whichever module you want. In this example, we will use gtk2:

modules:
  - shared-modules/gtk2/gtk2.json

To update the submodule, run this command:

git submodule update --remote --merge

To remove the submodule, run these commands:

git submodule deinit -f -- shared-modules
rm -rf .git/modules/shared-modules
git rm -f shared-modules
rm .gitmodules

Flatpak Builder Tools#

Flatpak Builder Tools (or flatpak-builder-tools) is a collection of scripts to aid using flatpak-builder. In this repository, each directory contains instructions to generate a manifest for the respective platform.

实例清单文件#

A complete manifest for GNOME Dictionary built from Git. It is also possible to browse all the manifests hosted by Flathub.