Preserving customized configuration file settings after applying an update

Resolving The Problem

The compiler introduces a set of new features that allow a customized version of the configuration file to continue to be effective, even after an update has been applied. To accomplish this, the compiler now recognizes both the "system" (default) configuration file shipped with the compiler and any updates, and a "user" configuration file that users can customize and save, The compiler will first process the definitions contained in the user configuration file before looking at the definitions in the system configuration file. In addition, the compiler now supports multiple levels for the use attribute, and allows you to prepend, append, and replace default attribute values.


Specifying the user configuration file
===========================
To instruct the compiler to recognize the "user" configuration file, you must set the following environment variable to specify the name of the file:

- XLC_USR_CONFIG for XL C/C++
- XLF_USR_CONFIG for XL Fortran


Specifying sets of values for configuration file stanzas
========================================
The use attribute is now expanded to support multiple levels (for example, stanza A uses stanza B, B uses stanza C, C uses DEFLT). The following example shows how you can use multiple levels for the use attribute (this example uses the options attribute, but it could apply to any other attributes, such as libraries):

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 <A> and <Z> options.
• stanza B uses <B1>, <B2>, <D>, <A>, and <Z> options
• stanza C uses <C>, <A>, and <Z> options
• stanza D uses <D>, <A>, and <Z> options

Overriding the default order of attribute values
======================================
The user 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 configuration file and then 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 different name from the stanza currently being processed, then the search for the use stanza starts from the beginning of the user configuration file (this is the case for the A, C, and D stanzas in the example above). However, if the stanza in the use attribute has the same name as the stanza currently being processed (as is the case of the B stanzas in the example), then the search for the use stanza starts from the location of the current stanza.

Note that the attributes are processed in the same order as that of the stanzas. The order in which the options are specified is important for option resolution (the last one wins).

By default, any values named for any attribute in the user configuration file are simply added to the list of values specified in previously processed stanzas; that is, For example:

----------USER configuration file (e.g /etc/userconfig1)-----------

xlc:  use=xlc
   options= <A1>

DEFLT: use=DEFLT
   options=<D>
--------------------------------------------------------------------------------------------------------

----SYSTEM configuration file /etc/vac.cfg (shipped with the compiler)----

xlc: use=DEFLT
  options=<A>

DEFLT:
  options=<C>
---------------------------------------------------------------------------------------------------------

If XLC_USR_CONFIG=/etc/userconfig1, then the xlc stanza will use the following options, in the following order:

<A1>, <A>, <D>, <C>

You can override the default order of attribute values by changing the assignment operator(=) for any attribute in the configuration file:
-= prepend the following values before any values determined by the default search order
:= replace any values determined by the default search order with the following values
+= append the following values after any values determined by the default search order

For example:

----------USER configuration file (e.g /etc/userconfig2)-----------

c99_prepend: use=c99
   options-=<B1>

c99_replace:use=c99
   options:=<B2>

c99_append:use=c99
   options+=<B3>

DEFLT: use=DEFLT
   options=<D>
---------------------------------------------------------------------------------------

----SYSTEM configuration file /etc/vac.cfg (shipped with the compiler)----

c99: use=DEFLT
  options=<B>

DEFLT:
  options=<C>
--------------------------------------------------------------------------------------------------------
If XLC_USR_CONFIG=/etc/userconfig2, then the stanzas will use the following options, in the following orders:

c99 uses <B>, <D>, <C>
c99_prepend uses <B1>, <B>, <D>, <C>
c99_replace uses <B2>
c99_append uses <B>, <D>, <C>,<B3>

You can also use the additional assignment operators to specify an attribute more than once. For example:
--------------------------------------------------
xlc:
    use=xlc
    options-=-Isome_include_path
    options+=some options
---------------------------------------------------


Examples of user configuration files
==============================

The following example specifies that the -g option is to be used in all compilations:
-----------------------------
DEFLT: use=DEFLT
   options = -g
-----------------------------

The following example specifies that -qalias=noansi is to be used by default for any compilation invoked by the xlc and xlc_r commands (that is, -qalias=noansi is to override the -qalias=ansi option specified in the system configuration file):
--------------------------------------
xlc: use=xlc
   options+=-qalias=noansi

xlc_r: use=xlc_r
   options+=-qalias=noansi
---------------------------------------

The following example specifies that all compilations should link with /home/user/lib/libmylib.a:
--------------------------------------------------
DEFLT: use=DEFLT
   libraries=-L/home/user/lib,-lmylib
---------------------------------------------------