Creating custom configuration files

If you use the XLF_USR_CONFIG environment variable to instruct the compiler to use a custom user-defined configuration file, the compiler examines and processes the settings in that user-defined configuration file before looking at the settings in the default system configuration file.

To create a custom user-defined configuration file, you add stanzas which specify multiple levels of the use attribute. The user-defined configuration file can reference definitions specified elsewhere in the same file, as well as those specified in the system configuration file. For a given compilation, when the compiler looks for a given stanza, it searches from the beginning of the user-defined configuration file and follows any other stanza named in the use attribute, including those specified in the system configuration file.

If the stanza named in the use attribute has a name different from the stanza currently being processed, the search for the use stanza starts from the beginning of the user-defined configuration file. This is the case for stanzas A, C, and D which you see in the following example. However, if the stanza in the use attribute has the same name as the stanza currently being processed, as is the case of the two B stanzas in the example, the search for the use stanza starts from the location of the current stanza.

The following example shows how you can use multiple levels for the use attribute. This example uses the options attribute to help show how the use attribute works, but any other attributes, such as libraries can also be used.

Figure 1. Sample configuration file

A: use =DEFLT
    options=<set of options A>
B: use =B
    options=<set of options B1>
B: use =D
    options=<set of options B2>
C: use =A
    options=<set of options C>
D: use =A
    options=<set of options D>
DEFLT:
    options=<set of options Z>

In this example:

stanza A uses option sets A and Z

stanza B uses option sets B1, B2, D, A, and Z

stanza C uses option sets C, A, and Z

stanza D uses option sets D, A, and Z

Attributes are processed in the same order as the stanzas. The order in which the options are specified is important for option resolution. Ordinarily, if an option is specified more than once, the last specified instance of that option wins.

By default, values defined in a stanza in a configuration file are added to the list of values specified in previously processed stanzas. For example, assume that the XLF_USR_CONFIG environment variable is set to point to the user-defined configuration file at ~/userconfig1. With the user-defined and default configuration files shown in the following example, the compiler references the xlf stanza in the user-defined configuration file and uses the option sets specified in the configuration files in the following order: A1, A, D, and C.

Figure 2. Custom user-defined configuration file ~/userconfig1

xlf:  use=xlf
    options= <A1>
 
DEFLT: use=DEFLT
    options=<D>

Figure 3. Default configuration file xlf.cfg

xlf:  use=DEFLT
    options=<A>

DEFLT:
    options=<C>

Provide feedback