From 8341b7a5e4661657776a93c7572dfab30e201380 Mon Sep 17 00:00:00 2001 From: Mario Sanchez Prada Date: Wed, 8 Jul 2026 18:53:45 +0200 Subject: [PATCH 01/11] Update the WPE design diagram to match the new API --- assets/img/diagram-WPE-design.svg | 571 ++++++++++++++++++++++++------ 1 file changed, 468 insertions(+), 103 deletions(-) diff --git a/assets/img/diagram-WPE-design.svg b/assets/img/diagram-WPE-design.svg index 5b4bde790..d6029435b 100644 --- a/assets/img/diagram-WPE-design.svg +++ b/assets/img/diagram-WPE-design.svg @@ -1,103 +1,468 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - + + + + + + + + + + + + + + Application / Launcher + your embedded app, MiniBrowser, etc. + + + + + WPE WebKit + + + + WebKit engine and public API (WebKitWebView, JavaScriptCore, Web Platform) + + + WPEPlatform API + WPEDisplay · WPEView · WPEToplevel · WPEBuffer (rendering and input) + + BUILT-IN PLATFORM IMPLEMENTATIONS + + + + + + + Wayland + WPEDisplayWayland + + + DRM / KMS + WPEDisplayDRM + + + Headless + WPEDisplayHeadless + + + + + Custom implementation + optional, for other environments + your WPEDisplay subclass + + + + + + + + Wayland compositor + e.g. Weston + + Display via DRM / KMS + no compositor + + Offscreen output + testing and CI + + Your platform + custom integration + + Legacy deployments (pre-2.54) use libwpe with an external backend such as WPEBackend-fdo and the Cog launcher; that path is documented separately. + From d14ae535576daedfb5cf733e88e870b02a6c3fa8 Mon Sep 17 00:00:00 2001 From: Mario Sanchez Prada Date: Wed, 8 Jul 2026 18:56:30 +0200 Subject: [PATCH 02/11] Update content in /about/architecture.html --- about/architecture.md | 112 +++++++++++++++++++++++++++++------------- 1 file changed, 79 insertions(+), 33 deletions(-) diff --git a/about/architecture.md b/about/architecture.md index 9dc77cdc0..788671fb7 100644 --- a/about/architecture.md +++ b/about/architecture.md @@ -39,30 +39,35 @@ such as the traditional Cocoa, GTK, etc toolkits. ## Web page rendering -

WPE is considered a hybrid port because it defers the final web page delivery for display to a rendering backend. A traditional port would provide a widget for a given toolkit, but WPE opted for a different and more flexible approach.

- -The common interface between WPEWebKit and its rendering backends is provided by -[libwpe](https://github.com/WebPlatformForEmbedded/libwpe). On one side, once -WPEWebKit has a graphical representation of the final composited Web page ready -for rendering, it invokes a callback function on `libwpe`. On the other side, -the WPE application has to register a view backend on the WPE WebView. This view -backend is provided by the rendering backend. The view backend receives the Web -page representation from `libwpe`, usually as an EGLImage, and is in charge of -presenting it in the application, on-screen. - -The decoupling between generating the WebPage representation on WebKit side and -the actual rendering on the application side provides a very flexible design. -For instance, WPE integrators can easily develop a new rendering backend for -specific embedded platforms that might have a graphics driver with special API -requirements. - -WPE provides a rendering backend aiming to target the most common platforms and -leverage the existing graphics stack available in the -[Freedesktop](https://freedesktop.org) umbrella eco-system. -[WPEBackend-FDO](https://github.com/Igalia/WPEBackend-FDO) is the reference -implementation of the base rendering backend design. WPEBackend-FDO provides an API -for WPE applications that aims to ease the handling of rendering either -on-screen using EGL, or off-screen using SHM. +

WPE integrates with the target platform through the WPEPlatform +API, which ships as part of WPE WebKit itself. Because WPE provides no user-interface +toolkit widget, this layer is what turns the rendered web page into pixels on screen +and feeds input back to the engine.

+ +Since 2.54, WPEPlatform is the default integration layer, and the only one needed +for the common targets. A `WPEDisplay` represents the connection to the underlying +windowing system or output, and manages one or more `WPEView`s, each hosted in a +`WPEToplevel` (a top-level surface such as a window or a full-screen output). The +composited web page is handed over through `WPEBuffer`, using a system GPU buffer +(e.g. `WPEBufferDMABuf`, `WPEBufferAndroid`), or shared memory (i.e. `WPEBufferSHM`) +as a fallback. + +WPE WebKit includes several built-in platform implementations: + +- **Wayland** (`WPEDisplayWayland`): renders as a client of a Wayland compositor. +- **DRM/KMS** (`WPEDisplayDRM`): renders directly through the display controller, + with no compositor, for dedicated embedded outputs. +- **Headless** (`WPEDisplayHeadless`): renders off-screen, for testing and CI. + +The implementation can be selected at runtime through the `WPE_DISPLAY` environment +variable (`wpe-display-wayland`, `wpe-display-drm`, `wpe-display-headless`), or +chosen automatically with `wpe_display_get_default()`. None of these targets +require libwpe or a separate rendering backend. + +This design keeps WPE flexible without giving up that convenience: for special +environments not covered by the built-in implementations, an integrator can provide +a custom WPEPlatform implementation by subclassing `WPEDisplay` (and the related +view and toplevel types). @@ -72,16 +77,57 @@ on-screen using EGL, or off-screen using SHM.

In a traditional WebKit port, the provided widget usually also handles input (keyboard, mouse, touch) events and is in charge of relaying them to the -internal WebKit input-methods components.

+internal WebKit input handling components.

+ +As WPE doesn't provide a widget, input is handled by the active WPEPlatform +implementation. Each implementation gathers events from its environment (for +example, from the Wayland compositor, or directly from the input devices under +DRM/KMS) and delivers them to the target `WPEView`, which relays them to WebKit's +internal input handling components. This flexible design enables applications to + provide input events in any way that better suits them. + + + +
+ +## Legacy architecture (libwpe and WPE backends) + +

Before 2.54, WPE integrated with the platform through libwpe and a +separate, external rendering backend. This model is legacy as of 2.54: it is kept for +existing deployments and still built as needed, but new projects should use the +WPEPlatform API described above.

+ +
+How the legacy libwpe and WPE backend model works + +The common interface between WPE WebKit and its rendering backends was provided by +[libwpe](https://github.com/WebPlatformForEmbedded/libwpe). On one side, once WPE +WebKit had a graphical representation of the final composited web page ready for +rendering, it invoked a callback function on `libwpe`. On the other side, the WPE +application had to register a view backend on the WPE web view. This view backend +was provided by the rendering backend, received the web page representation from +`libwpe` (usually as an EGLImage), and was in charge of presenting it in the +application, on-screen. + +This decoupling between generating the web page representation on the WebKit side +and the actual rendering on the application side provided a flexible design. WPE +integrators could develop a new rendering backend for specific embedded platforms +whose graphics driver had special API requirements. + +WPE provided a rendering backend aiming to target the most common platforms and +leverage the existing graphics stack available in the +[Freedesktop](https://freedesktop.org) umbrella ecosystem. +[WPEBackend-FDO](https://github.com/Igalia/WPEBackend-FDO) is the reference +implementation of that base rendering backend design. WPEBackend-FDO provides an +API for WPE applications that eases the handling of rendering either on-screen +using EGL, or off-screen using SHM. -As WPE doesn't provide a widget, it relies on `libwpe` APIs to relay input -events from the WPE application to the internal WebKit input-methods components. -This design again adds flexibility to the overall WPE architecture, enabling -applications to support new input devices without having to go through a UI -toolkit first. +For input, because WPE provides no widget, this model relied on `libwpe` APIs to +relay input events from the WPE application to the internal WebKit input-method +components. In the example of the [Cog launcher](https://github.com/Igalia/cog), +the application relied on Wayland protocols to communicate input events coming from +the Wayland compositor to WPE. -In the example of the [Cog WPE browser](https://github.com/Igalia/cog), the -application relies on Wayland protocols for user input to communicate events -coming from the Wayland compositor to WPE. +
From 32f407c27d95b6ec16a8df46e3e4fafb9ff3a4d0 Mon Sep 17 00:00:00 2001 From: Mario Sanchez Prada Date: Wed, 8 Jul 2026 18:58:31 +0200 Subject: [PATCH 03/11] Update part of the content in /about/get-wpe.html We will leave changes in the release tarballs section for a later commit. --- about/get-wpe.md | 26 ++++++++++++++++++-------- 1 file changed, 18 insertions(+), 8 deletions(-) diff --git a/about/get-wpe.md b/about/get-wpe.md index 836336c21..4d935ad61 100644 --- a/about/get-wpe.md +++ b/about/get-wpe.md @@ -50,12 +50,19 @@ get your hands on WPE, depending on what you need. ### Before starting Before getting the code, it's a good idea to be familiar with what you -will need. The different components that are needed to run WPE are: +will need. Since 2.54, WPE WebKit bundles the WPEPlatform API, which provides +built-in Wayland, DRM/KMS, and headless integration, so the only component you +need to run WPE on the common targets is: -* [WebKit](https://webkit.org): as WPE is an official WebKit port, you will need the source code for the WebKit project. -* [libwpe](https://github.com/WebPlatformForEmbedded/libwpe): A general-purpose library for WPE, that enables integration between WebKit and different platforms, through backends. -* [WPEBackend-fdo](https://github.com/Igalia/WPEBackend-fdo): A reference FreeDesktop.org backend for WPE, that relies on different FreeDesktop.org projects and can serve as a starting point to either customize or create a completely new backend for specific configurations. -* [Cog](https://github.com/Igalia/cog): A simple and minimalistic browser using WPE, with no user interface, suitable to be used as a Web application container or as a starting point to develop more complex browser applications based on WPE. +* [WebKit](https://webkit.org): as WPE is an official WebKit port, you will need the source code for the WebKit project. WPE WebKit includes the WPEPlatform API, so it can drive Wayland, DRM/KMS, and headless output on its own. + +#### Optional and legacy components + +The following components are only needed for the legacy API (pre-2.54), or for existing deployments built on it. They are still released as needed, but new projects do not require them: + +* [libwpe](https://github.com/WebPlatformForEmbedded/libwpe): A general-purpose library for the legacy API, that enables integration between WebKit and different platforms, through external backends. +* [WPEBackend-fdo](https://github.com/Igalia/WPEBackend-fdo): A reference FreeDesktop.org backend for the legacy API, that relies on different FreeDesktop.org projects and can serve as a starting point to either customize or create a completely new backend for specific configurations. +* [Cog](https://github.com/Igalia/cog): A simple and minimalistic launcher built on the legacy API, with no user interface, suitable to be used as a Web application container. With WPEPlatform, a launcher is only a few lines of code, so Cog is no longer required for new projects. ## __Install it from your Linux distribution__ @@ -159,9 +166,12 @@ that is not yet available in WPE. Additionally, this can be also be a good way to track down any bug you might find and to fix it. * [WebKit](https://github.com/webKit/WebKit/) -* [libwpe](https://github.com/WebPlatformForEmbedded/libwpe). -* [WPEBackend-fdo](https://github.com/Igalia/WPEBackend-fdo). -* [Cog](https://github.com/Igalia/cog). + +The following repositories are only needed for the legacy API (pre-2.54) or existing deployments built on it: + +* [libwpe](https://github.com/WebPlatformForEmbedded/libwpe) (legacy). +* [WPEBackend-fdo](https://github.com/Igalia/WPEBackend-fdo) (legacy). +* [Cog](https://github.com/Igalia/cog) (legacy). Instead of downloading each of these components on their own, the recommended procedure is cloning Git repositories for WebKit and the [WebKit Container From 36e68bbc0a571d35c9dd0f45cc432b6a675be1c7 Mon Sep 17 00:00:00 2001 From: Mario Sanchez Prada Date: Wed, 8 Jul 2026 19:01:38 +0200 Subject: [PATCH 04/11] Update release tarballs section in /about/get-wpe.html --- about/get-wpe.md | 58 +++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 57 insertions(+), 1 deletion(-) diff --git a/about/get-wpe.md b/about/get-wpe.md index 4d935ad61..9d03e7933 100644 --- a/about/get-wpe.md +++ b/about/get-wpe.md @@ -109,12 +109,13 @@ and its components:

Releases

-
+

Stable

{%- for item in collections.latestReleases -%} + {%- if item[0] == "wpewebkit" -%}
{{ item[0] }}: @@ -127,6 +128,7 @@ and its components: href="{{ item[1].stable.url }}">Release notes for v{{ item[1].stable.version }}
+ {%- endif -%} {%- endfor -%}
@@ -135,6 +137,7 @@ and its components:

Unstable

{%- for item in collections.latestReleases -%} + {%- if item[0] == "wpewebkit" -%}
{{ item[0] }}: @@ -147,6 +150,7 @@ and its components: href="{{ item[1].unstable.url }}">Release notes for v{{ item[1].unstable.version }}
+ {%- endif -%} {%- endfor -%}
@@ -157,6 +161,58 @@ and its components:
+### Legacy components + +These components are tied to the legacy API (pre-2.54) and are provided for existing deployments. They are still released as needed. + +
+
+
+

Stable

+
+ {%- for item in collections.latestReleases -%} + {%- unless item[0] == "wpewebkit" -%} +
+ {{ item[0] }}: + + Download v{{ item[1].stable.version }} + - + Release notes for v{{ item[1].stable.version }} + +
+ {%- endunless -%} + {%- endfor -%} +
+
+ +
+

Unstable

+
+ {%- for item in collections.latestReleases -%} + {%- unless item[0] == "wpewebkit" -%} +
+ {{ item[0] }}: + + Download v{{ item[1].unstable.version }} + - + Release notes for v{{ item[1].unstable.version }} + +
+ {%- endunless -%} + {%- endfor -%} +
+
+
+
+ ## __Get the source code directly from git__ This is the most involved way to get the source code, and it's only From 9e0f931c910239635c152453d43ea624e7498210 Mon Sep 17 00:00:00 2001 From: Mario Sanchez Prada Date: Fri, 17 Jul 2026 19:14:28 +0200 Subject: [PATCH 05/11] Update content in /about/faq.html --- about/faq.md | 101 +++++++++++++++++++++++++++++---------------------- 1 file changed, 57 insertions(+), 44 deletions(-) diff --git a/about/faq.md b/about/faq.md index 7da69171f..b16d649fa 100644 --- a/about/faq.md +++ b/about/faq.md @@ -13,7 +13,7 @@ sitemapChangeFrequency: monthly WPE is an Open Source project developed upstream as part of [the WebKit project](https://webkit.org), with all its code being pushed to [WebKit's upstream repository](https://github.com/WebKit/WebKit). Therefore, **WPE is published under a mix of LGPLv2 and BSD licenses**, which are the ones applying to the WebKit project as a whole. You can [find a copy of such licenses in the webkit.org website](https://webkit.org/licensing-webkit). -There are also [three related components developed alongside with WPEWebKit](https://wpewebkit.org/release), which are externally maintained and have their own Open Source licenses: +There are also [three related components developed alongside WPE WebKit](https://wpewebkit.org/release), tied to the legacy API (pre-2.54) and kept for existing deployments. They are externally maintained and have their own Open Source licenses: * libwpe: [BSD-2-Clause license](https://github.com/WebPlatformForEmbedded/libwpe/blob/master/COPYING) (also known as _“Simplified BSD License”_). * WPEBackend-fdo: [BSD-2-Clause license](https://github.com/Igalia/WPEBackend-fdo/blob/master/COPYING). @@ -84,13 +84,13 @@ There is code in WebKit to support Encrypted Media Extensions (EME), but in any ## What is the WPEPlatform API? -WPEPlatform is the new platform integration layer inside WPE WebKit, which will replace the libwpe API in WPE WebKit 2.54. It handles rendering and input for the target environment: a `WPEDisplay` manages the `WPEView`s that display web content, buffers are exchanged through `WPEBuffer` (DMA-BUF or shared memory), and WPE WebKit provides built-in implementations for Wayland, DRM/KMS, and headless output. The right implementation is chosen at runtime through the `WPE_DISPLAY` environment variable, or automatically. +WPEPlatform is the platform integration layer that ships inside WPE WebKit. It handles rendering and input for the target environment: a `WPEDisplay` manages the `WPEView`s that display web content, buffers are exchanged through `WPEBuffer` (e.g. `WPEBufferDMABuf`, `WPEBufferAndroid`, shared memory), and WPE WebKit provides built-in implementations for Wayland, DRM/KMS, and headless output. The right implementation can be chosen at runtime through the `WPE_DISPLAY` environment variable, or automatically. -WPEPlatform is already available in WPE WebKit 2.52 and in the current unstable releases, but it is not part of the stable API yet, so for now it is optional and not built by default. It is expected to be enabled by default and become the recommended API with the upcoming 2.54 release. If you are starting a new project, we encourage you to try it out now instead of building on the libwpe API, that will soon become legacy. See the [WPEPlatform API reference](/reference/stable/wpe-platform-2.0/) for the details. +Since 2.54, WPEPlatform is the default and recommended API. See the [architecture page](/about/architecture.html) for the full picture, and the [WPEPlatform API reference](/reference/stable/wpe-platform-2.0/) for the details. ## How do I build a launcher with the WPEPlatform API? -This uses [the WPEPlatform API described above](#what-is-the-wpeplatform-api%3F), which you can already try today with WPE WebKit 2.52 or the unstable releases, as long as they are built with `-DENABLE_WPE_PLATFORM=ON` (not by default [except for "developer mode" builds](https://github.com/WebKit/WebKit/blob/6ea58a42a90953702692b60e2347b63075394968/Source/cmake/OptionsWPE.cmake#L106)). With WPEPlatform there is no separate launcher to install: writing one is only a few lines of code, because WPE WebKit provides the platform integration itself. A minimal launcher looks like this: +With WPEPlatform there is no separate launcher to install: writing one is only a few lines of code, because WPE WebKit provides the platform integration itself. A minimal launcher looks like this: ```cpp #include @@ -119,12 +119,14 @@ WPE_DISPLAY=wpe-display-headless ./my-launcher https://wpewebkit.org/ ## Do I still need libwpe and a WPE backend? -For now, by default, yes. Until the 2.54 release builds the WPEPlatform by default, any application built on top of WPE WebKit will use the current API, which relies on libwpe together with an external rendering backend such as WPEBackend-fdo. +No. For the common targets (Wayland, DRM/KMS, and headless), WPE WebKit provides everything through its built-in WPEPlatform implementations, so neither libwpe nor an external rendering backend is required. -If you explicitly opt into the WPEPlatform API (available since 2.52), you no longer need either of them: for the common targets (Wayland, DRM/KMS, and headless) WPE WebKit provides everything through its built-in WPEPlatform implementations. Since the current API is expected to become legacy once 2.54 makes WPEPlatform the default, we encourage new projects to adopt WPEPlatform now rather than build on an API that will soon be legacy. +libwpe, WPEBackend-fdo, and similar backends belong to the legacy API used before 2.54. They are kept for existing deployments and still built as needed, but new projects should target WPEPlatform. -## What is (and isn't) Cog? +## What is (and isn't) Cog? (legacy) + +Cog is the launcher built on the legacy API (pre-2.54). It is kept for existing deployments, but new projects do not need it: with WPEPlatform, [a launcher is only a few lines of code](#how-do-i-build-a-launcher-with-the-wpeplatform-api%3F). From [Cog's README](https://github.com/igalia/cog): @@ -137,74 +139,85 @@ Cog's usage scenarios span from a MiniBrowser application to a full web-app cont Although it can run on Linux-based desktop environments, Cog is not a full-blown Web Browser to be compared with Google Chrome or Safari. Cog's primary environment is on embedded platforms, and it can run within a Wayland compositor such as Weston. Additionally, if the platform supports KMS/DRM, Cog can run as a full-screen standalone browser, this use-case is very common on kiosk products for instance. -If you are a developer aiming to enable WPE on a certain embedded platform, Cog combined with WPEBackend-FDO provides the most flexible solution for agile tinkering and to test WPE's features. +For legacy deployments, Cog combined with WPEBackend-FDO provided a flexible solution for agile tinkering and for testing WPE's features. For new projects, prefer [writing a small launcher against the WPEPlatform API](#how-do-i-build-a-launcher-with-the-wpeplatform-api%3F) instead. ## Is Wayland required to run WPE? As we say in Galicia, "it depends". -[WPE's architecture](/about/architecture.html) was designed in order to -decouple rendering out of the Web engine and delegate this task to rendering -backends and to the application running the Web engine—it does not strictly -*require* usage of Wayland. +Since 2.54, WPE WebKit integrates with the target platform through its built-in +WPEPlatform implementations, and Wayland is just one of several supported outputs: + +* **Wayland** (`WPEDisplayWayland`) renders as a client of a Wayland compositor, so + a compositor (such as Weston) is required. +* **DRM/KMS** (`WPEDisplayDRM`) renders web content directly on screen through the + display controller, with no compositor at all. This is very common on kiosk and + appliance products. +* **Headless** (`WPEDisplayHeadless`) produces no on-screen output, and is meant for + testing and CI. + +The implementation can be chosen at runtime with the `WPE_DISPLAY` environment +variable, or by manually creating a `WPEDisplay`, so Wayland is required only if +you select the Wayland output. -Typically when talking about Wayland we tend to conflate many things: +It also helps to remember that "Wayland" tends to conflate several things: * Wayland *itself* is an IPC - **protocol** which happens to be designed to move buffers containing pixel - data and input events from one process to another. + **protocol**, designed to move buffers containing pixel data and input events from + one process to another. -* The Wayland *package* typically contains the **reference implementation** - of the protocol, `libwayland`. Other implementations are theoretically - possible. +* The Wayland *package* typically contains the **reference implementation** of the + protocol, `libwayland`. Other implementations are theoretically possible. -* By extension we may refer to **a compositor**, which is a program that - implements the server–side of the Wayland - protocol—possibly with the aid of `libwayland`. +* By extension we may refer to **a compositor**, a program that implements the server + side of the Wayland protocol, possibly with the aid of `libwayland`. -If you use [WPEBackend-fdo][fdo-backend], it internally uses the Wayland +
+Legacy note: Wayland and the pre-2.54 backends + +With the legacy API, [WPEBackend-fdo][fdo-backend] internally used the Wayland *protocol* (via `libwayland`) to pass rendered frames from the `WPEWebProcess` -program to the application that embeds the web view—that we call “the UI -process”. As this is an implementation detail of the backend, the fact that -Wayland is used as IPC protocol does not need to be known by the application. -A *compositor* may be required or not depending on how the UI process displays -the web content. - -For example, [Cog][cog-github] can act as a Wayland *client* using its FDO platform plug-in, and in that case a -Wayland *compositor* is required. On the other hand, using Cog's DRM platform plug-in it will display -rendered web content directly on screen (without a running Wayland -*compositor*). Note that in both cases WPEBackend-fdo is used as backend, -which means that the Wayland *protocol* is still in use. - -Some WPE backends may not require Wayland at all. Such is the case -of [WPEBackend-rdk][rdk-backend] in some configurations -(`USE_BACKEND_BCM_RPI`, `USE_BACKEND_BCM_NEXUS`, etc.) +program to the application that embedded the web view (the "UI process"). As that +was an implementation detail of the backend, the application did not need to know the +Wayland protocol was involved. A *compositor* might or might not be required, +depending on how the UI process displayed the web content. + +For example, [Cog][cog-github] could act as a Wayland *client* through its FDO platform plug-in, in which case a Wayland +*compositor* was required. Using Cog's DRM +platform plug-in, it displayed rendered web content directly on screen, without a +running Wayland *compositor*. In both cases WPEBackend-fdo was used as the backend, so +the Wayland *protocol* was still in use. Some WPE backends did not require Wayland at +all, such as [WPEBackend-rdk][rdk-backend] in some configurations +(`USE_BACKEND_BCM_RPI`, `USE_BACKEND_BCM_NEXUS`, etc.). [cog-github]: https://github.com/Igalia/cog [fdo-backend]: https://github.com/Igalia/WPEBackend-fdo [rdk-backend]: https://github.com/WebPlatformForEmbedded/WPEBackend-rdk +
+ ## Are open dialogs/popups menus supported? -The application embedding WPE is responsible for rendering popups and dialogs. The reference WPE Browser, Cog, has limited support for these features (as of 2021, it supports option menus). +The application embedding WPE is responsible for rendering popups and dialogs. For instance, the legacy launcher Cog has limited support for these features (e.g. Cog supported option menus as of 2021). + +## What is the wayland-protocols build dependency about in Cog (legacy)? -## What is the wayland-protocols build dependency about in Cog? +*This applies to the legacy Cog launcher and its FDO/Wayland plug-in.* Depending on which platform rendering plugin is enabled at build time, the Cog browser might depend on the [wayland-protocols](https://github.com/wayland-project/wayland-protocols) project to generate source files needed in order to act as a Wayland client to the compositor (server) implementing those protocols. So for instance, if you enable the [FDO platform plugin](https://github.com/Igalia/cog/blob/master/CMakeLists.txt#L57) and want to use it at runtime to have Cog running as a Wayland application, then the plugin will try to consume some Wayland protocols from the server, such as `xdg-shell`, `fullscreen-shell-unstable-v1`, `presentation-time` and `linux-dmabuf-unstable-v1`. Those protocols can't be used without first generating source files derived from each protocol XML spec definition. This is all part of the Wayland design. -## Why does the browser/launcher (e.g. Cog) crash at startup? +## Why does the launcher crash at startup? If you are building an embedded system image yourself, make sure there is at least one font installed that can be used as fallback by [Fontconfig](https://www.freedesktop.org/wiki/Software/fontconfig/). You can use the `fc-list` program to print the list of known fonts. -## Why does the browser/launcher (e.g. Cog) crash when trying to play audio? +## Why does the launcher crash when trying to play audio? If you are building an embedded system image yourself, make sure that the GStreamer elements `autoaudiosink` and `alsasink` are installed. Even if your @@ -213,7 +226,7 @@ ALSA is always tried as the last fallback if all the other available sinks fail. -## Why does the browser/launcher (e.g. Cog) not load local files? +## Why does the launcher not load local files? If you are building an embedded system image yourself, make sure to install the [shared MIME database][shared-mime-db] is installed—in most distributions From 062aa2161551369c3a226a633874a374f36ccf5c Mon Sep 17 00:00:00 2001 From: Mario Sanchez Prada Date: Fri, 17 Jul 2026 19:20:54 +0200 Subject: [PATCH 06/11] Update content in /developers --- developers/index.md | 10 +++------- 1 file changed, 3 insertions(+), 7 deletions(-) diff --git a/developers/index.md b/developers/index.md index b6c2cbe12..010192454 100644 --- a/developers/index.md +++ b/developers/index.md @@ -37,16 +37,12 @@ API documentation for the **latest stable release** is available here: - -API documentation for the **[new WPEPlatform API](/about/faq.html#what-is-the-wpeplatform-api%3F)** (under development): - API documentation for **deprecated APIs**: @@ -89,7 +85,7 @@ WPE WebKit and [WebKitGTK](https://webkitgtk.org/) share a fair amount of code.

WPE Design

-

WPE is the official port of the WebKit Web rendering engine for Linux-based embedded platforms. WPE is uniquely designed for embedded systems in that it doesn’t depend on any user-interface toolkits such as the traditional Cocoa, GTK, etc toolkits.

+

WPE is the official port of the WebKit Web rendering engine for Linux-based embedded platforms. WPE is uniquely designed for embedded systems in that it doesn’t depend on any user-interface toolkits such as the traditional Cocoa, GTK, etc toolkits. Since 2.54, its built-in WPEPlatform API provides Wayland, DRM/KMS, and headless integration out of the box.

From dcd0961c48f79a4404b8109cf3b26d2ce4a9b0f9 Mon Sep 17 00:00:00 2001 From: Mario Sanchez Prada Date: Wed, 8 Jul 2026 19:55:28 +0200 Subject: [PATCH 07/11] Update content in /about/supported-hardware.html --- about/supported-hardware.md | 66 +++++++++++++++++++------------------ 1 file changed, 34 insertions(+), 32 deletions(-) diff --git a/about/supported-hardware.md b/about/supported-hardware.md index 762858216..8ffc0bc4b 100644 --- a/about/supported-hardware.md +++ b/about/supported-hardware.md @@ -97,60 +97,62 @@ WPE is currently running on a wide range of hardware. This page lists configurat
-Note that this list is not exhaustive. Reports of unlisted configurations are welcome. +**Note**: Since 2.54, WPE WebKit provides Wayland, DRM/KMS, and headless output directly through [the built-in WPEPlatform implementations](/about/faq.html#what-is-the-wpeplatform-api%3F), which run on standard Mesa-based graphics stacks without libwpe or an external backend. The tables below record validated configurations in pre-2.54 releases, where the **Legacy backend** and **Legacy Cog platforms** columns describe the pre-2.54 stack, and are kept for reference. + +This list is not exhaustive. Reports of unlisted configurations are welcome. ## NXP -| Series | GPU | Driver | WPE Backend | Cog Platforms | -|---------|----------------|-------------|-------------|---------------| -| i.MX 51 | Imageon Z460 | freedreno (reverse-engineered) | fdo | wl, drm | -| i.MX 53 | Imageon Z460 | freedreno (reverse-engineered) | fdo | wl, drm | -| i.MX 6 | Vivante GC880 | Vivante (Proprietary) | fdo | wl, drm | -| i.MX 6 | Vivante GC2000 | etnaviv (reverse-engineered) | fdo | wl, drm | -| i.MX 6 | Vivante GC2000 | Vivante (Proprietary) | fdo | wl | -| i.MX 6 | Vivante GC2000 | Vivante (Proprietary) | rdk, `VIV_IMX6_EGL` | n/a | -| i.MX 8M | Vivante GC7000 | etnaviv (reverse-engineered) | fdo | wl, drm | -| i.MX 8M | Vivante GC7000 | Vivante (Proprietary) | fdo | wl | +| Series | GPU | Driver | Legacy backend | Legacy Cog platforms | +|----------------|----------------|--------------------------------|---------------------|----------------------| +| i.MX 51 | Imageon Z460 | freedreno (reverse-engineered) | fdo | wl, drm | +| i.MX 53 | Imageon Z460 | freedreno (reverse-engineered) | fdo | wl, drm | +| i.MX 6 | Vivante GC880 | Vivante (Proprietary) | fdo | wl, drm | +| i.MX 6 | Vivante GC2000 | etnaviv (reverse-engineered) | fdo | wl, drm | +| i.MX 6 | Vivante GC2000 | Vivante (Proprietary) | fdo | wl | +| i.MX 6 | Vivante GC2000 | Vivante (Proprietary) | rdk, `VIV_IMX6_EGL` | n/a | +| i.MX 8M | Vivante GC7000 | etnaviv (reverse-engineered) | fdo | wl, drm | +| i.MX 8M | Vivante GC7000 | Vivante (Proprietary) | fdo | wl | ## Broadcom -| Device | GPU | Driver | WPE Backend | Cog Platforms | -|----------------|-----|--------|-------------|---------------| -| Arris VIP5202W | VideoCore IV | Proprietary | rdk, `BCM_NEXUS` or `USE_BACKEND_BCM_NEXUS_WAYLAND` | n/a | -| Raspberry Pi 3 | VideoCore IV | Proprietary | rdk, `BCM_RPI` | n/a | -| Raspberry Pi 3 | VideoCore IV | Mesa vc4 | fdo | wl, drm, headless | -| Raspberry Pi 4 | VideoCore V | Mesa v3d | fdo | wl | +| Device | GPU | Driver | Legacy backend | Legacy Cog platforms | +|----------------|--------------|-------------|-----------------------------------------------------|----------------------| +| Arris VIP5202W | VideoCore IV | Proprietary | rdk, `BCM_NEXUS` or `USE_BACKEND_BCM_NEXUS_WAYLAND` | n/a | +| Raspberry Pi 3 | VideoCore IV | Proprietary | rdk, `BCM_RPI` | n/a | +| Raspberry Pi 3 | VideoCore IV | Mesa vc4 | fdo | wl, drm, headless | +| Raspberry Pi 4 | VideoCore V | Mesa v3d | fdo | wl | ## Qualcomm -| Device | GPU | Driver | WPE Backend | Cog Platforms | -|---------|-----|--------|-------------|---------------| -| APQ8017 | Adreno 306 | Proprietary | Custom | n/a | +| Device | GPU | Driver | Legacy backend | Legacy Cog platforms | +|---------|------------|-------------|----------------|----------------------| +| APQ8017 | Adreno 306 | Proprietary | Custom | n/a | ## RockChip -| Device | GPU | Driver | WPE Backend | Cog Platforms | -|--------|--------------|--------|-------------|---------------| -| RK3399 | Mali T860MP4 | panfrost (reverse-engineered) | fdo | wl | -| RK3399 | Mali T860MP4 | Mali (Proprietary) | | | +| Device | GPU | Driver | Legacy backend | Legacy Cog platforms | +|--------|--------------|-------------------------------|----------------|----------------------| +| RK3399 | Mali T860MP4 | panfrost (reverse-engineered) | fdo | wl | +| RK3399 | Mali T860MP4 | Mali (Proprietary) | | | ## PC-style Hardware -| Device | GPU | Driver | WPE Backend | Cog Platforms | -|--------|-----|--------|-------------|------------------------| -| Any | AMD | Mesa amdgpu | fdo | wl, x11, gtk4, headless | -| Any | Intel | Mesa i965 | fdo | wl, x11, gtk4, headless, drm | -| Any | Intel | Mesa iris | fdo | wl, x11, gtk4, headless, drm | +| Device | GPU | Driver | Legacy backend | Legacy Cog platforms | +|--------|-------|-------------|----------------|------------------------------| +| Any | AMD | Mesa amdgpu | fdo | wl, x11, gtk4, headless | +| Any | Intel | Mesa i965 | fdo | wl, x11, gtk4, headless, drm | +| Any | Intel | Mesa iris | fdo | wl, x11, gtk4, headless, drm | ## Other -| Device | GPU | Driver | WPE Backend | Cog Platforms | -|--------|-----|--------|-------------|---------------| -| Beaglebone | PowerVR SGX530 | Proprietary | | | +| Device | GPU | Driver | Legacy backend | Legacy Cog platforms | +|------------|----------------|-------------|----------------|----------------------| +| Beaglebone | PowerVR SGX530 | Proprietary | | |
From 1f05d6406427669d3c60a2386446c91929b6dc51 Mon Sep 17 00:00:00 2001 From: Mario Sanchez Prada Date: Wed, 8 Jul 2026 20:02:50 +0200 Subject: [PATCH 08/11] Update content in /release --- release.md | 54 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 54 insertions(+) diff --git a/release.md b/release.md index c4c9f57d1..89f347fbc 100644 --- a/release.md +++ b/release.md @@ -15,6 +15,7 @@ sitemapPriority: 0.7
{%- for pkg in collections.pkgCatalog -%} + {%- if pkg[0] == "wpewebkit" -%}

{{ pkg[0] }}

{%- assign package = pkg[1] -%} @@ -43,6 +44,44 @@ sitemapPriority: 0.7
+ {%- endif -%} + {%- endfor -%} + +
+

Legacy components

+

These components are tied to the legacy API (pre-2.54) and are provided for existing deployments. They are still released as needed.

+
+ + {%- assign legacyOrder = "cog,libwpe,wpebackend-fdo" | split: "," -%} + {%- for key in legacyOrder -%} + {%- assign package = collections.pkgCatalog[key] -%} + {%- endfor -%}
@@ -148,4 +187,19 @@ sitemapPriority: 0.7 font-style: italic; font-weight: 400; } +.legacy-components { + width: 100%; + margin-top: 1.5em; +} +.legacy-components h2 { + font-size: 1.6em; + margin: 0 0 0.25em; + padding-bottom: 0.15em; + border-bottom: 2px solid #1593ED; +} +.legacy-components p { + margin: 0 0 1em; + font-style: italic; + color: #555; +} \ No newline at end of file From 729debf15b8c7e9732fecf480878338d060bad6a Mon Sep 17 00:00:00 2001 From: Mario Sanchez Prada Date: Wed, 8 Jul 2026 20:16:40 +0200 Subject: [PATCH 09/11] Update content in /release/schedule --- release/schedule/index.md | 13 ++++++++----- 1 file changed, 8 insertions(+), 5 deletions(-) diff --git a/release/schedule/index.md b/release/schedule/index.md index 055eb1739..ca8bf420c 100644 --- a/release/schedule/index.md +++ b/release/schedule/index.md @@ -48,12 +48,15 @@ version number stays the same: well, because we actively avoid breaking it unless strictly needed. -## Compatible Components +## Compatible Components (legacy API) + +**Since 2.54**, WPE WebKit has a [new WPEPlatform API](/about/faq.html#what-is-the-wpeplatform-api%3F), +and [libwpe and an external rendering backend are no longer required](/about/faq.html#do-i-still-need-libwpe-and-a-wpe-backend%3F). +Therefore, the table below is only relevant to *legacy-API* deployments, summarizing +which *stable* releases of libwpe, WPE WebKit, WPEBackend-fdo, and Cog are compatible +and tested with each other (updated March 2026). Distributors and packagers targeting +the legacy API are strongly advised to use the versions listed here. -The following table summarizes which *stable* releases of libwpe, WPE WebKit, -WPEBackend-fdo, and Cog are compatible and tested with each other (updated -March 2026). Distributors and packagers are strongly advised to use the -versions listed below. | **WPE WebKit** | **libwpe** | **WPEBackend-fdo** | **Cog** | |:--------------:|:------------:|:------------------:|:------------:| From d9230b04d6e507a824972a4a0c40fe7951294ff7 Mon Sep 17 00:00:00 2001 From: Mario Sanchez Prada Date: Wed, 8 Jul 2026 20:22:37 +0200 Subject: [PATCH 10/11] Update content in /about/what-is-embedded.html --- about/what-is-embedded.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/about/what-is-embedded.md b/about/what-is-embedded.md index 543fdc0e2..42b9b2941 100644 --- a/about/what-is-embedded.md +++ b/about/what-is-embedded.md @@ -40,6 +40,6 @@ A "proper" _browser_ is, in all likelihood, the application in which you are rea In terms of WebKit-based browsers, a "port" is the set of extra layers that provides facilities at those top and bottom layers of the engine. The WebKit project has a few "official" ports that are available from [webkit.org/downloads/](https://webkit.org/downloads/). Some, like Safari, are fully-featured desktop browsers. WebKitGTK is a port for the GTK GUI toolkit, used among others by the desktop browser Epiphany. -WPE ("Web Platform for Embedded") is the official port for embedded systems, and it adds another layer to the architecture allowing for more easily swappable _backends_ (the graphics layers, windowing and so on) and simpler bindings for programmatic top-level control in Linux based systems. Cog is another project that makes it easier to launch and drive WPE views. +WPE ("Web Platform for Embedded") is the official port for embedded systems. It includes its own platform integration layer, the [WPEPlatform API](/about/faq.html#what-is-the-wpeplatform-api%3F), which drives the graphics and windowing output (Wayland, DRM/KMS, or headless) directly, and can be extended to other environments. WPE views are loaded and driven by custom WPE launcher applications, [which are very easy to write](/about/faq.html#how-do-i-build-a-launcher-with-the-wpeplatform-api%3F). In other words, WPE is designed to be _built_ and optimized for your embedded device in order to deliver the best performance. What all of this means is that there isn't really a single "WPE" that’s as easy to provide as many browsers that you're probably familiar with. From f2240c08b6bb11bc5097ebccb79587f9cf2a3d49 Mon Sep 17 00:00:00 2001 From: Mario Sanchez Prada Date: Wed, 8 Jul 2026 20:23:54 +0200 Subject: [PATCH 11/11] Update content in /about/builds.html --- about/builds.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/about/builds.md b/about/builds.md index aab1d9c8d..c09dc3c77 100644 --- a/about/builds.md +++ b/about/builds.md @@ -8,6 +8,6 @@ sitemapChangeFrequency: yearly skipHtmlSitemap: true --- -While there are several [simple ways for developers to experiment with and explore WPE](/about/exploring.html), none are tuned for performance. Generally, shipping products for embedded systems are performance-tuned custom builds. To make this easier, there is also [meta-webkit](https://github.com/Igalia/meta-webkit), which provides build recipes, WebKit based runtimes, and browsers for use with OpenEmbedded and/or Yocto. +While there are several [simple ways for developers to experiment with and explore WPE](/about/get-wpe.html), none are tuned for performance. Generally, shipping products for embedded systems are performance-tuned custom builds. To make this easier, there is also [meta-webkit](https://github.com/Igalia/meta-webkit), which provides build recipes, WebKit based runtimes, and browsers for use with OpenEmbedded and/or Yocto. We also have some [performance tips](https://github.com/Igalia/meta-webkit/wiki/PerformanceTips) that might be helpful.