This tool checks whether messages codes are supported.
This is useful e.g. for CI, where one may want to grep for some XKB
error codes and ensure that these are still supported.
Currently there is little structure in the log messages, making
difficult to use them for the following use cases:
- A user looking for help about a log message: the user probably
uses a search engine, thus the results will depend on the proper
indexing of our documentation and the various forums. It relies
only on the wording of the message, which may change with time.
- A user wants to filter the logs resulting of the use of one of the
components of xkbcommon. A typical example would be testing
xkeyboard-config against libxkbcommon. It requires the use of a
pattern (simple words detection or regex). The issue is that the
pattern may become silently out-of-sync with xkbcommon.
A common practice (e.g. in compilers) is to assign unique error codes
to reference theses messages, along with an error index for
documentation.
Thus this commit implements the following features:
- Create a message registry (message-registry.yaml) that defines the
log messages produced by xkbcommon. This is a simple YAML file that
provides, for each message:
- A unique numeric code as a short identifier. It is used in the
output message and thus can be easily be filtered to spot errors
or searched in the internet. It must not change: if the
semantics of message changes, it is better to introduce a new
message for clarity.
- A unique text identifier, meant for two uses:
1. Generate constants dealing with log information in our code
base.
2. Generate human-friendly names for the documentation.
- A type: currently warning or error. Used to prefix the constants
(see hereinabove) and for basic classification in documentation.
- A short description, used as concise and mandatory documentation.
- An optionnal detailed description.
- Optional examples, intended to help the user to fix issues
themself.
- Version of xkbcommon it was added. For old entries this often
unknown, so they will default to 1.0.0.
- Version of xkbcommon it was removed (optional)
No entry should ever be deleted from this index, even if the message
is not used anymore: it ensures we have unique identifiers along the
history of xkbcommon, and that users can refer to the documentation
even for older versions.
- Add the script update-message-registry.py to generate the following
files:
- messages.h: message code enumeration for the messages currently
used in the code base. Currently a private API.
- message.registry.md: the error index documentation page.
- Modify the logging functions to use structured messages. This is a
work in progress.
Add an option to print modmap and vmodmap of relevant keys, as well as
virtual modifiers mapping to real modifier. This is useful for debugging.
It uses private API, so we compile it separately in the fashion of
`xkbcli-compile-keymap/compile-keymap`.
The x11 test is currently silently skipped in CI, because it requires a
running X server.
Create a xvfb wrapper to run the test. We do not use `xvfb-run`, because
it is a shell script and it causes valgrind to detect unrelated memory
issues in the shell (dash, bash).
Improve wrapper using a special ELF section
TODO: The wrapper is intended to be used with the x11comp test as well.
The script `ensure-stable-doc-urls.py` relies on the Doxygen output files
names. These may change between Doxygen versions, although the Doxygen
developers intend stability.
Since the script is useful mainly for the online documentation of
xkbcommon, make the target `doc-cool-uris` optional.
Doc URLs may change with time because they depend on Doxygen machinery.
This is unfortunate because it is good practice to keep valid URLs
(see: https://www.w3.org/Provider/Style/URI.html).
I could not find a built-in solution in Doxygen, so the solution proposed
here is to maintain a registry of all URLs and manage legacy URLs as
redirections to their canonical page.
This commit adds a registry of URLs that has three functions:
- Check no previous URL is now invalid.
- Add aliases for moved pages.
- Generate redirection pages for aliases. The redirection works with
a simple <meta http-equiv="refresh"> HTML tag. See:
https://developer.mozilla.org/en-US/docs/Web/HTML/Element/meta#http-equiv
This commit also initialize the URLs registry with current pages and some
redirections needed after recent documentation refactoring.
Finally, the CI is updated to catch any change that invalidate previous
URLs.
At least 2.3 (released 2006) which is the version shipped with macos
doesn't work. Reading the changelog I think 2.3a *should* work, so
require that.
Signed-off-by: Ran Benita <ran@unusedvar.com>
meson needs to know that the executable tools
link against libxkbcommon.dylib so that the
@rpath references used during the build/test phases
can be rewritten to full path names on install
Unlike current xkbcommon, X11’s xkbcomp allows to remove entries in
the modifiers’ map using “modifier_map None { … }”.
“None” is translated to the special value “XkbNoModifier” defined in
“X11/extensions/XKB.h”. Then it relies on the fact that in "CopyModMapDef",
the following code:
1U << entry->modifier
ends up being zero when “entry->modifier” is “XkbNoModifier” (i.e. 0xFF).
Indeed, it relies on the overflow behaviour of the left shift, which in
practice resolves to use only the 5 low bits of the shift amount, i.e.
0x1F here. Then the result of “1U << 0xFF” is cast to “char”, i.e. 0.
This is a good trick but too magical, so in libxkbcommon we will use
an explicit test against our new constant XKB_MOD_NONE.
- Add table of contents
- Add terminology section
- (WIP) Add Introduction to the format
- Improve the keycode section
- Improve the interpret section
- Add guide to create and use modifiers
- (WIP) Add actions documentation
- Add cross-references
- Add keysyms header to documentation
Meson complains; it's probably not that important anymore when using the
`-Db_sanitize` options.
meson.build:36: WARNING: Consider using the built-in option for sanitizers instead of using "-fsanitize-undefined-trap-on-error".
Signed-off-by: Ran Benita <ran@unusedvar.com>
Specify where to find the headers for libxkbcommon_dep,
libxkbcommon_x11_dep, and libxkbregistry_dep, which allows other
projects to correctly locate the headers when libxkbcommon is being
built as a Meson subproject.
The dep_libxkbregistry variable is renamed to libxkbregistry_dep,
to follow the usual convention for variables which hold declared
dependencies to be used from subproject builds.
Arrange for passing .def files with the lists of symbols to export from
DLLs when building on Windows with MSVC. Without this no symbols were
being exported at all.
The .def files are generated from the .map files at build time using
scripts/map-to-def, which avoids needing to maintain two different sets
of files.
I'd really like to use anonymous unions/structs. Supposedly even MSVC
supports it now. Let's try and see.
Signed-off-by: Ran Benita <ran@unusedvar.com>
A simple script that creates a new layout with the given keysym replacing TLDE.
Then we compile a keymap and search for the keysym being assigned to TLDE and
bail if that fails.
The list of keysyms is manually maintained but we only need to add one or two to
spot-check whenever the xorgproto is updated.
Signed-off-by: Peter Hutterer <peter.hutterer@who-t.net>
On every keymap notify event, the keymap should be refreshed, which
fetches the required X11 atoms. A big keymap might have a few hundred of
atoms.
A profile by a user has shown this *might* be slow when some intensive
amount of keymap activity is occurring. It might also be slow on a
remote X server.
While I'm not really sure this is the actual bottleneck, caching the
atoms is easy enough and only needs a couple kb of memory, so do that.
On the added bench-x11:
Before: retrieved 2500 keymaps from X in 11.233237s
After : retrieved 2500 keymaps from X in 1.592339s
Signed-off-by: Ran Benita <ran@unusedvar.com>
mkdtmp, rmdir and unlink are in unstd.h on MacOS. Since including that it
doesn't hurt us on Linux, let's do it without ifdefs.
Signed-off-by: Peter Hutterer <peter.hutterer@who-t.net>
While this tool is useful for users starting with a new keyboard layout, it is a
somewhat bad fit for libxkbcommon. It's the only python tool, we don't even
install it yet (because we're not sure yet what it's supposed to do) and there's
a potential for it to expand into more corner cases.
The only tie it has to libxkbcommon is that it templates the data files that
libxkbcommon reads, but those files are effectively public API.
Let's remove this tool from there and instead move it to a separate git
repository where it can go its own way.
This reverts commit d00cf64dbc
Pierre Le Marre
Ran Benita
Ken Cunningham
Simon Ser
Alex Xu (Hello71)
Adrian Perez de Castro
Peter Hutterer