Current Solutions

There have always been multiple ways to build WebKit and its dependencies on your host however this was never a great developer experience. Only very specific hosts could be “supported”, you often had to build a large number of dependencies, and the end result wasn’t very reproducable for others.

The current solution used by default is a Flatpak based one. This was a big improvement for ease of use and excellent for reproducablity but it introduced many challenges doing development work. As it has a strict sandbox and provides read-only runtimes it was difficult to use complex tooling/IDEs or develop third party libraries in it.

The new SDK tries to take a middle ground between those two alternatives, isolating itself from the host to be somewhat reproducable, yet being a mutable environment to be flexible enough for a wide range of tools and workflows.

The WebKit Container SDK

At the core it is an Ubuntu OCI image with all of the dependencies and tooling needed to work on WebKit. On top of this we added some scripts to run/manage these containers with podman and aid in developing inside of the container. It’s intention is to be as simple as possible and not change traditional development workflows.

You can find the SDK and follow the quickstart guide on our GitHub: https://github.com/Igalia/webkit-container-sdk

The main requirements is that this only works on Linux with podman 4.0+ installed. For example Ubuntu 23.10+.

In the most simple case, once you clone https://github.com/Igalia/webkit-container-sdk.git, using the SDK can be a few commands:

source /your/path/to/webkit-container-sdk/register-sdk-on-host.sh
wkdev-create --create-home
wkdev-enter

From there you can use WebKit’s build scripts (./Tools/Scripts/build-webkit --gtk) or CMake. As mentioned before it is an Ubuntu installation so you can easily install your favorite tools directly like VSCode. We even provide a wkdev-setup-vscode script to automate that.

Advanced Usage

Disposibility

A workflow that some developers may not be familiar with is making use of entirely disposable development environments. Since these are isolated containers you can easily make two. This allows you to do work in parallel that would interfere with eachother while not worrying about it as well as being able to get back to a known good state easily:

wkdev-create --name=playground1
wkdev-create --name=playground2

podman rm playground1 # You would stop first if running.
wkdev-enter --name=playground2

Working on Dependencies

An important part of WebKit development is working on the dependencies of WebKit rather than itself, either for debugging or for new features. This can be difficult or error-prone with previous solutions. In order to make this easier we use a project called JHBuild which isn’t new but works well with containers and is a simple solution to work on our core dependencies.

Here is an example workflow working on GLib:

wkdev-create --name=glib
wkdev-enter --name=glib

# This will clone glib main, build, and install it for us. 
jhbuild build glib

# At this point you could simply test if a bug was fixed in a different versin of glib.
# We can also modify and debug glib directly. All of the projects are cloned into ~/checkout.
cd ~/checkout/glib

# Modify the source however you wish then install your new version.
jhbuild make

Remember that containers are isoated from each other so you can even have two terminals open with different builds of glib. This can also be used to test projects like Epiphany against your build of WebKit if you install it into the JHBUILD_PREFIX.

To Be Continued

In the next blog post I’ll document how to use VSCode inside of the SDK for debugging and development.

Clients

Before we talk about Flatpak we have to talk about how GTK3 itself decides what theme you use.

Wayland

If you use Wayland this is very simple. It talks to xdg-desktop-portal-gtk to get your theme name from the host. The setting location on the host is in GSettings:

gsettings set org.gnome.desktop.interface gtk-theme 'Adwaita-dark'

gnome-tweaks sets this value for you, so I’d recommend just using it. Other desktop tools may set this value in their respective settings applications.

X11

If you are on X11 it relies upon a standard known as XSettings. How to configure this is less straightforward. On GNOME it uses gsd-xsettings as part of the gnome-settings-daemon project and it reads the GSettings value discussed above.

If you use a different daemon like xsettingsd you have to set Net/ThemeName in its configuration file. Other desktops may have their own daemon that need to be configured.

Getting themes inside of Flatpak

Now that your theme is actually configured properly you need to get the theme files inside of flatpak. You often can run a single command, flatpak update and everything will work now. It reads the GSetting discussed above and downloads a packaged theme.

Not packaged themes

If no package for the theme was found a common direction people go in is modifying permissions to add folders to the sandbox. I don’t recommend this. Instead here is how you package your theme.

#!/bin/bash
DEFAULT_ARCH=`flatpak --default-arch`
THEME_NAME=`gsettings get org.gnome.desktop.interface gtk-theme | tr -d \'`
THEME_EXTENSION_DIR=~/.local/share/flatpak/extension/org.gtk.Gtk3theme.$THEME_NAME/$DEFAULT_ARCH/3.22

mkdir -p $THEME_EXTENSION_DIR

cp -r /usr/share/themes/$THEME_NAME/gtk-3.0/* $THEME_EXTENSION_DIR

This simply copies your theme into a private flatpak extension and everything should work fine as long as there aren’t weird symlinks in your theme. Replace /usr/share/themes with a different directory like ~/.themes if needed.

Web browsers have supported extensions in some form for decades. They allow the creation of features that would otherwise be part of a browser but can be authored and experimented with more easily. They’ve helped develop and popularize ideas like ad blocking, password management, and reader modes. Sometimes, as in very popular cases like these, browsers themselves then begin trying to apply lessons upstream.

Toward universal support

For most of this history, web extensions have used incompatible browser-specific APIs. This began to change in 2015 with Firefox adopting an API similar to Chrome’s. In 2020, Safari also followed suit. We now have the foundations of an ecosystem-wide solution.

“The foundations of” is an important thing to understand: There are still plenty of existing extensions built with browser-specific APIs and this doesn’t magically make them all portable. It does, however, provide a way towards making portable extensions. In some cases, existing extensions might just need some porting. In other cases, they may utilize features that aren’t entirely universal yet (or, may never be).

Bringing Extensions to Epiphany

With version 43.alpha Epiphany users can begin to take advantage of some of the same powerful and portable extensions described above. Note that there are quite a few APIs that power this and with this release we’ve covered a meaningful segment of them but not all (details below). Over time our API coverage and interoperability will continue to grow.

What WebExtensions can do: Technical Details

At a high level, WebExtensions allow a private privileged web page to run in the browser. This is an invisible Background Page that has access to a browser JavaScript API. This API, given permission, can interact with browser tabs, cookies, downloads, bookmarks, and more.

Along with the invisible background page, it gives a few options to show a UI to the user. One such method is a Browser Action which is shown as a button in the browser’s toolbar that can popup an HTML view for the user to interact with. Another is an Options Page dedicated to configuring the extension.

Lastly, an extension can inject JavaScript directly into any website it has permissions to via Content Scripts. These scripts are given full access to the DOM of any web page they run in. However content scripts don’t have access to the majority of the browser API but, along with the above pages, it has the ability to send and receive custom JSON messages to all pages within an extension.

Example usage

For a real-world example, I use Bitwarden as my password manager which I’ll simplify how it roughly functions. Firstly there is a Background Page that does account management for your user. It has a Popup that the user can trigger to interface with your account, passwords, and options. Finally, it also injects Content Scripts into every website you open.

The Content Script can detect all input fields and then wait for a message to autofill information into them. The Popup can request the details of the active tab and, upon you selecting an account, send a message to the Content Script to fill this information. This flow does function in Epiphany now but there are still some issues to iron out for Bitwarden.

Epiphany’s current support

Epiphany 43.alpha supports the basic structure described above. We are currently modeling our behavior after Firefox’s ManifestV2 API which includes compatibility with Chrome extensions where possible. Supporting ManifestV3 is planned alongside V2 in the future.

As of today, we support the majority of:

• alarms - Scheduling of events to trigger at specific dates or times.
• commands - Keyboard shortcuts.
• cookies - Management and querying of browser cookies.
• downloads - Ability to start and manage downloads.
• menus - Creation of context menu items.
• notifications - Ability to show desktop notifications.
• storage - Storage of extension private settings.
• tabs - Control and monitoring of browser tabs, including creating, closing, etc.
• windows - Control and monitoring of browser windows.

A notable missing API is webRequest which is commonly used by blocking extensions such as uBlock Origin or Privacy Badger. I would like to implement this API at some point however it requires WebKitGTK improvements.

For specific API details please see Epiphany’s documentation.

What this means today is that users of Epiphany can write powerful extensions using a well-documented and commonly used format and API. What this does not mean is that most extensions for other browsers will just work out of the box, at least not yet. Cross-browser extensions are possible but they will have to only require the subset of APIs and behaviors Epiphany currently supports.

How to install extensions

This support is still considered experimental so do understand this may lead to crashes or other unwanted behavior. Also please report issues you find to Epiphany rather than to extensions.

You can install the development release and test it like so:

flatpak remote-add --if-not-exists gnome-nightly https://nightly.gnome.org/gnome-nightly.flatpakrepo
flatpak install gnome-nightly org.gnome.Epiphany.Devel
flatpak run --command=gsettings org.gnome.Epiphany.Devel set org.gnome.Epiphany.web:/org/gnome/epiphany/web/ enable-webextensions true

You will now see Extensions in Epiphany’s menu and if you run it from the terminal it will print out any message logged by extensions for debugging. You can download extensions most easily from Mozilla’s website.

Performance

In simple terms what HTTP/2 provides for improved performance is more efficient network usage when requesting multiple files from a single host. It does this by avoiding making new connections whenever possible and over that single connection allowing multiple requests to happen at the same time.

It is easy to imagine many workloads this would improve, such as flatpak downloading a lot of objects from a single server.

Here are some examples in Epiphany:

gophertiles

This is a benchmark made to directly test the best case for HTTP/2. As you can see in the inspector (which has been improved to show more network information) you can see HTTP/2 creates a single connection and completes in 229ms. HTTP/1 on the other-hand creates 6 connections taking 1.5 seconds. This all happens on a network which is a best case for HTTP/1, a low latency wired gigabit connection; As network latency increases HTTP/2’s lead grows dramatically.

Youtube

For a more real world example Youtube is a great demo. It hosts a lot of files for a webpage but it isn’t a perfect benchmark as it still involves multiple hosts that don’t share connections. HTTP/2 still has the slight lead, again versus HTTP/1’s best case.

Testing

This work is all new and we would really like some testing and feedback. The easiest way to run this yourself is with this custom Epiphany Flatpak (sorry for the slow download server, and it will not work with NVidia drivers).

You can get useful debug output both through the WebKit inspector (ctrl+shift+i) and by running with --env='G_MESSAGES_DEBUG=libsoup-http2;nghttp2'.

Please report any bugs you find to https://gitlab.gnome.org/gnome/libsoup/issues.

History

Before getting into what is changing I want to briefly give backstory to why these changes are happening.

The library has a long history, that I won’t cover all of, being created in 2000 by Helix Code, which became Ximian, where it was used in projects such as an email client (Evolution).

While it has been maintained to some degree for all of this time it hasn’t had a lot of momementum behind it. The library has maintained its ABI for 13 years at this point with ad-hoc feature additions and fixes being often added on top. This has resulted in a library that has multiple APIs to accomplish the same task, confusing APIs that don’t follow any convention common within GNOME, and at times odd default behaviors that couldn’t be changed.

What’s Coming

We are finally breaking ABI and making a new libsoup 3.0 release. The goal is to make it a smaller, more simple, and focused library.

Making the library smaller meant deleting a lot of duplicated and deprecated APIs, removing rarely used features, leveraging additions to GLib in the past decades, and general code cleanup. As of today the current codebase is roughly at 45,000 lines of C code compared to 57,000 lines in the last release with over 20% of the project deleted.

Along with reducing the size of the library I wanted to improve the quality of the codebase. We now have improved CI which deploys documentation that has 100% coverage, reports code coverage for tests, tests against Clang’s sanitizers, and the beginnings of automated code fuzzing.

Lastly there is ongoing work to finally add HTTP/2 support improving responsiveness for the whole platform.

There will be follow up blog posts going more into the technical details of each of these.

Release Schedule

The plan is to release libsoup 3.0 with the GNOME 41 release in September. However we will be releasing a preview build with the GNOME 40 release for developers to start testing against and porting to. All feedback would be welcomed.

Igalia plans on helping the platform move to 3.0 and will port GStreamer, GVFS, WebKitGTK and may help with some applications so we can have a smooth transition.

For more details on WebKitGTK’s release plans there is a mailinglist thread over it.

The previous release libsoup 2.72 will continue to get bug fix releases for the forseable future but no new 2.7x releases will happen.

How to Help

You can build the current head of libsoup to test now.

Installing it does not conflict with version 2.x however GObject-Introspection based applications may accidentally import the wrong version (Python for example needs gi.require_version('Soup', '2.4') and GJS needs imports.gi.versions.Soup = "2.4"; for the old API) and you cannot load both versions in the same process.

A migration guide has been written to cover some of the common questions as well as improved documentation and guides in general.

All bug reports and API discussions are welcomed on the bug tracker.

You can also join the IRC channel for direct communication (be patient for timezones): ircs://irc.gimp.net/libsoup.

For this example I’ll be using Pithos which is an application I maintain.
It is an online radio player for Pandora.com.

These are the Flatpak permissions used for the application 2 years ago:

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

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

    "--talk-name=org.freedesktop.secrets",

    "--talk-name=org.freedesktop.Notifications",

    "--talk-name=org.gnome.SettingsDaemon",
    "--talk-name=org.mate.SettingsDaemon",

    "--talk-name=org.gnome.ScreenSaver",
    "--talk-name=org.cinnamon.ScreenSaver",
    "--talk-name=org.freedesktop.ScreenSaver",
    "--talk-name=com.canonical.Unity.Session",

    "--talk-name=org.kde.StatusNotifierWatcher",

    "--own-name=org.mpris.MediaPlayer2.pithos"
  ]

These are the possible* permissions today:

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

    "--talk-name=org.gnome.SettingsDaemon.MediaKeys",
    "--talk-name=org.mate.SettingsDaemon",

    "--talk-name=org.kde.StatusNotifierWatcher"

So lets go over each permission from the old manifest.

    "--share=ipc", "--share=network", "--socket=x11", "--socket=wayland", "--socket=pulseaudio"

These are simply required for the application to function. The application will always require network access and wayland access. We did replace x11 with fallback-x11 which means on Wayland X11 is blocked. Eventually (hopefully within a year?) pulseaudio will have a similar solution for pipewire which will be able to block things like being able to record audio.

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

As of GLib 2.60.6+ this permission is simply removed and settings are stored locally. This prevents applications from reading and writing settings for all software on the system.

    "--talk-name=org.freedesktop.secrets"

In an upcoming libsecret release this will also store secrets locally preventing the application from being able to read and write all stored secrets in the system keyring.

* This is not in a stable release yet.

    "--talk-name=org.freedesktop.Notifications"

A portal for notifications have been supported for a long time and the application simply uses the GNotification API and just works.

    "--talk-name=org.gnome.SettingsDaemon", "--talk-name=org.mate.SettingsDaemon"

These permissions are required for GNOME (and forks of GNOME like MATE) to bind media keys. Granting talk access to everything the settings daemon can do is not ideal and lets the application mess with system wide settings. Years ago gnome-settings-daemon improved this by splitting the features into their own namespaces so you only need to expose org.gnome.SettingsDaemon.MediaKeys which should be relatively safe to talk to. Hopefully this goes away entirely eventually with a host side solution using MPRIS.

    "--talk-name=org.gnome.ScreenSaver", "--talk-name=org.cinnamon.ScreenSaver", "--talk-name=org.freedesktop.ScreenSaver", "--talk-name=com.canonical.Unity.Session"

These were used to track the state of the screensaver to pause playback. This isn’t the most dangerous thing in the world but it does allow applications to activate the screensaver. GTK now supports the GtkApplication::screensaver-active property which lets an application monitor the state without having extra permissions.

    "--own-name=org.mpris.MediaPlayer2.pithos"

This was never a dangerous permission but as of Flatpak 1.0.4 you implicitly have permission to own org.mpris.MediaPlayer2.$app_id and subnames so that is now used for our name.

    "--talk-name=org.kde.StatusNotifierWatcher"

Lastly we do not have an alternative to this permission which still isn’t ideal and could be used to spoof other applications or exploit the host service which was likely never designed to handle untrusted data.

In conclusion there is certainly progress being made and this isn’t the only application slowly tightening permissions. There are of course still big holes where no alternative exists (most usage of --filesystem) but already today relatively secure but still well integrated flatpak’d applications can and do exist.

Lets start with some high level goals:

• Don’t use X11

  I’ll start with this because its simple and everybody knows it by now. If you want to set a tray you can’t use X11 because not everybody uses X11. So you need a different solution and on Linux that is a DBus service that applications talk to.

• Safely handle and expose if the tray works

  There are always going to situations where the tray will not work such as using a desktop that doesn’t support it or bugs like the service crashing and going away. This should always be reported to the application as soon as possible as this avoids issues like an application having a hide window feature but no tray to show it.

• Be designed for a sandboxed future

  We are now at a point where desktop software is getting sandboxed so that means certain actions are limited such as reading/writing files on the host, talking to or owning arbitrary DBus names, having a PID that means anything to the host, etc. On top of that applications should expect a permission system where they are denied using a tray.

• Recommended features

  This is more opinionated but I’d say you need to support:

  • Showing an icon and changing it (with scaling ideally)
  • Reacting to clicks and maybe scrolling
  • Exporting a menu to be shown

Ok I think that covers the basics lets look at the real world solutions:

- GtkStatusIcon (GTK)

• ❌ Uses X11
• ✔️ It does expose if the tray is “embedded” or not (almost nobody listens to this).
• ❌ Sandbox friendly (its X11)
• ✔️ Features

Nobody should use this API in new code if you want to target non-X11 but this is the classic API everybody has lived with for years and it got the job done. Since it no longer exists in GTK4 due to not being portable a replacement had to come.

- AppIndicator (Canonical)

• ✔️ Uses DBus (but falls back to X11)
• ❌ Failure not exposed by default
• ❓ It is kinda sandbox friendly
• ✔️ Features

While nobody should be using the DBus service anymore many use the libappindciator library which behind the scenes uses StatusNotifier these days. It has a complete feature-set for the most part though menu handling is overly complex.

There are quite a few problems with this implementation however. It is designed to silently fail by default; It falls back to X11 automatically and unless you override the fallback handling XEmbed failing yourself (maybe literally nobody does) you will not know it did. It does tell if you if the DBus portion is connected but as long as it fallsback you don’t know what is going on.

It isn’t quite sandbox friendly because it does require talking to an insecure service and it allows referencing icons by path. However it doesn’t require bus name ownership which is a positive.

Lastly the library is entirely unmaintained for many years and libdbusmenu is just disgusting, so its not something I’d recommend in new code.

- StatusNotifier (KDE)

• ✔️ Uses DBus
• ✔️ You can detect failure if you try
• ❌ Not sandbox friendly
• ✔️ Features

This is the de-facto standard at the moment that many people are using now. It has its positives and its negatives.

The biggest problem with this API is that it is clearly not designed with a sandbox in mind. Quoting the spec:

Each application can register an arbitrary number of Status Notifier Items by registering on the session bus the service org.kde.StatusNotifierItem-PID-ID, where PID is the process id of the application and ID is an arbitrary numeric unique identifier between different instances registered by the same application.

So this bad on a few levels. For one it requires name ownership in the KDE namespace which I personally do not understand why. Flatpak blocks all ownership except for your app-id. I’m not even sure a well-known name is required at all.

Secondly it requires putting your PID in the name which is a no-go for any PID namespace on Linux as they will almost always have the same values inside the sandbox.

Lastly it has the same issues AppIndicator exposed such as talking to an insecure service, referencing icons by path, etc. It also reuses the DBusMenu spec for exporting menus which is still completely awful and unmaintained.

I’d say it is the best solution we have but it needs improving.

- StatusIcon (Linux Mint)

• ✔️ Uses DBus (but falls back to X11)
• ❌ Failure not exposed
• ❌ Not sandbox friendly
• ❌ Features

So last comes Mint with a new interface which repeats the issues of the past.

Failure is not exposed at all so applications have no idea if it works.

It has all of the sandbox problems of StatusNotifier nearly copy paste. It requires name ownership, it uses your PID in said ownership, etc.

In the end it does not expose as many features as the previous solutions as you can only set an icon, label, and tooltip. I understand why to a degree for menus because libdbusmenu is seriously evil but they could have went a more minimal approach and reused GMenu in GLib which perfectly handles exporting a menu over DBus.

This announcement is clearly why I am writing this as I hope they will consider some of the sandboxing cases and better expose if a tray is working in the future. I just do not want to see past mistakes repeated and for adoption to happen before they are solved.

P.S. Don’t use the org.x namespace and don’t do blocking IO.

- What I want to see (or maybe create)

• Supports features mentioned above
• Backed by DBus service
  • This must be a robust service, validating the sent icon data in a sandbox
    • All icons must be sent as data or icon-names, no paths allowed
  • Not require well-known name ownership outside of app-id namespace
    • Uniqueness is up to the application already
  • Support more minimal menus than DBusMenu (via GMenu IMO, but anything similar)
  • Be exposed by xdg-desktop-portal which handles permissions
• Library that exposes if the tray is working or not
  • Also don’t fallback to XEmbed, at least not silently

Thankfully there is a hacky solution of using a custom EDID and this solution works on Wayland as well as Xorg (it should work with other drivers also). I was not actually the one to figure this out so shout out to parkerlreed on reddit. This post is just to make it more visible and I packaged the tool used to make this easier.

1. Find the edid file used by the connector: find /sys/devices/pci*/ -name edid
   • For convenience copy to home: cp /sys/devices/.../edid ~/edid.bin
2. Install wxEDID: flatpak install https://dl.tingping.se/flatpak/wxedid.flatpakref
3. Open the found file in wxEDID and edit it to disable YCbCr support:
   • SPF: Supported features -> change value of vsig_format to 0b00
   • CHD: CEA-861 header -> change the value of YCbCr420 and YCbCr444 to 0
   • VSD: Vendor Specific Data Block -> change the value of DC_Y444 to 0
4. Use the modified EDID file:
   1. Option -> Recalc Checksum
   2. File -> Save EDID Binary (to ~/modified_edid.bin for example)
   3. Copy to firmware directory: sudo install -Dm644 ~/modified_edid.bin /usr/lib/firmware/edid/modified_edid.bin
   4. Configure kernel to use it. For example on Fedora: sudo grubby --args='drm.edid_firmware=edid/modified_edid.bin' --update-kernel=DEFAULT
      • Note that this only changes the current kernel so you can boot into older kernels (or edit in the grub menu) if it fails and revert this with grubby --remove-args
5. Reboot

One of the main goals of LAS has been to be a place for multiple platforms to discuss the desktop space and not just be a GNOME event. This year two KDE members, @aleixpol and Albert Astals Cid, who spoke about release cycle of KDE Applications, Plasma, and the history of Qt. It is always interesting to see how another project solves the same problems and where there is overlap.

The elementary folks were there since this is @cassidyjames home turf who had a great “It’s Not Always Techincal” talk as well as a talk with @danrabbit about AppCenter which are both very important areas the GNOME Project needs to improve in. I also enjoyed meeting a few other community members such as @Philip-Scott and talk about their use of elementary’s platform.

Heather from Purism spoke about the Librem 5 status which I’m excited for but has a way to go. It was great to get an opportunity to meet her since we’ve spoken online about their interest in Flatpak and GNOME-Builder.

There were some fantastic talks discussing FOSS usage at a broader level:

• “FreeHive: An Open-Source Creative Agency” and “Developers, Developers, Developers—How About Creatives?” - Ryan Gorely
• “How Can You Make Your Open Source Project Attractive to Students?” - Heidi Ellis and Gregory Hislop
• “Research Science and Libre Computing” - Britt Yazel

As always there was a big Flatpak presense and throughout we had the opportunity to discuss things like adding Qt to fdo, tracking runtime CVEs, sandboxing WebKitGTK, etc. We also had a Flatpak BoF on the last day discussing things like possibilty of selling apps and infrastructure improvements.

I really enjoyed the event overall and look forward to future LASes. Next week I will be in A Coruña, Spain, for the webengine hackfest.

Just as a quick recap Flatpak does not use host libraries. This is required to be portable and reproducable on nearly any Linux distro. This even applies to very important libraries like libgl but this is rarely a problem as Mesa supports a wide range of hardware. The exception to this is properietary drivers which for desktop users means Nvidia. This isn’t necessarily a problem since we can just package more drivers but Nvidia’s userspace drivers must be the same version as the kernel driver which becomes a bit of a packaging nightmare because then we have to package every version that is in use.

The logical solution to this is for the Flatpak GL driver to come from the same place that your host GL driver did. Flatpak supports “unmanaged extensions” allowing loading extensions installed externally into /var/lib/flatpak/extension and $XDG_DATA_HOME/flatpak/extension. This does make my previous paragraph a lie but it places trust in the host to be responsable and understand how ABI works to keep things portable which we will get into later.

Before we get into packaging the Nvidia driver on the host for this lets look at how the GL driver extension point specifically works. This extension point is defined as such:

'Extension org.freedesktop.Platform.GL':
    versions: "18.08;1.4"
    version: "1.4"
    directory: "%{lib}/GL"
    subdirectories: "true"
    no-autodownload: "true"
    autodelete: "false"
    add-ld-path: "lib"
    merge-dirs: "vulkan/icd.d;glvnd/egl_vendor.d"
    download-if: "active-gl-driver"
    enable-if: "active-gl-driver"

I will point out the important parts of this later but I will just cover what active-gl-driver means really quick. The -if properties run custom checks within flatpak to know if an extension should be downloaded or enabled. This check specifically looks up your nvidia version from the kernel and maps that to a string e.g. nvidia-396-54. What your current version is can be checked with flatpak --gl-drivers where you will notice host and default are always inserted. This value can also be overriden with the env var FLATPAK_GL_DRIVERS.

So here is a real world example of me packaging this on Fedora: negativo17/nvidia-driver. The path it ends up installed into is: …/org.freedesktop.Platform.GL.host/x86_64/1.4. As you can see host is used here because it is always in the default driver list and thus will always get used first. The 1.4 version might also be confusing since the 1.4 runtime is ancient and nobody uses it. The reason this is used is because the Nvidia driver has no ABI requirements outside of libc basically and will run on every freedesktop runtime that exists so far. That guarentee does not exist for all drivers and must be used cautiously. The layout of files ends up being this because of merge-dirs and add-ld-path shown above:

├── glvnd
│   └── egl_vendor.d
│       └── 10_nvidia.json
├── lib
│   ├── libGLX_nvidia.so.396.54
│   └── All libs omitted for brevity…
├── OpenCL
│   └── vendors
│       └── nvidia.icd
└── vulkan
    └── icd.d
        └── nvidia_icd.json

That should cover all the details for host extensions but this extension point is also still very useful for normal flatpaked extensions. There is a MR for mesa-git that would end up being used by setting FLATPAK_GL_DRIVERS=mesa-git to try out newer versions.

If you are a distro packager I do believe it makes sense to start making a nvidia package for the Flatpak extension especially for beta versions. This should probably not be used to package host versions of Mesa though because they link to host libraries outside of libc. There is some work done to make this possible but most distro packages are not acceptable for this usage and there is rarely an upside as fdo 18.08 might even have newer Mesa versions than some distros and can get updates.