Motivation: normalization of keysyms header files in `xorgproto`. See:
https://gitlab.freedesktop.org/xorg/proto/xorgproto/-/merge_requests/80
Improve `scripts/makeheader`:
- Simplify `evdev` and `XK_` substitution and improve alignment. Also, perform
some additional `XK_` substitutions in comments.
- Format with `black`.
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.
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.
- 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
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.
Make it use a bit operation instead of an expensive modulo.
perf diff:
Baseline Delta Abs Shared Object Symbol
........ ......... ................. ...................................
28.15% -6.57% bench-compose [.] xkb_keysym_from_name
Signed-off-by: Ran Benita <ran@unusedvar.com>
In 7d84809fdc I added a fast path for the
case-sensitive case, but it is still slowing down Compose parsing.
Instead of the binary search, use a perfect hash function, computed with
a simple python module I found (vendored).
It is faster -- perf diff is:
Baseline Delta Abs Shared Object Symbol
........ ......... ................. ...................................
22.35% -14.04% libc-2.33.so [.] __strcmp_avx2
16.75% +10.28% bench-compose [.] xkb_keysym_from_name
20.72% +2.40% bench-compose [.] parse.constprop.0
2.29% -1.97% bench-compose [.] strcmp@plt
2.56% +1.81% bench-compose [.] resolve_name
2.37% +0.92% libc-2.33.so [.] __GI_____strtoull_l_internal
26.19% -0.63% bench-compose [.] lex
1.45% +0.56% libc-2.33.so [.] __memchr_avx2
1.13% -0.31% libc-2.33.so [.] __strcpy_avx2
Also reduces the binary size:
Before:
text data bss dec hex filename
341111 5064 8 346183 54847 build/libxkbcommon.so.0.0.0
After:
text data bss dec hex filename
330215 5064 8 335287 51db7 build/libxkbcommon.so.0.0.0
Note however that it's still larger than before 7d84809fdccbb5898d08388:
text data bss dec hex filename
320617 5168 8 325793 4f8a1 build/libxkbcommon.so.0.0.0
Signed-off-by: Ran Benita <ran@unusedvar.com>
xkb_keysym_from_name() is called a lot in Compose file parsing. The
lower case handling slows things down a lot (particularly given we can't
use the optimized strcasecmp() due to locale issues). So add separate
handling for the non-case-sensitive case which is used by Compose.
To do this we need to add another version of the ks_tables table. This
adds ~20kb to the shared library binary. We can probably do something
better here but I think it's fine.
Signed-off-by: Ran Benita <ran@unusedvar.com>
As of xorgproto commit 5dbb5b76597f [1], the 0x10081XXX keycode range is defined
for direct evdev kernel keycode mapping. For example, KEY_MACRO1 (0x290) is
mapped to 0x10081290. The format of the #define lines for these keys is
stable to allow for parsing:
#define XF86XK_FooBar _EVDEVK(0x123) /* optional comment */
Update our script so we detect these new lines. Our keysym generation is a
two-step process: makeheader and then makekeys. Replacing the key with its full
value in the makeheader script means we don't have to update makekeys to handle
the _EVDEVK macro and our header file is fully resolved.
[1] https://gitlab.freedesktop.org/xorg/proto/xorgproto/-/merge_requests/23
Signed-off-by: Peter Hutterer <peter.hutterer@who-t.net>
These scripts generate source code that is committed to git and hence do
not really belong in the build system. A maintainer runs them as needed.
Signed-off-by: Ran Benita <ran234@gmail.com>
Pierre Le Marre
Peter Hutterer
Adrian Perez de Castro
Ran Benita
Sebastian Wick
Ran Benita