From db14c907f927bf7e66e7ea09e47665123293d570 Mon Sep 17 00:00:00 2001 From: Federico Mena Quintero Date: Mon, 5 Dec 2022 19:12:33 -0600 Subject: Convert all the devel-docs files to reStructuredText Sphinx, the document generator, more or less prefers this format. --- devel-docs/atk-deprecations.md | 24 ----- devel-docs/atk-deprecations.rst | 31 ++++++ devel-docs/de-controller.md | 29 ------ devel-docs/de-controller.rst | 29 ++++++ devel-docs/gitlab-ci.md | 212 --------------------------------------- devel-docs/gitlab-ci.rst | 216 ++++++++++++++++++++++++++++++++++++++++ devel-docs/roadmap.md | 177 -------------------------------- devel-docs/roadmap.rst | 188 ++++++++++++++++++++++++++++++++++ devel-docs/toolkits.md | 52 ---------- devel-docs/toolkits.rst | 74 ++++++++++++++ 10 files changed, 538 insertions(+), 494 deletions(-) delete mode 100644 devel-docs/atk-deprecations.md create mode 100644 devel-docs/atk-deprecations.rst delete mode 100644 devel-docs/de-controller.md create mode 100644 devel-docs/de-controller.rst delete mode 100644 devel-docs/gitlab-ci.md create mode 100644 devel-docs/gitlab-ci.rst delete mode 100644 devel-docs/roadmap.md create mode 100644 devel-docs/roadmap.rst delete mode 100644 devel-docs/toolkits.md create mode 100644 devel-docs/toolkits.rst (limited to 'devel-docs') diff --git a/devel-docs/atk-deprecations.md b/devel-docs/atk-deprecations.md deleted file mode 100644 index cf411cd4..00000000 --- a/devel-docs/atk-deprecations.md +++ /dev/null @@ -1,24 +0,0 @@ -# Deprecations in ATK that need work elsewhere - -`atk_document_get_locale()` and the corresponding field in the vtable -`AtkDocumentIface.get_document_locale` are documented as deprecated since 2013 (commit -97880727). However, WebKitGtk still seems to implement it; it should use -`AtkObjectClass.get_object_locale` instead. - -Note that Orca does not seem to use the `Document.GetLocale` method nor the -`Accessible.Locale` property, so probably the code above from WebKitGtk is not exercised. - -## AtkValue - -The following methods are deprecated in `AtkValueIface` since 2014 (commit 98838b2a): - -* `get_current_value` - replaced with `get_value_and_text` -* `set_current_value` - replaced with `set_value` - -And the following are replaced with `get_range`, which returns an `AtkRange` boxed type: - -* `get_maximum_value` -* `get_minimum_value` -* `get_minimum_increment` - -Firefox still does not implement `get_range`, `get_value_and_text`, `set_value`. See bug #71. diff --git a/devel-docs/atk-deprecations.rst b/devel-docs/atk-deprecations.rst new file mode 100644 index 00000000..53ad6821 --- /dev/null +++ b/devel-docs/atk-deprecations.rst @@ -0,0 +1,31 @@ +Deprecations in ATK that need work elsewhere +============================================ + +``atk_document_get_locale()`` and the corresponding field in the vtable +``AtkDocumentIface.get_document_locale`` are documented as deprecated +since 2013 (commit 97880727). However, WebKitGtk still seems to +implement it; it should use ``AtkObjectClass.get_object_locale`` +instead. + +Note that Orca does not seem to use the ``Document.GetLocale`` method +nor the ``Accessible.Locale`` property, so probably the code above from +WebKitGtk is not exercised. + +AtkValue +-------- + +The following methods are deprecated in ``AtkValueIface`` since 2014 +(commit 98838b2a): + +- ``get_current_value`` - replaced with ``get_value_and_text`` +- ``set_current_value`` - replaced with ``set_value`` + +And the following are replaced with ``get_range``, which returns an +``AtkRange`` boxed type: + +- ``get_maximum_value`` +- ``get_minimum_value`` +- ``get_minimum_increment`` + +Firefox still does not implement ``get_range``, ``get_value_and_text``, +``set_value``. See bug #71. diff --git a/devel-docs/de-controller.md b/devel-docs/de-controller.md deleted file mode 100644 index 000b92f4..00000000 --- a/devel-docs/de-controller.md +++ /dev/null @@ -1,29 +0,0 @@ -Notes on the device event controller machinery ----------------------------------------------- - -In pyatspi2, `Registry.setReferenceWIndow()` is misspelled. However, -that function is never called in Orca or elsewhere, as far as I can -tell. - -This ties down to `atspi_registry_set_reference_window()`, which just -calls `_atspi_mutter_set_reference_window()`. The side effect of that -is to set the `ATSPI_MUTTER_DATA.window_id` and -`window_id_is_explicit`, but again, those fields never get used in the -`atspi-mutter.c` code. I think they were meant to be used in -`_atspi_mutter_generate_keyboard_event` or -`_atspi_mutter_generate_mouse_event`. - -Relatedly, `_atspi_mutter_generate_keyboard_event` takes a `keystring` -argument but it's not used. - -What is incomplete here? - -Refactoring plan ----------------- - -While the device event controller (DEC) code works for X11, it doesn't -work for Wayland because there are no hooks there to sniff the -keyboard or mouse. - -However, the machinery to synthesize events is presumably still -useful. I'd like to be able to add tests for it. diff --git a/devel-docs/de-controller.rst b/devel-docs/de-controller.rst new file mode 100644 index 00000000..ee1d6f95 --- /dev/null +++ b/devel-docs/de-controller.rst @@ -0,0 +1,29 @@ +Notes on the device event controller machinery +---------------------------------------------- + +In pyatspi2, ``Registry.setReferenceWIndow()`` is misspelled. However, +that function is never called in Orca or elsewhere, as far as I can +tell. + +This ties down to ``atspi_registry_set_reference_window()``, which just +calls ``_atspi_mutter_set_reference_window()``. The side effect of that +is to set the ``ATSPI_MUTTER_DATA.window_id`` and +``window_id_is_explicit``, but again, those fields never get used in the +``atspi-mutter.c`` code. I think they were meant to be used in +``_atspi_mutter_generate_keyboard_event`` or +``_atspi_mutter_generate_mouse_event``. + +Relatedly, ``_atspi_mutter_generate_keyboard_event`` takes a +``keystring`` argument but it’s not used. + +What is incomplete here? + +Refactoring plan +---------------- + +While the device event controller (DEC) code works for X11, it doesn’t +work for Wayland because there are no hooks there to sniff the keyboard +or mouse. + +However, the machinery to synthesize events is presumably still useful. +I’d like to be able to add tests for it. diff --git a/devel-docs/gitlab-ci.md b/devel-docs/gitlab-ci.md deleted file mode 100644 index 26abeeee..00000000 --- a/devel-docs/gitlab-ci.md +++ /dev/null @@ -1,212 +0,0 @@ -# Gitlab Continuous Integration (CI) for at-spi2-core - -Summary: make the robots set up an environment for running the test -suite, run it, and report back to us. - -If you have questions about the CI, mail federico@gnome.org, or [file -an issue](https://gitlab.gnome.org/GNOME/at-spi2-core/-/issues) and -mention `@federico` in it. - -Table of contents: - -[[_TOC_]] - -# Quick overview - -By having a [`.gitlab-ci.yml`](../.gitlab-ci.yml) file in the toplevel -directory of a project, Gitlab knows that it must run a continuous -integration pipeline when certain events occur, for example, when -someone creates a merge request, or pushes to a branch. - -What's a pipeline? It is an automated version of the following. -Running the test suite for at-spi2-core involves some repetitive -steps: - -* Create a pristine and minimal environment for testing, without all the random - gunk from one's development system. Gitlab CI uses Linux containers, - with pre-built operating system images in the [Open Container - Initiative][OCI] format — this is what Docker, Podman, etc. all use. - -* Install the build-time dependencies (gcc, meson, libfoo-devel, - etc.), the test-time dependencies (dbus-daemon, etc.) in that - pristine environment, as well as special tools (lcov, libasan, - clang-tools). - -* Run the build and install it, and run the test suite. - -* Run variations of the build and test suite with other tools — for - example, using static analysis during compilation, or with address - sanitizer (asan), or with a code coverage tool. Gitlab can collect - the analysis results of each of these tools and present them as part - of the merge request that is being evaluated. It also lets - developers obtain those useful results without dealing with a lot of - fiddly tools on their own computers. - -Additionally, on each pipeline run we'd like to do extra repetitive -work like building the reference documentation, and publishing it on a -web page. - -The `.gitlab-ci.yml` file defines the CI pipeline, the jobs it will -run (build/test, coverage, asan, static-scan, etc.), and the locations -where each job's artifacts will be stored. - -What's an artifact or a job? Read on! - -# A little glossary - -**Pipeline** - A collection of **jobs**, which can be run in parallel -or sequentially. For example, a pair of "build" and "test" jobs would -need to run sequentially, but maybe a "render documentation" job can -run in parallel with them. Similarly, "build" jobs for various -distributions or configurations could be run in parallel. - -**Job** - Think of it as running a shell script within a container. -It can have input from other previous jobs: if you have separate -"build" and "test" jobs, then the "build" job will want to keep around -its compiled artifacts so that the "test" job can use them. It can -provide output artifacts that can be stored for human perusal, or for -use by other jobs. - -**Artifact** - Something produced from a job. If your job compiles -binaries, those binaries could be artifacts if you decide to keep them -around for use later. A documentation job can produce HTML artifacts -from the rendered documentation. A code coverage job will produce a -coverage report artifact. - -**Runner** - An operating system setup for running jobs. -Gitlab.gnome.org provides runners for Linux, BSD, Windows, and MacOS. -For example. the Linux runners let you use any OCI image, so you can -test on openSUSE, Fedora, a custom distro, etc. You don't normally -need to be concerned with runners; Gitlab assigns the shared runners -automatically to your pipeline. - -**Container** - You can think of it as a chroot with extra isolation, -or a lightweight virtual machine. Basically, the Linux kernel can -isolate groups of processes in control groups (cgroups). Each cgroup -can have a different view of the file system, as if you had a -different chroot for each cgroup. Cgroups can be isolated to be in -their own PID namespace, so running "ps" in the container will not -show all the processes in the system, but only those inside the -container's cgroup. File system overlays allow you to have read-only -images for the operating system (the OCI images we talked about above) -plus a read-write overlay that is kept around only during the lifetime -of a container, or persistently if one wants. For Gitlab CI one does -not need to deal with containers directly, but keep in mind that your -jobs will run inside a container, which is more limited than e.g. a -shell session on a graphical, development machine. - -# The CI pipeline for at-spi2-core - -The `.gitlab-ci.yml` file is a more-or-less declarative description -the CI pipeline, with some `script` sections which are imperative -commands to actually *do stuff*. - -Jobs are run in `stages`, and the names of the stages are declared -near the beginning of the YAML file. The stage names are arbitrary; -the ones here follow some informal GNOME conventions. - -Jobs are declared at the toplevel of the YAML file, and they are -distinguished from other declarations by having a container `image` -declared for them, as well as a `script` to execute. - -Many jobs need exactly the same kind of setup (same container images, -mostly same package dependencies), so they use `extends:` to use a -declared template with all that stuff instead of redeclaring it each -time. - -The `build` stage has these jobs: - -* `opensuse-x86_64` - Extends the `.only-default` rule, - builds/installs the code, and runs the tests. Generally this is the - job that one cares about during regular development. - -* `fedora-x86_64` - Same as the previous job, but runs on Fedora - instead of openSUSE. The intention is to run the build - configuration for `dbus-broker` here instead of `dbus-daemon`. - -The `analysis` stage has these jobs: - -* `static-scan` - Runs static analysis during compilation, which - performs interprocedural analysis to detect things like double - `free()` or uninitialized struct fields across functions. - -* `asan-build` - Builds and runs with Address Sanitizer (libasan). - -* `coverage` - Instruments the build to get code coverage information, - and runs the test suite to see how much of the code it manages to - exercise. This is to see which code paths may be untested - automatically, and to decide which ones would require manual - testing, or refactoring to allow automated testing. - -As of 2022/Apr/19 there are some commented-out jobs to generate -documentation and publish it; this needs to be made to work. - -# CI templates - -The task of setting up CI for a particular distro or build -configuration is rather repetitive. One has to start with a "bare" -distro image, then install the build-time dependencies that your -project requires, then that is slow, then you want to build a -container image instead of installing packages every time, then you -want to test another distro, then you want to make those container -images easily available to your project's forks, and then you start -pulling your hair. - -[Fredesktop CI Templates][ci-templates] -([documentation][ci-templates-docs]) are a solution to this. They can -automatically build container images for various distros, make them -available to forks of your project, and have some nice amenities to -reduce the maintenance burden. - -At-spi2-core uses CI templates to test its various build -configurations, since it actually works differently depending on a -distro's choice of `dbus-daemon` versus `dbus-broker`. - -The prebuilt container images are stored here: -https://gitlab.gnome.org/GNOME/at-spi2-core/container_registry - -They get updated automatically thanks to the CI Templates machinery. - -# General advice and future work - -A failed run of a CI pipeline should trouble you; it either means that -some test broke, or that something is not completely deterministic. -Fix it at once. - -Try not to accept merge requests that fail the CI, as this will make -`git bisect` hard in the future. There are tools like Marge-bot to -enforce this; ask federico@gnome.org about it. Read ["The Not Rocket -Science Rule Of Software -Engineering"](https://graydon.livejournal.com/186550.html), which can -be summarized as "automatically maintain a repository of code that -always passes all the tests" for inspiration. Marge-bot is an -implementation of that, and can be used with Gitlab. - -If your software can be configured to build with substantial changes, -the CI pipeline should have jobs that test each of those -configurations. For example, at-spi-bus-launcher operates differently -depending on whether `dbus-daemon` or `dbus-broker` are being used. As of -2022/Apr/19 the CI only tests `dbus-daemon`; there should be a test for -dbus-broker, too, in the `fedora-x86_64` job since that is one of the -distros that uses `dbus-broker`. - -Although the YAML syntax for `.gitlab-ci.yml` is a bit magic, the -scripts and configuration are quite amenable to refactoring. Do it -often! - -Minimizing the amount of time that CI takes to run is a good goal. It -reduces energy consumption in the build farm, and allows you to have a -faster feedback loop. Instead of installing package dependencies on -each job, we can move to prebuilt container images. - -# References - -Full documentation for Gitlab CI: https://docs.gitlab.com/ee/ci/ - -Introduction to Gitlab CI: https://docs.gitlab.com/ee/ci/quick_start/index.html - -Freedesktop CI templates: https://gitlab.freedesktop.org/freedesktop/ci-templates/ - -[OCI]: https://opencontainers.org/ -[ci-templates]: https://gitlab.freedesktop.org/freedesktop/ci-templates/ -[ci-templates-docs]: https://freedesktop.pages.freedesktop.org/ci-templates/ diff --git a/devel-docs/gitlab-ci.rst b/devel-docs/gitlab-ci.rst new file mode 100644 index 00000000..27df04be --- /dev/null +++ b/devel-docs/gitlab-ci.rst @@ -0,0 +1,216 @@ +Gitlab Continuous Integration (CI) for at-spi2-core +=================================================== + +Summary: make the robots set up an environment for running the test +suite, run it, and report back to us. + +If you have questions about the CI, mail federico@gnome.org, or `file an +issue `__ and +mention ``@federico`` in it. + +Table of contents: + +[[*TOC*]] + +Quick overview +============== + +By having a ```.gitlab-ci.yml`` <../.gitlab-ci.yml>`__ file in the +toplevel directory of a project, Gitlab knows that it must run a +continuous integration pipeline when certain events occur, for example, +when someone creates a merge request, or pushes to a branch. + +What’s a pipeline? It is an automated version of the following. Running +the test suite for at-spi2-core involves some repetitive steps: + +- Create a pristine and minimal environment for testing, without all + the random gunk from one’s development system. Gitlab CI uses Linux + containers, with pre-built operating system images in the `Open + Container Initiative `__ format — this + is what Docker, Podman, etc. all use. + +- Install the build-time dependencies (gcc, meson, libfoo-devel, etc.), + the test-time dependencies (dbus-daemon, etc.) in that pristine + environment, as well as special tools (lcov, libasan, clang-tools). + +- Run the build and install it, and run the test suite. + +- Run variations of the build and test suite with other tools — for + example, using static analysis during compilation, or with address + sanitizer (asan), or with a code coverage tool. Gitlab can collect + the analysis results of each of these tools and present them as part + of the merge request that is being evaluated. It also lets developers + obtain those useful results without dealing with a lot of fiddly + tools on their own computers. + +Additionally, on each pipeline run we’d like to do extra repetitive work +like building the reference documentation, and publishing it on a web +page. + +The ``.gitlab-ci.yml`` file defines the CI pipeline, the jobs it will +run (build/test, coverage, asan, static-scan, etc.), and the locations +where each job’s artifacts will be stored. + +What’s an artifact or a job? Read on! + +A little glossary +================= + +**Pipeline** - A collection of **jobs**, which can be run in parallel or +sequentially. For example, a pair of “build” and “test” jobs would need +to run sequentially, but maybe a “render documentation” job can run in +parallel with them. Similarly, “build” jobs for various distributions or +configurations could be run in parallel. + +**Job** - Think of it as running a shell script within a container. It +can have input from other previous jobs: if you have separate “build” +and “test” jobs, then the “build” job will want to keep around its +compiled artifacts so that the “test” job can use them. It can provide +output artifacts that can be stored for human perusal, or for use by +other jobs. + +**Artifact** - Something produced from a job. If your job compiles +binaries, those binaries could be artifacts if you decide to keep them +around for use later. A documentation job can produce HTML artifacts +from the rendered documentation. A code coverage job will produce a +coverage report artifact. + +**Runner** - An operating system setup for running jobs. +Gitlab.gnome.org provides runners for Linux, BSD, Windows, and MacOS. +For example. the Linux runners let you use any OCI image, so you can +test on openSUSE, Fedora, a custom distro, etc. You don’t normally need +to be concerned with runners; Gitlab assigns the shared runners +automatically to your pipeline. + +**Container** - You can think of it as a chroot with extra isolation, or +a lightweight virtual machine. Basically, the Linux kernel can isolate +groups of processes in control groups (cgroups). Each cgroup can have a +different view of the file system, as if you had a different chroot for +each cgroup. Cgroups can be isolated to be in their own PID namespace, +so running “ps” in the container will not show all the processes in the +system, but only those inside the container’s cgroup. File system +overlays allow you to have read-only images for the operating system +(the OCI images we talked about above) plus a read-write overlay that is +kept around only during the lifetime of a container, or persistently if +one wants. For Gitlab CI one does not need to deal with containers +directly, but keep in mind that your jobs will run inside a container, +which is more limited than e.g. a shell session on a graphical, +development machine. + +The CI pipeline for at-spi2-core +================================ + +The ``.gitlab-ci.yml`` file is a more-or-less declarative description +the CI pipeline, with some ``script`` sections which are imperative +commands to actually *do stuff*. + +Jobs are run in ``stages``, and the names of the stages are declared +near the beginning of the YAML file. The stage names are arbitrary; the +ones here follow some informal GNOME conventions. + +Jobs are declared at the toplevel of the YAML file, and they are +distinguished from other declarations by having a container ``image`` +declared for them, as well as a ``script`` to execute. + +Many jobs need exactly the same kind of setup (same container images, +mostly same package dependencies), so they use ``extends:`` to use a +declared template with all that stuff instead of redeclaring it each +time. + +The ``build`` stage has these jobs: + +- ``opensuse-x86_64`` - Extends the ``.only-default`` rule, + builds/installs the code, and runs the tests. Generally this is the + job that one cares about during regular development. + +- ``fedora-x86_64`` - Same as the previous job, but runs on Fedora + instead of openSUSE. The intention is to run the build configuration + for ``dbus-broker`` here instead of ``dbus-daemon``. + +The ``analysis`` stage has these jobs: + +- ``static-scan`` - Runs static analysis during compilation, which + performs interprocedural analysis to detect things like double + ``free()`` or uninitialized struct fields across functions. + +- ``asan-build`` - Builds and runs with Address Sanitizer (libasan). + +- ``coverage`` - Instruments the build to get code coverage + information, and runs the test suite to see how much of the code it + manages to exercise. This is to see which code paths may be untested + automatically, and to decide which ones would require manual testing, + or refactoring to allow automated testing. + +As of 2022/Apr/19 there are some commented-out jobs to generate +documentation and publish it; this needs to be made to work. + +CI templates +============ + +The task of setting up CI for a particular distro or build configuration +is rather repetitive. One has to start with a “bare” distro image, then +install the build-time dependencies that your project requires, then +that is slow, then you want to build a container image instead of +installing packages every time, then you want to test another distro, +then you want to make those container images easily available to your +project’s forks, and then you start pulling your hair. + +`Fredesktop CI +Templates `__ +(`documentation `__) +are a solution to this. They can automatically build container images +for various distros, make them available to forks of your project, and +have some nice amenities to reduce the maintenance burden. + +At-spi2-core uses CI templates to test its various build configurations, +since it actually works differently depending on a distro’s choice of +``dbus-daemon`` versus ``dbus-broker``. + +The prebuilt container images are stored here: +https://gitlab.gnome.org/GNOME/at-spi2-core/container_registry + +They get updated automatically thanks to the CI Templates machinery. + +General advice and future work +============================== + +A failed run of a CI pipeline should trouble you; it either means that +some test broke, or that something is not completely deterministic. Fix +it at once. + +Try not to accept merge requests that fail the CI, as this will make +``git bisect`` hard in the future. There are tools like Marge-bot to +enforce this; ask federico@gnome.org about it. Read `“The Not Rocket +Science Rule Of Software +Engineering” `__, which can +be summarized as “automatically maintain a repository of code that +always passes all the tests” for inspiration. Marge-bot is an +implementation of that, and can be used with Gitlab. + +If your software can be configured to build with substantial changes, +the CI pipeline should have jobs that test each of those configurations. +For example, at-spi-bus-launcher operates differently depending on +whether ``dbus-daemon`` or ``dbus-broker`` are being used. As of +2022/Apr/19 the CI only tests ``dbus-daemon``; there should be a test +for dbus-broker, too, in the ``fedora-x86_64`` job since that is one of +the distros that uses ``dbus-broker``. + +Although the YAML syntax for ``.gitlab-ci.yml`` is a bit magic, the +scripts and configuration are quite amenable to refactoring. Do it +often! + +Minimizing the amount of time that CI takes to run is a good goal. It +reduces energy consumption in the build farm, and allows you to have a +faster feedback loop. Instead of installing package dependencies on each +job, we can move to prebuilt container images. + +References +========== + +Full documentation for Gitlab CI: https://docs.gitlab.com/ee/ci/ + +Introduction to Gitlab CI: +https://docs.gitlab.com/ee/ci/quick_start/index.html + +Freedesktop CI templates: +https://gitlab.freedesktop.org/freedesktop/ci-templates/ diff --git a/devel-docs/roadmap.md b/devel-docs/roadmap.md deleted file mode 100644 index c88535d1..00000000 --- a/devel-docs/roadmap.md +++ /dev/null @@ -1,177 +0,0 @@ -# Accessibility infrastructure roadmap - -Note that this roadmap refers exclusively to **cleanups** and **paying -technical debt**. It does not yet refer to actually changing the -accessibility interfaces, or the way accessibility works in general. - -## High level goals, detailed below - -* Make at-spi2-core/xml the authoritative version of the a11y interfaces. - -* Remove all the hand-written DBus code in at-spi2-core; replace with - gdbus as generated from the XML files. - -* Add good end-to-end tests, to complement the ones already in at-spi2-atk. - -* Remove as much duplication / leftovers from the CORBA days / - compatibility hacks as we can. - -* Give people the confidence that the accessibility stack works, so - it's their responsibility to make their apps and gnome-shell - accessible. - -## Short term tasks - -* Merge these repositories into a single one: at-spi2-core, atk, - at-spi2-atk. They are tightly coupled, and it will be much easier - to test/refactor them if the code is in the same repo. See "[merge - the repositories](#merge-the-repositories)" below for details. - -* Replace manually-written DBus code in at-spi2-core for automatically - generated code. See "[DBus update for - libatspi](#dbus-update-for-libatspi)" below for details. - -* [Make the XML interfaces the single source of truth](#make-the-xml-interfaces-the-single-source-of-truth). - -# Details on big tasks - -## Merge the repositories - -Merging at-spi2-core, atk, and at-spi2-atk into a single repository -will make end-to-end testing easier. As of 2022/May/27, at-spi2-atk -has a few end-to-end tests, which do not manage to exercise all the -code in libatspi or in atk. Having all the code in the same -repository will make it easier to refactor and test things. Some -reasons to merge: - -* at-spi2-atk has the real end-to-end integration tests for - at-spi2-core; it tests the part for an accessible application and - the accessibility technology together, with the registry daemon in - the middle. It would be nice to run these tests automatically when - any of at-spi2-core or atk changes. - -* Both at-spi2-atk and pyatspi2 have "dummy" implementations of the - ATK interfaces to use with their tests. It may be possible to - deduplicate that. - -* Doing refactoring across all modules will be easier if their tests - are in a single place. - -* We only have to get the CI working once, instead of three times. - -Some cool things in at-spi2-core's CI that now work for all the -accessibility middleware: - -* CI pipelines run the test suite and generate a code coverage report. - This can be used to fine-tune tests, or decide how to refactor - things for finer-grained testing. - -* Static analysis. Fix broken C code as early as possible. - -* Address Sanitizer - runtime analysis; does not fully work yet, but - the basics are there. - -* Infrastructure to test build configurations for various distro - images, e.g. dbus-daemon for openSUSE, versus dbus-broker for - Fedora - those have different code paths. - -## Make the XML interfaces the single source of truth - -In the past the at-spi2-core/xml files, which define the DBus -interfaces for accessibility, have gotten out of sync with -at-spi2-core's own C code, because it does DBus calls by hand instead -of using an autogenerated binding - there weren't any at the time it -was written. Also they have gotten out of sync with external copies, -like GTK. Perhaps we can add some bits to GTK's CI scripts to -guarantee that this doesn't happen, or make GTK just reference -at-spi2-core/xml directly. - -It may not be possible to "disappear" libatspi2 and rely only on an -autogenerated binding for the XML DBus interfaces everywhere, but that -should certainly be a goal. - -## Remove hand-written DBus code - -My initial goal is to replace it with gdbus from GIO (an auto-generated C binding to XML -interfaces). I want to experiment with a few strategies to make this easier. Right now -all the DBus code is interwoven with logic from at-spi2-core, so the first thing is to -separate them. Then, replace the DBus code in one shot for gdbus. - -For example, there's quite a bit of code like this: - -```c -static void -handle_some_method (DBusMessage *message) -{ - foo = demarshal_a_bit (); - bar = find_the_accessible (); - bar_set_foo (bar, foo); - - baz = demarshal_a_bit (); - bar_set_baz (bar, baz); - - while (some_logic_here) - { - qux = demarshal_something (); - blah_blah (qux, bar); - } - - /* etc */ -} -``` - -So I would first split it into a part that demarshals everything, and then one that does the logic: - -```c -typedef struct { - Accessible accessible; - Foo foo; - Baz baz; - Qux quxes[]; -} SomeMethodArgs; - -handle_some_method (DBusMessage *message) -{ - SomeMethodArgs args; - - if (demarshal_some_method_args (message, &args) != SUCCESS) - { - return ERROR; - } - - do_the_thing (args.accessible, args.foo, args.baz, args.quxes); -} -``` - -Once everything is split apart, it's a lot easier to replace the demarshalers with gdbus -calls, and the rest of the logic can hopefully remain unchanged. - -As a side benefit, this may allow testing the logic without having to worry about -inter-process communication. Test the thing; assume communication works. - -It may not be possible to separate all such cases so cleanly. -However, if a certain "sequence" requires intermediate IPC, then that -is a good indication for a less granular interface to add later: -instead of querying for an object and then for each of its properties -/ children / etc., maybe send the whole object's tree in a single -call. - -(Future goal: this separation of IPC vs. logic may make it easier, to -port the accessibility middleware to Rust - something I'd really like -to do.) - -## End-to-end tests - -There are already some end-to-end tests in at-spi2-atk/tests. They -create a mock AT and a mock accessible application, and ensure that -what they communicate through the accessibility bus matches on both -ends. - -These tests are good! Let's add more extensive ones to help test -things like event throttling, unstable applications, compatibility -APIs, etc. - -## Should we merge pyatspi2 in here? - -Maybe! It is a compatibility layer, through and through, and maybe we -can disappear it gradually if we change Orca in lockstep. diff --git a/devel-docs/roadmap.rst b/devel-docs/roadmap.rst new file mode 100644 index 00000000..3f194f14 --- /dev/null +++ b/devel-docs/roadmap.rst @@ -0,0 +1,188 @@ +Accessibility infrastructure roadmap +==================================== + +Note that this roadmap refers exclusively to **cleanups** and **paying +technical debt**. It does not yet refer to actually changing the +accessibility interfaces, or the way accessibility works in general. + +High level goals, detailed below +-------------------------------- + +- Make at-spi2-core/xml the authoritative version of the a11y + interfaces. + +- Remove all the hand-written DBus code in at-spi2-core; replace with + gdbus as generated from the XML files. + +- Add good end-to-end tests, to complement the ones already in + at-spi2-atk. + +- Remove as much duplication / leftovers from the CORBA days / + compatibility hacks as we can. + +- Give people the confidence that the accessibility stack works, so + it’s their responsibility to make their apps and gnome-shell + accessible. + +Short term tasks +---------------- + +- Merge these repositories into a single one: at-spi2-core, atk, + at-spi2-atk. They are tightly coupled, and it will be much easier to + test/refactor them if the code is in the same repo. See “`merge the + repositories <#merge-the-repositories>`__” below for details. + +- Replace manually-written DBus code in at-spi2-core for automatically + generated code. See “`DBus update for + libatspi <#dbus-update-for-libatspi>`__” below for details. + +- `Make the XML interfaces the single source of + truth <#make-the-xml-interfaces-the-single-source-of-truth>`__. + +Details on big tasks +==================== + +Merge the repositories +---------------------- + +Merging at-spi2-core, atk, and at-spi2-atk into a single repository will +make end-to-end testing easier. As of 2022/May/27, at-spi2-atk has a few +end-to-end tests, which do not manage to exercise all the code in +libatspi or in atk. Having all the code in the same repository will make +it easier to refactor and test things. Some reasons to merge: + +- at-spi2-atk has the real end-to-end integration tests for + at-spi2-core; it tests the part for an accessible application and the + accessibility technology together, with the registry daemon in the + middle. It would be nice to run these tests automatically when any of + at-spi2-core or atk changes. + +- Both at-spi2-atk and pyatspi2 have “dummy” implementations of the ATK + interfaces to use with their tests. It may be possible to deduplicate + that. + +- Doing refactoring across all modules will be easier if their tests + are in a single place. + +- We only have to get the CI working once, instead of three times. + +Some cool things in at-spi2-core’s CI that now work for all the +accessibility middleware: + +- CI pipelines run the test suite and generate a code coverage report. + This can be used to fine-tune tests, or decide how to refactor things + for finer-grained testing. + +- Static analysis. Fix broken C code as early as possible. + +- Address Sanitizer - runtime analysis; does not fully work yet, but + the basics are there. + +- Infrastructure to test build configurations for various distro + images, e.g. dbus-daemon for openSUSE, versus dbus-broker for Fedora + - those have different code paths. + +Make the XML interfaces the single source of truth +-------------------------------------------------- + +In the past the at-spi2-core/xml files, which define the DBus interfaces +for accessibility, have gotten out of sync with at-spi2-core’s own C +code, because it does DBus calls by hand instead of using an +autogenerated binding - there weren’t any at the time it was written. +Also they have gotten out of sync with external copies, like GTK. +Perhaps we can add some bits to GTK’s CI scripts to guarantee that this +doesn’t happen, or make GTK just reference at-spi2-core/xml directly. + +It may not be possible to “disappear” libatspi2 and rely only on an +autogenerated binding for the XML DBus interfaces everywhere, but that +should certainly be a goal. + +Remove hand-written DBus code +----------------------------- + +My initial goal is to replace it with gdbus from GIO (an auto-generated +C binding to XML interfaces). I want to experiment with a few strategies +to make this easier. Right now all the DBus code is interwoven with +logic from at-spi2-core, so the first thing is to separate them. Then, +replace the DBus code in one shot for gdbus. + +For example, there’s quite a bit of code like this: + +.. code:: c + + static void + handle_some_method (DBusMessage *message) + { + foo = demarshal_a_bit (); + bar = find_the_accessible (); + bar_set_foo (bar, foo); + + baz = demarshal_a_bit (); + bar_set_baz (bar, baz); + + while (some_logic_here) + { + qux = demarshal_something (); + blah_blah (qux, bar); + } + + /* etc */ + } + +So I would first split it into a part that demarshals everything, and +then one that does the logic: + +.. code:: c + + typedef struct { + Accessible accessible; + Foo foo; + Baz baz; + Qux quxes[]; + } SomeMethodArgs; + + handle_some_method (DBusMessage *message) + { + SomeMethodArgs args; + + if (demarshal_some_method_args (message, &args) != SUCCESS) + { + return ERROR; + } + + do_the_thing (args.accessible, args.foo, args.baz, args.quxes); + } + +Once everything is split apart, it’s a lot easier to replace the +demarshalers with gdbus calls, and the rest of the logic can hopefully +remain unchanged. + +As a side benefit, this may allow testing the logic without having to +worry about inter-process communication. Test the thing; assume +communication works. + +It may not be possible to separate all such cases so cleanly. However, +if a certain “sequence” requires intermediate IPC, then that is a good +indication for a less granular interface to add later: instead of +querying for an object and then for each of its properties / children / +etc., maybe send the whole object’s tree in a single call. + +(Future goal: this separation of IPC vs. logic may make it easier, to +port the accessibility middleware to Rust - something I’d really like to +do.) + +End-to-end tests +---------------- + +There are already some end-to-end tests in at-spi2-atk/tests. They +create a mock AT and a mock accessible application, and ensure that what +they communicate through the accessibility bus matches on both ends. + +These tests are good! Let’s add more extensive ones to help test things +like event throttling, unstable applications, compatibility APIs, etc. + +Should we merge pyatspi2 in here? +--------------------------------- + +Maybe! It is a compatibility layer, through and through, and maybe we +can disappear it gradually if we change Orca in lockstep. diff --git a/devel-docs/toolkits.md b/devel-docs/toolkits.md deleted file mode 100644 index c05318a8..00000000 --- a/devel-docs/toolkits.md +++ /dev/null @@ -1,52 +0,0 @@ -# Accessibility implementations in different toolkits - -## Toolkits that use the DBus APIs directly - -### GTK4 - -Sources: [`gtk4/gtk/a11y`](https://gitlab.gnome.org/GNOME/gtk/-/tree/main/gtk/a11y) - -## Qt5 - -Sources: [`qtbase/src/gui/accessible/linux`](https://github.com/qt/qtbase/tree/dev/src/gui/accessible/linux) - -Note: Qt's implementation of -[Cache.GetItems](https://github.com/qt/qtbase/blob/dev/src/gui/accessible/linux/qspi_struct_marshallers.cpp#L41-L71) -uses the old signature `a((so)(so)(so)a(so)assusau)` instead of the -preferred/new `a((so)(so)(so)iiassusau)`. - -## WebKit - -Sources: [`WebKit/Source/WebCore/accessibility/atspi`](https://github.com/WebKit/WebKit/tree/main/Source/WebCore/accessibility/atspi) - - -## Toolkits that use ATK - -## GTK3 - -Sources: [`gtk3/gtk/a11y`](https://gitlab.gnome.org/GNOME/gtk/-/tree/gtk-3-24/gtk/a11y) - -## gnome-shell / St / via clutter's cally - -Sources: [`mutter/clutter/clutter/cally`](https://gitlab.gnome.org/GNOME/mutter/-/tree/main/clutter/clutter/cally) - -## Mozilla Firefox - -Sources: [`gecko-dev/accessible/atk`](https://github.com/mozilla/gecko-dev/tree/master/accessible/atk) - -## Chromium - -Uses both ATK and libatspi? - -Sources: -* [`chromium/ui/accessibility/platform/*auralinux*`](https://github.com/chromium/chromium/tree/main/ui/accessibility/platform) (atk) -* [`chromium/ui/accessibility/platform/inspect/*auralinux*`](https://github.com/chromium/chromium/tree/main/ui/accessibility/platform/inspect) (atspi) -* [`chromium/content/browser/accessibility/*auralinux*`](https://github.com/chromium/chromium/tree/main/content/browser/accessibility/) (atspi and atk) - -## LibreOffice - -Sources: [`LibreOffice/core/vcl/unx/gtk3/a11y`](https://github.com/LibreOffice/core/tree/master/vcl/unx/gtk3/a11y) - -## Java Swing - via java-atk-wrapper - -Sources: [`java-atk-wrapper`](https://gitlab.gnome.org/GNOME/java-atk-wrapper) diff --git a/devel-docs/toolkits.rst b/devel-docs/toolkits.rst new file mode 100644 index 00000000..609cb911 --- /dev/null +++ b/devel-docs/toolkits.rst @@ -0,0 +1,74 @@ +Accessibility implementations in different toolkits +=================================================== + +Toolkits that use the DBus APIs directly +---------------------------------------- + +GTK4 +~~~~ + +Sources: +```gtk4/gtk/a11y`` `__ + +Qt5 +--- + +Sources: +```qtbase/src/gui/accessible/linux`` `__ + +Note: Qt’s implementation of +`Cache.GetItems `__ +uses the old signature ``a((so)(so)(so)a(so)assusau)`` instead of the +preferred/new ``a((so)(so)(so)iiassusau)``. + +WebKit +------ + +Sources: +```WebKit/Source/WebCore/accessibility/atspi`` `__ + +Toolkits that use ATK +--------------------- + +GTK3 +---- + +Sources: +```gtk3/gtk/a11y`` `__ + +gnome-shell / St / via clutter’s cally +-------------------------------------- + +Sources: +```mutter/clutter/clutter/cally`` `__ + +Mozilla Firefox +--------------- + +Sources: +```gecko-dev/accessible/atk`` `__ + +Chromium +-------- + +Uses both ATK and libatspi? + +Sources: \* +```chromium/ui/accessibility/platform/*auralinux*`` `__ +(atk) \* +```chromium/ui/accessibility/platform/inspect/*auralinux*`` `__ +(atspi) \* +```chromium/content/browser/accessibility/*auralinux*`` `__ +(atspi and atk) + +LibreOffice +----------- + +Sources: +```LibreOffice/core/vcl/unx/gtk3/a11y`` `__ + +Java Swing - via java-atk-wrapper +--------------------------------- + +Sources: +```java-atk-wrapper`` `__ -- cgit v1.2.1