Acacia is a library for accessing accessibility APIs. The goal of this library to make it easier to test or inspect the accessibility APIs on any platform for any application. The library provides a thin C++ wrapper around each supported API, which can also be exposed in a Python C++ extension module and a Node.js C++ addon.
OS | Supported API |
---|---|
Linux | AT-SPI |
macOS | NSAccessibility Protocol (also referred to as AX API) |
Windows | MSAA with IAccessible2 1.3 |
This library is a work in progress, no API is completely supported, yet! :) To see the currently supported APIs, peruse the documentation or take a look at the examples.
(If you're viewing this README on GitHub, you can use the Outline button at the top right of the preview pane to see a Table of Contents for this README.)
We use clang-format to ensure our code is consistently formatted and readable. Our pre-commit configuration includes checking clang-format has already been run, and runs on each pull request as a pre-merge check.
We recommend setting up clang-format
and pre-commit to ensure your code is consistent with the project style (and to make your life easier!)
Setting up pre-commit will cause clang-format to run on uncommitted code (changed lines only) when you run git commit
, and prevent the commit if clang-format makes any changes. You can then run git commit
again to commit the formatted change.
You can also set up many editors (including Emacs and Visual Studio Code) to run clang-format automatically each time you save a file.
The OS-specific instructions below include instructions on setting up clang-format and pre-commit, as well as setting up CMake to build the project binaries.
By default, building the project will only build the C++ library.
The build steps on each operating system mention <feature-flags>
. These are flags that may be passed to CMake during the configure step in order to enable building the various optional features:
Flag | Feature | Default |
---|---|---|
ACACIA_PYTHON | Enable building Python bindings | OFF |
ACACIA_NODEJS | Enable building Node.js bindings | OFF |
ACACIA_DOCS | Enable building Doxygen documentation for the C++ library | OFF |
ACACIA_TESTS | Enable building tests. | ON |
ACACIA_CAT | Enable building the experimental cross-platform library. If enabled, this will also build bindings for the cross-platform library for each enabled optional target language. | OFF |
To pass feature flags on the command line, add -D<flag>=ON
for each feature flag you wish to enable, and -D<flag>=OFF
for each feature you wish to disable. For example:
The Python and NodeJS bindings are built with SWIG. SWIG version 4.2.0 is required to build the bindings. If your package manager provides an older version of SWIG, you will need to download and build from source, see: https://swig.org/
The instructions below assume a Debian-like system (e.g. Debian, Ubuntu).
There is a known issue linking the NodeJS module with the Debian default linker. So, using the gold linker is recommended:
For building Python3 bindings (optional):
For building the Node.js module (optional):
You should be able to simply install clang-format and pre-commit using apt:
From the project root, configure pre-commit for the project:
From the project root:
This will produce a shared C++ library, optional Python module and optional Node.js module in build/lib/atspi/
, and examples in build/examples/
.
An examples/atspi
folder will be created under the build directory containing example programs that show how the API can be used.
dump_tree_atspi
: (C++ binary.) Dumps the accessible tree of a running application given its process ID and/or name.dump_tree_atspi.js
: If the Node.js bindings feature is enabled, this program can be run using the same arguments as the C++ binary via node examples/atspi/dump_tree_atspi.js
.dump_tree_atspi.py
: If the Python bindings feature is enabled, this program can be run using the same arguments as the C++ binary via python examples/atspi/dump_tree_atspi.py
.All examples can be used to dump information in an accessibility tree using the PID of the browser, its name or substring thereof, or both:
To use the Python module, import
acacia_atspi
from within your Python script or the Python Interpreter. For example:
To use the Node.js module, require
acacia_atspi
from your JavaScript code or the Node.js REPL. For example:
Ensure you have XCode and Ninja installed.
If you encounter a python3_LIBRARIES not found, try updating python with:
For the NodeJS bindings, you will need to download and build node-gyp app and put the executable on your path. One way to do this is through npm:
For pre-commit
:
pip install pre-commit
pip install clang-format
pre-commit install
The outputs will show up at the same relative path under build/
as the path to the CMakeLists.txt
file which defined the target, e.g. for a target defined in lib/mac/CMakeLists.txt
, the output will be in build/lib/mac/<target>
.
Currently, we build the executable:
As well as a python module:
And a node C++ add-on:
First, install Visual Studios to get the Visual Studio installer. You can then find the "Visual Studio Installer" from the start menu.
Through the Visual Studio Installer, install:
Through the Microsoft Store, download Python.
Git for windows:
For package management, you can use scoop (https://scoop.sh/) or the windows package manager of your choice.
IMPORTANT: This project was not designed for a multi-configuration generator, like Visual Studios. Instead, please use a single configuration generator. The recommended generator is Ninja and the following instructions will assume Ninja will be used. You can install ninja
through scoop.
SWIG and python3 are also necessary to build both the NodeJS and python3 bindings.
For the nodeJS bindings, you will need to download and build node-gyp app and put the executable on your path. One way to do this is through npm:
Add the following to your settings.json:
If you are using MSVC to compile, you will need to specify the "Release" build, otherwise you will need a debug version of the Python library. In VSCode, you can use the command pallet option "Cmake: select variant", and choose "Release". If you want to build python bindings with a "Debug" build with visual studios, you will need to create a debug build of the python library to link against.
You can then build and run any number of was through VS Code, such as through the command pallet (search for "build") or by right clicking on the root directories CMakeLists.txt
To build from PowerShell, first you have to import and run the DevShell module:
Then, to build:
Note: -DCMAKE_BUILD_TYPE=Release
is necessary if you are using MSVC and only have the Release version of Python.
To turn on the Python3 and NodeJS bindings, run cmake with the following flags:
All output files on Windows are in the build/bin
directory, as shared libraries must be in the same folder as the executable on windows.
Currently produces the following executable:
To use the python library, navigate to build/bin
:
Or run the script:
NodeJS also has an example dump tree which can be run from the bin folder:
There is basic unit-test infrastructure, for now only available on Linux. To run the tests, simple do make test
after a successful build.
The tests are built by default. To disable them, pass -DACACIA_TESTS=off
to cmake.
After building your targets successfully with make
, simply do:
Use the CMAKE variable CMAKE_INSTALL_PREFIX
to define the root directory where the different artifacts will be placed. For example:
On Linux, the default prefix is /usr/local
.
Before installing, please make sure that the user has write permissions on the destination dir. Also, before using the library from the installation dir, make sure your that <PREFIX>/lib
is added to ld.so configuration. You can do this by adding a file /etc/ld.so.conf.d/
(called, for example, acacia-libs.conf) with the path <PREFIX>/lib
in it, then running ldconfig
.
Not yet supported.
Not yet supported.
Documentation for the different backend APIs can be automatically generated from source code via Doxygen, which must be install locally. It is off by default; to enable it, pass -DACACIA_DOCS=ON
to cmake.
The resulting documentation can be found in: build/docs/docs/html
At present, arrays returned by the underlying c++ functions are not implemented as native JavaScript array objects. They are objects with the follow accessor functions:
equals
size
capacity
reserve
isEmpty
clear
add
get
set
constructor
This is a native C++ library that will eventually abstract the other, platform-specific APIs, so that developers can target a single API regardless of that provided by the platform. This may be useful for some use-cases (e.g, to dump the accessible tree of an application in a cross-platform way).
The feature is governed by the feature flag ACACIA_CAT
, currently OFF by default. To enable it, simply pass -DACACIA_CAT=ON
to cmake.
GNU Library General Public License version 2.1, see LICENSE file.