ARK-OS/arkos/arkrt/libxkbcommon/doc/introspection.md

Recipes for the introspection tool

Installation

[!IMPORTANT] The tools are not yet public, so it is required to build libxkbcommon locally and run them with e.g. meson devenv -C tools/….

The Python dependencies ares:

• PyYAML
• rdflib
• tqdm (optional)

File paths

XKB directories

[!TIP] It is advised to always use explicit XKB directories, denoted XKB_ROOT in the following sections. This avoids any conflict with e.g. personal settings.

Keymap files

File paths are resolved following these rules:

• - corresponds to the standard input stdin.
• If using --section: target section must be present in the file.
• Absolute paths:
  • If using --resolve with --type: file types must match.
• Relative paths:
  • They are resolved relative to the provided XKB directories, unless not using --resolve nor --type. In the former case:
  • --type: file types must match.

Resolve paths

Answers to:

• What file does this include resolves to?

• Where is the file corresponding to a registry entry?

  # TYPE is a KcCGST component
  # FILE is a file name
  # SECTION is a section name in FILE
  
  # Default section
  introspection --include XKB_ROOT --resolve --type TYPE FILE
  # Specific section
  introspection --include XKB_ROOT --resolve --type TYPE --section SECTION FILE
  

List sections

The default output format is YAML, which is handy for analyzing a single file.

# Specific file (absolute path)
introspection --include XKB_ROOT --yaml FILE
# Specific file (relative path)
introspection --include XKB_ROOT --yaml --type TYPE FILE

# Specific file (absolute path) and its transitive dependencies
introspection --include XKB_ROOT --yaml --recursive FILE

# Keymap from RMLVO
xkbcli compile-keymap --kccgst --layout LAYOUT | introspection --include XKB_ROOT --yaml

# XKB tree
introspection-query tree XKB_ROOT -- --yaml --recursive
# XKB tree for a specific type
introspection-query tree XKB_ROOT --type TYPE -- --yaml --recursive

Draw graphs

This section uses the DOT output format.

[!NOTE] DOT is a basic format. Usual conversions:

• SVG: … | dot -Tsvg:cairo > OUTPUT.svg
• PDF: … | dot -Tpdf:cairo > OUTPUT.pdf

# Specific file (absolute path)
introspection --include XKB_ROOT --dot FILE
# Specific file (relative path)
introspection --include XKB_ROOT --dot --type TYPE FILE

# Specific file (absolute path) and its transitive dependencies
introspection --include XKB_ROOT --dot --recursive FILE

# Keymap from RMLVO
xkbcli compile-keymap --kccgst --layout LAYOUT | introspection --include XKB_ROOT --dot

# XKB tree
introspection-query tree XKB_ROOT -- --dot --recursive
# XKB tree for a specific type
introspection-query tree XKB_ROOT --type TYPE -- --dot --recursive

Query

This section uses the RDF Turtle output format and the SPARQL query language.

List dependencies

# Get data about the XKB directories
introspection-query tree XKB_ROOT -- --rdf --recursive > /tmp/tree.ttl
# Query direct dependencies
introspection-query deps --include XKB_ROOT --type TYPE --file FILE --section SECTION /tmp/tree.ttl
# Query all dependencies
introspection-query deps --include XKB_ROOT --type TYPE --file FILE --section SECTION --transitive /tmp/tree.ttl

List unused files/sections

# Get data about the XKB directories
introspection-query tree XKB_ROOT -- --rdf --recursive > /tmp/tree.ttl
# Analyze a ruleset
RULES=evdev; introspection-query rules --rules $RULES --rdf --output /tmp/$RULES.ttl XKB_ROOT
# Get the unused items for a specific ruleset
RULES=evdev; cat /tmp/tree.ttl /tmp/$RULES.ttl | introspection-query use --include XKB_ROOT --unused -
# Get the unused items for multiple rulesets
cat /tmp/tree.ttl /tmp/base.ttl /tmp/evdev.ttl | introspection-query use --include XKB_ROOT --unused -