en/LXR lxr.conf Dynamic Path Transformation

The rewrite rules allow dynamic modification of the include paths. They are preferentially used for trees describing a multi-target application (think of an OS kernel running on many hardware architectures or of a compiler with several code generators).

To be fully operational, the rewrite rules are used in conjunction with 'variables' substitution. The variable value points to directories or contains part of directory name.

Up to version 0.11 , 'maps' => { source_pattern => replacement, ... } The application order of the rules is unpredictable and vary from one LXR invocation to the next. This Perl feature causes serious issues when rules are designed to profit from their cumulative effect.
Version 1.0 or higher , 'maps' => [ source_pattern => replacement, ... ] The rules are applied in the order where they are written.

CAUTION! Using the inadequate syntax is not detected at configuration time but causes an error only when the 'maps' are activated. Consequently the bug can go unnoticed for a long period of time before happening.

source_pattern
is a Perl pattern without delimiters. It is strongly recommended to surround it with path delimiters to avoid matching inadvertantly a part only of a directory name instead of the full name (unless this is the expected result, of course).
replacement
provides the replacement string for the matched pattern. It may substitute text from variables if it includes occurrences of $var_name.

Example (with the [] syntax):

We define a target variable to contain the name of the target architecture for our application (considering this name is part of the directory names):

, 'variables' => { 'v' => ... # Version list , 'target' => { 'name' => 'Target architecture' , 'range' => [qw(intel ppc m68k)] } }

Supposing that the include directives are written as #include "asm/file.h" and there is a set of 'target' asm-xxx directories in /include, we'll get the right hyperlinks with:

, 'incprefix' => [ '/include' ] , 'maps' => [ '\/asm[^\/]*\/' => '\/asm-$target\/' ]

Notes

Escape the special characters
You do not know the pattern context within LXR; to avoid syntax errors caused by premature end of pattern, systematically escape all special litteral characters.
The above 'maps' has a wider capture range than required
The pattern will catch any directory name starting with asm (such as asm, asm.backup, etc.) and replace it with asm-xxx. If you really want to transform only a path strictly defined by the requirement, use pattern \/include\/asm\/.
You change the hyperlink by clicking on the desired value of the variable(s)
Remember that the variable values are displayed in the header of the page as a set of clickables "buttons". Click on one (or select a value from the drop-down menu and click the Change button) and the hyperlinks are recomputed.

Another example (with the [] syntax):

This example gives first-level rules to resolve the #include directives in the Linux kernels 2.x and 3.x.

The referenced files are stored in directories /include and /arch for architecture-independent and architecture-dependent files respectively.

The arch/ directory is itself structured not to restrict what can be stored inside. The #included files are found in an include/ subdirectory of the architecture-specific subtree as /arch/xxx/include/asm/yyy.h where xxx is replaced by the architecture name. They are referenced from source code as #include "asm/yyy.h".

Traditionally, the kernel uses variable a for the target architecture. The intended result will be obtained with the following parameters in lxr.conf:

, 'variables' => { 'v' => ... # Version list , 'a' => { 'name' => 'Target architecture' , 'range' => [qw(x86 intel ppc m68k)] # and many more } } , 'incprefix' => [ '/include', '/arch/%=ARCH=%/include' ] , 'maps' => [ '\/arch\/%=ARCH=%\/' => '\/arch\/$a\/' ] The %=ARCH=% above is no magic identifier. It has only been chose as a placeholder with a name thought never to occur as a directory name in the kernel tree. It is of utmost importance to use a never-to-be-seen symbol (thus the % and = characters in the name) otherwise some unforeseen substitutions may happen with surprising results.

The Linux kernel uses one of the most complex configuration management system of the open source world. To cope with sub-architecture variants needs more variable definitions and more 'incprefix' and 'maps' rules. Configuring LXR for the kernel deserves a full chapter.

Refer to the Tips section for two non-trivial examples of rewrite rules.