YAMLing the flathub

综合技术 2018-05-04

The most common way to build flatpak is using a tool called flatpak-builder. This is a tool that takes a higher level description of the sources that go into an application and generate the build commands to build it. This description is called a manifest
, and is traditionally a JSON file.

JSON is very common in the web world, and it is a well known format that have many implementations. However, it is not really great for humans to write.

For example, JSON has no support for comments, which you typically want in something as complicated as a build script. There are ways to work around this, but it is not pretty.

The syntax, while easy for a machine to parse, is very verbose and noisy to read and picky to write. For example, all lists have to be comma separated, but you can’t have a trailing comma, which you often run into when deleting or moving items around. Also, both keys and values always have to be quoted, which feels pretty unnecessary for the simple one-word keys and values that are common case in manifest files.

This is what a JSON manifest look like:

  "id": "org.gnome.frogr",
  "runtime": "org.gnome.Platform",
  "sdk": "org.gnome.Sdk",
  "runtime-version": "3.26",
  "command": "frogr",
  "finish-args": [
    "--share=ipc", "--socket=x11",
  "build-options" : {
    "cflags": "-O2 -g",
    "env": {
      "V": "1"
  "cleanup": [ "/share/man" ],
  "modules": [
      "name": "frogr",
      "buildsystem": "meson",
      "sources": [
          "type": "git",
          "url": "git://git.gnome.org/frogr",
          "branch": "RELEASE_1.4",
          "commit": "e2322c8f99f9d3a3cdc020b79c6c7224ad1988d0"

Starting in flatpak-builder 0.10.10 you can now also use YAML
for manifests. In term of the content model, YAML is a superset of JSON, but it is easier for humans to read and write. This makes it a good fit for flatpak-builder. In fact, the implementation internally just converts the YAML parser nodes to JSON parser nodes.

Yesterday I enabled support in flathub
, so you can now convert existing apps, or submit new apps using YAML.

Here is how the above manifest looks in YAML:

id: org.gnome.frogr
runtime: org.gnome.Platform
sdk: org.gnome.Sdk
runtime-version: 3.26
command: frogr
  - --share=ipc
  - --socket=x11
  - --socket=wayland
  - --share=network
  # Grant app access to ~/Pictures
  - --filesystem=xdg-pictures
  cflags: -O2 -g
  env: { V: '1' }
cleanup: [ /share/man ]
  - name: frogr
    buildsystem: meson
      - type: git
        url: git://git.gnome.org/frogr
        branch: RELEASE_1.4
        commit: e2322c8f99f9d3a3cdc020b79c6c7224ad1988d0

This is clearly the same content as above (except it has a comment), but shorter and more readable.

For a longer example, see this conversion of a flathub app.

Of course, YAML is not perfect. Its a pretty complex format, it relies on indentation, and the specification has historically been a bit vague with implementations sometimes differing in interpretation. Going forward both JSON and YAML will be supported (and can even be mixed when you use includes), allowing you to chose what works best for you.


git ubuntu clone This is the second post in a collaborative series between Robie Basak and myself to introduce (more formally) git ubuntu to a broader audience. ...
Ephemeral port exhaustion and how to avoid it Recently, a production incident caused a part of our system to reject all new connections. The culprit: “ephemeral port exhaustion.” By default, yo...
Visual Studio Code 1.18 – October 2017 October 2017 (version 1.18) Welcome to the October 2017 release of Visual Studio Code. There are a number of significant updates in this release and...
skynet socketserver 1. 异步IO skynet用C编写的sokcet模块使用异步回调机制,通过lualib-src/lua-socket.c导出为socketdriver模块。skynet socket C API使用的异步回调方式是:在启动socket时,记录当前服务handle,之后该socket上面的消息...
Socket.io does not work on Firefox & Chrome I'm trying to develop a simple chat application. Here is my chat.js file. var app = require('http').createServer(handler) , io = require...