canonical · Saviq · Oct 15, 2024 · Oct 10, 2024 · Oct 11, 2024 · Oct 10, 2024
@@ -12,3 +12,4 @@ jobs:
     uses: canonical/documentation-workflows/.github/workflows/documentation-checks.yaml@main
     with:
       working-directory: doc/sphinx
+      linkcheck-target: ${{ github.event_name == 'workflow_dispatch' && 'linkcheck' || 'noop-target' }}
@@ -6,21 +6,27 @@ appications
 AUR
 backend
 backends
+barebones
 behavior
 Binutils
 Broadcom
 buf
 cgroup
 ci
 classDiagram
+cmake
 CMake
 codebase
 Codecov
 CompositorAuthor
+config
 coreXX
 CRTC
+csd
+CSD
 Ctrl
 customize
+customization
 debian
 deps
 devel
@@ -45,6 +51,7 @@ EGMDE
 EndToEnd
 etnaviv
 Etnaviv
+eyecandy
 favorite
 filesystem
 flavors
@@ -81,6 +88,7 @@ ish
 jenkins
 KDE's
 KDE’s
+keybinds
 KHR
 Khronos
 kms
@@ -99,9 +107,13 @@ lttng
 LTTng
 LWN
 maintainer's
+maximize
+minimizing
 maximized
+maximizing
 Miaspects
 minimalistic
+minimize
 mir
 miral
 MirAL
@@ -118,6 +130,8 @@ mirwayland
 mmal
 Multiarch
 MX
+natively
+Natively
 nouveau
 nvidia
 Nvidia's
@@ -130,6 +144,7 @@ organized
 paltform
 ppa
 PPAs
+prebuilt
 preload
 preselects
 prober
@@ -157,6 +172,8 @@ snapcraft
 snapd
 SONAME
 SpinnerSplash
+ssd
+SSD
 subgraph
 subprocess
 sys
@@ -174,6 +191,7 @@ UBports
 ubuntu
 udev
 UndefinedBehaviourSanitizer
+usecase
 userland
 userspace
 UST

@@ -78,7 +78,7 @@ def DeduplicateExtensions(extensionNames: [str]):
     requirements = [
         "furo",
         "pyspelling",
-        "sphinx",
+        "sphinx==8.0.0",
         "sphinx-autobuild",
         "sphinx-copybutton",
         "sphinx-design",

@@ -35,7 +35,7 @@ HTMLINDEX     = $(WORKSPHINX)/_build/index.html
 endif
 
 .PHONY: help full-help woke-install pa11y-install install run html epub serve \
-        clean clean-doc spelling linkcheck woke pa11y Makefile
+        clean clean-doc spelling linkcheck woke pa11y Makefile noop-target
 
 # Put it first so that "make" without argument is like "make help".
 help:
@@ -122,7 +122,7 @@ clean-doc:
 spelling: html
 	. $(VENV) ; cd $(WORKSPHINX); python3 -m pyspelling -c $(SPHINXDIR)/spellingcheck.yaml -j $(shell nproc)
 
-linkcheck: install
+linkcheck: install configure
 	. $(VENV) ; cd $(WORKSPHINX); $(SPHINXBUILD) -b linkcheck "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS)
 
 # No need to go to $(WORKSPHINX) since it works on raw source files
@@ -133,6 +133,8 @@ woke: woke-install
 pa11y: pa11y-install html
 	$(PA11Y) $(shell find $(WORKSPHINX)/_build -name *.html -not -path '$(WORKSPHINX)/_build/api/*');
 
+noop-target:
+
 # Catch-all target: route all unknown targets to Sphinx using the new
 # "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
 %: Makefile

@@ -18,7 +18,7 @@ The most widely used and tested platform is “mesa-kms” which works with the
 
 Platform|Status|Description
 --|--|--
-gbm-kms|Released|Works with any driver providing KMS, `libgbm` and an EGL supporting [EGL_WL_bind_wayland_display](https://www.khronos.org/registry/EGL/extensions/WL/EGL_WL_bind_wayland_display.txt). The open-source Mesa drivers are the obvious example, but other drivers supporting these interfaces should work - for example, the binary MALI drivers provided by ARM have been tested on some devices.
+gbm-kms|Released|Works with any driver providing KMS, `libgbm` and an EGL supporting [EGL_WL_bind_wayland_display](https://registry.khronos.org/EGL/extensions/WL/EGL_WL_bind_wayland_display.txt). The open-source Mesa drivers are the obvious example, but other drivers supporting these interfaces should work - for example, the binary MALI drivers provided by ARM have been tested on some devices.
 x11|Released|Provides “Mir-on-X11” primarily for development.
 eglstream-kms|Released|Works with proprietary Nvidia drivers.
 wayland|Released|Provides “Mir-on-Wayland” both for nested compositors and for development.
@@ -68,18 +68,18 @@ Mesa open-source graphics stack|Proprietary driver
 --|--
 Etnaviv - Full open-source stack, using standard KMS/dma-buf/gbm interfaces. Reverse-engineered.|Vivante - proprietary driver.
 Same comments as etnaviv on i.MX6 apply, but the GPU is newer and the driver support is likewise newer; there may be more missing features/bugs than i.MX6 support.|same comments as i.MX6. <br/>_It’s likely that a Mir vivante platform would work on both i.MX6 and i.MX8; likewise, there is apparently Weston support (again, in the form of out-of-tree patches)_
-Looks like there might not be open-source video decode support (cf: https://community.nxp.com/thread/489829#comment-1160206). Unknown whether we could interface the IMX bits with the etnaviv DRM bits.|Proprietary video decode solution.
+Looks like there might not be open-source video decode support (https://community.nxp.com/t5/i-MX-Processors/i-MX8-Linux-video-decode-support/m-p/796955/highlight/true#M123321). Unknown whether we could interface the IMX bits with the etnaviv DRM bits.|Proprietary video decode solution.
 
 ## Driver requirements
 
 Different Mir platforms require different features of the underlying driver stack. The features needed to enable a given Mir platform are:
 
 ### gbm-kms
 
-The gbm-kms platform requires a DRM device node with KMS support, a `libgbm` implementation for buffer allocation, and an EGL implementation supporting at least [EGL_KHR_platform_gbm](https://www.khronos.org/registry/EGL/extensions/KHR/EGL_KHR_platform_gbm.txt) (or the equivalent [EGL_MESA_platform_gbm](https://www.khronos.org/registry/EGL/extensions/MESA/EGL_MESA_platform_gbm.txt) extension) and [EGL_WL_bind_wayland_display](https://www.khronos.org/registry/EGL/extensions/WL/EGL_WL_bind_wayland_display.txt).
+The gbm-kms platform requires a DRM device node with KMS support, a `libgbm` implementation for buffer allocation, and an EGL implementation supporting at least [EGL_KHR_platform_gbm](https://registry.khronos.org/EGL/extensions/KHR/EGL_KHR_platform_gbm.txt) (or the equivalent [EGL_MESA_platform_gbm](https://registry.khronos.org/EGL/extensions/MESA/EGL_MESA_platform_gbm.txt) extension) and [EGL_WL_bind_wayland_display](https://registry.khronos.org/EGL/extensions/WL/EGL_WL_bind_wayland_display.txt).
 
-Optionally, the EGL implementation can support [EGL_EXT_image_dma_buf_import](https://www.khronos.org/registry/EGL/extensions/EXT/EGL_EXT_image_dma_buf_import.txt), [EGL_EXT_image_dma_buf_import_modifiers](https://www.khronos.org/registry/EGL/extensions/EXT/EGL_EXT_image_dma_buf_import_modifiers.txt), and use the [zwp_linux_dmabuf_unstable_v1](https://gitlab.freedesktop.org/wayland/wayland-protocols/-/blob/master/unstable/linux-dmabuf/linux-dmabuf-unstable-v1.xml) Wayland protocol for client buffer transfer. Support for this was added in Mir 2.3. Composite-bypass support depends on this implementation. Some future performance improvements, such as overlay plane usage, are likely to require this support from the driver stack.
+Optionally, the EGL implementation can support [EGL_EXT_image_dma_buf_import](https://registry.khronos.org/EGL/extensions/EXT/EGL_EXT_image_dma_buf_import.txt), [EGL_EXT_image_dma_buf_import_modifiers](https://registry.khronos.org/EGL/extensions/EXT/EGL_EXT_image_dma_buf_import_modifiers.txt), and use the [zwp_linux_dmabuf_unstable_v1](https://gitlab.freedesktop.org/wayland/wayland-protocols/-/blob/master/unstable/linux-dmabuf/linux-dmabuf-unstable-v1.xml) Wayland protocol for client buffer transfer. Support for this was added in Mir 2.3. Composite-bypass support depends on this implementation. Some future performance improvements, such as overlay plane usage, are likely to require this support from the driver stack.
 
 ### eglstream-kms
 
-The eglstream-kms platform requires a DRM device node with Atomic KMS support and an EGL implementation supporting [EGL_EXT_platform_base](https://www.khronos.org/registry/EGL/extensions/EXT/EGL_EXT_platform_base.txt), [EGL_EXT_platform_device](https://www.khronos.org/registry/EGL/extensions/EXT/EGL_EXT_platform_device.txt), [EGL_EXT_device_base](https://www.khronos.org/registry/EGL/extensions/EXT/EGL_EXT_device_base.txt), [EGL_EXT_device_drm](https://www.khronos.org/registry/EGL/extensions/EXT/EGL_EXT_device_drm.txt), and [EGL_EXT_output_base](https://www.khronos.org/registry/EGL/extensions/EXT/EGL_EXT_output_base.txt).
+The eglstream-kms platform requires a DRM device node with Atomic KMS support and an EGL implementation supporting [EGL_EXT_platform_base](https://registry.khronos.org/EGL/extensions/EXT/EGL_EXT_platform_base.txt), [EGL_EXT_platform_device](https://registry.khronos.org/EGL/extensions/EXT/EGL_EXT_platform_device.txt), [EGL_EXT_device_base](https://registry.khronos.org/EGL/extensions/EXT/EGL_EXT_device_base.txt), [EGL_EXT_device_drm](https://registry.khronos.org/EGL/extensions/EXT/EGL_EXT_device_drm.txt), and [EGL_EXT_output_base](https://registry.khronos.org/EGL/extensions/EXT/EGL_EXT_output_base.txt).
@@ -6,15 +6,15 @@ discourse: 8484
 
 **Or: things are complicated. Let's see if one more explanation will incrementally reduce the Internet's Wrongness™**
 
-We've recently (ok, recently-ish) released [Mir 1.0](https://github.com/MirServer/mir/releases/tag/v1.0.0) with usable Wayland support. Yay!
+We've recently (ok, recently-ish) released [Mir 1.0](https://github.com/canonical/mir/releases/tag/v1.0.0) with usable Wayland support. Yay!
 
-That brought a bunch of publicity, including on [LWN](https://lwn.net/Articles/766178/). Some of the comments there and elsewhere betray a misunderstanding about what Wayland *is* (and is not), and this still occasionally comes up in ``#wayland``, so I'll dust off an old blog post, polish up the rusty bits, and see if I can make this clearer for people again! 
+That brought a bunch of publicity, including on [LWN](https://lwn.net/Articles/766178/). Some of the comments there and elsewhere betray a misunderstanding about what Wayland *is* (and is not), and this still occasionally comes up in ``#wayland``, so I'll dust off an old blog post, polish up the rusty bits, and see if I can make this clearer for people again!
 
 I'll give a run-down as to what the various projects in this space are and aim to do, throwing in X11 as a reference point.
 
 ## Wayland, Mir, and X - different projects, with different goals
 
-### X11, and X.org
+### X11, and Xorg
 
 Everyone's familiar with their friendly neighbourhood X server. This is what we've currently got as the default desktop Linux display server. For the purposes of this blog post, X consists of:
 

@@ -18,15 +18,15 @@ Compositor|Description
 --|--
 [Miriway](https://github.com/Miriway/Miriway)|A minimal desktop shell
 [Lomiri](https://lomiri.com/)|The shell used by Ubuntu Touch, aspires to be "convergent": that is work across various form factors (including desktop)
-[Ubuntu Frame](https://github.com/MirServer/ubuntu-frame/tree/main/src)|Runs an app (or apps) fullscreen, intended for embedded/IoT use
-[Miracle](https://github.com/mattkae/miracle)| A tiling window manager much like i3/sway
+[Ubuntu Frame](https://github.com/canonical/ubuntu-frame/tree/main/src)|Runs an app (or apps) fullscreen, intended for embedded/IoT use
+[Miracle](https://github.com/miracle-wm-org/miracle-wm)| A tiling window manager much like i3/sway
 [egmde](https://github.com/AlanGriffiths/egmde)|An example desktop environment used to write tutorials about writing Mir compositors
 [mir_kiosk_x11](https://github.com/MirServer/mir_kiosk_x11)|Minimal compositor to support fullscreen X11 applications
 [lomiri-system-compositor](https://gitlab.com/ubports/development/core/lomiri-system-compositor/)|Owns the display and input hardware and supports a nested shell with fewer permissions
-[miral-kiosk](https://github.com/MirServer/mir/tree/main/examples/miral-kiosk)|Runs an app (or apps) maximized
-[miral-shell](https://github.com/MirServer/mir/tree/main/examples/miral-shell)|Options for "floating" or "tiling" window management and a limited "desktop" experience with workspaces and a keyboard shortcut for launching a terminal
-[mir_demo_server](https://github.com/MirServer/mir/tree/main/examples/mir_demo_server)|"floating" window management, enables by default all the Wayland extensions Mir supports
-[miral-system-compositor](https://github.com/MirServer/mir/tree/main/examples/miral-system-compositor)|Owns the display and input hardware and supports a nested shell with fewer permissions
+[miral-kiosk](https://github.com/canonical/mir/tree/main/examples/miral-kiosk)|Runs an app (or apps) maximized
+[miral-shell](https://github.com/canonical/mir/tree/main/examples/miral-shell)|Options for "floating" or "tiling" window management and a limited "desktop" experience with workspaces and a keyboard shortcut for launching a terminal
+[mir_demo_server](https://github.com/canonical/mir/tree/main/examples/mir_demo_server)|"floating" window management, enables by default all the Wayland extensions Mir supports
+[miral-system-compositor](https://github.com/canonical/mir/tree/main/examples/miral-system-compositor)|Owns the display and input hardware and supports a nested shell with fewer permissions
 [mirco](https://github.com/wmww/mirco)|The basis of experiments moving MATE shell components to Wayland
 
 For all of these examples Mir provides the code and logic connecting the display and input hardware, and the Wayland protocols connecting to the client. Mir also separates out the concerns such as Window Management,  abstracts the graphics  stack, and manages Wayland extensions:
@@ -236,4 +236,4 @@ int main(int argc, char const* argv[])
 ```
 The code in `main()` is written using a mixture of classes defined in the `miral` API (such as `ConfigurationOption` and `X11Support`) and ones written as mart of Miriway (such as `ShellPids` and `CommandIndex`).
 
-For the `miral` API there's [documentation on the Mir website](https://mir-server.io/doc/namespacemiral.html), and for the `miriway` classes are documented in the code.
+For the `miral` API there's [documentation on the Mir website](https://canonical-mir.readthedocs-hosted.com/stable/), and for the `miriway` classes are documented in the code.
@@ -8,7 +8,7 @@ With the [Mir 1.3 release](https://discourse.ubuntu.com/t/mir-1-3-0-release/1163
 
 ## The worked example
 
-To create a "worked example" the first thing I needed was a downstream shell that plausibly needed an extension writing. For obvious reasons I chose [egmde](https://discourse.ubuntu.com/t/egmde-a-project-that-uses-mir/7129) as the example server. For the extension protocol I chose ["primary selection"](https://github.com/wayland-project/wayland-protocols/blob/master/unstable/primary-selection/primary-selection-unstable-v1.xml). While a protocol that allows every application to "spy" on the clipboard may not meet the security criteria we use for Mir in IoT, for a desktop environment like egmde it is a great convenience.
+To create a "worked example" the first thing I needed was a downstream shell that plausibly needed an extension writing. For obvious reasons I chose [egmde](https://discourse.ubuntu.com/t/egmde-a-project-that-uses-mir/7129) as the example server. For the extension protocol I chose ["primary selection"](https://gitlab.freedesktop.org/wayland/wayland-protocols/-/blob/main/unstable/primary-selection/primary-selection-unstable-v1.xml). While a protocol that allows every application to "spy" on the clipboard may not meet the security criteria we use for Mir in IoT, for a desktop environment like egmde it is a great convenience.
 
 The changes to egmde can be seen in [this pull request](https://github.com/AlanGriffiths/egmde/pull/18). I'll discuss these in more detail below, but for those that want to follow along the following setup is needed to build the code.
 
@@ -22,7 +22,7 @@ The `libmirwayland-dev` provides the tooling needed to implement the protocol in
 
 ## wlcs tests for primary selection
 
-While working on this I proposed adding some ["primary selection" tests](https://github.com/MirServer/wlcs/pull/106) to wlcs and they are included in the 1.1 release of wlcs. Here's an example of what the tests look like:
+While working on this I proposed adding some ["primary selection" tests](https://github.com/canonical/wlcs/pull/106) to wlcs and they are included in the 1.1 release of wlcs. Here's an example of what the tests look like:
 
 ```cpp
 TEST_F(PrimarySelection, source_sees_request)
@@ -72,7 +72,7 @@ add_custom_target(primary-selection-unstable
 ```
 The generator cannot implement the semantics of the protocol: it just provides the "hooks" into which to write the code. The latter can be found in a couple of files `egprimary_selection_device_controller.cpp` and `primary_selection.cpp` (this is only split this way as a lot of logic can be shared with `gtk_primary_selection`.)
 
-All these generated and and-written files are combined into a static library that is used both by egmde and by a new module `egmde-wlcs.so` that provides the wlcs test fixture for egmde. 
+All these generated and and-written files are combined into a static library that is used both by egmde and by a new module `egmde-wlcs.so` that provides the wlcs test fixture for egmde.
 
 ## wlcs test fixture
 

@@ -3,13 +3,13 @@
 ## Getting involved
 
 The Mir project website is <https://mir-server.io/>,
-the code is [hosted on GitHub](https://github.com/canonical)
+the code is [hosted on GitHub](https://github.com/canonical/mir)
 
 For announcements and other discussions on Mir see:
-[Mir on community.ubuntu](https://community.ubuntu.com/c/mir)
+[Mir on discourse.ubuntu](https://discourse.ubuntu.com/c/mir/15)
 
-For other questions and discussion about the Mir project:
-the [\#mir-server](https://web.libera.chat/?channels=#mir-server) IRC channel on Libera.Chat.
+For other questions and discussion about the Mir project, feel free to join the
+[Matrix channel](https://matrix.to/#/#mir-server:matrix.org).
 
 
 ## Getting Mir source and dependencies
@@ -48,7 +48,7 @@ With the default options this runs in a window on X (which is convenient for
 development).
 
 The miral-shell example is simple, don’t expect to see a sophisticated launcher
-by default. Within this window you can start a terminal with Ctrl-Alt-Shift-T 
+by default. Within this window you can start a terminal with Ctrl-Alt-Shift-T
 (the "Shift" is needed to avoid Ubuntu's DE intercepting the input). From this
 terminal you can start apps. For example: