[cfe-dev] Configuration files

[Serge Pavlov via cfe-dev]

Thanks to all for feedback!

I tried to summarize the feedback in the form of user-visible description
(possibly a part of user documentation) and random set of development
specific notes.

------ User documentation ------

Using clang as a part of toolchain, especially in the case of
cross-compilation, require setting up large amount of parameters - location
of headers and libraries, set of enabled warnings, triplet names etc.
Changing from debug to release build, or from host processor to accelerator
or any other change of build configuration requires substantial changes of
these parameters. To help maintaining option sets for various build
variants, sets of options may be combined into configurations and stored in
*configuration files*. Selection of particular configuration file activates
all options it represents.

Configuration file may be selected in several ways:
- Using command line option --config,
- By setting up environmental variable CLANGCFG,
- As default configuration.
Only one way may be used. If option ''--config" is specified, CLANGCFG is
not checked and the default configuration is not be applied even if the
requested configuration is not found. Similarly, if variable CLANGCFG
exists, default configuration is never applied.

Command line option --config expects argument either full path to
configuration file, or a name of configuration, for instance:
--config /home/user/cfgs/testing.cfg
--config debug
--config debug.cfg
If full path is specified, options are read from that file. If
configuration is specified by name with optional suffix ".cfg",
corresponding configuration file is searched in the directories in the
following order:
- ~/.llvm
- /etc/llvm

If the option --config is absent, and environment variable CLANGCFG is set,
content of CLANGCFG is used as full path to configuration file. If CLANGCFG
is empty, config file is not used, no diagnostic produced.

If neither --config nor CLANGCFG are specified, default config file is
searched in the following order:
- ~/.llvm/clang.cfg
- /etc/llvm/clang.cfg
- clang.cfg in the directory where clang executable resides.

Configuration file is the sequence of compiler options specified in one or
several lines. Lines started with '#' possibly prepended with space
characters are comments, they are ignored. Lines started with '#" in the
first column immediately followed by ':' are reserved for directives. The
file may reference other files using usual syntax for response files:
@included_file. Example of configuration file:

# Frontend options
-std=c++14 -fcxx-exceptions
# Directories
@include-dirs.cfg
@library-dirs
Name of the active configuration file and options it provided can be
obtained by call of clang with options '-v' or '-###'.

------ End of user documentation ------

Notes:

1. What should be the name of default config file, 'default.cfg' or
'clang.cfg'? If some tool other than clang will use the same mechanism,
name 'clang.cfg' looks more appropriate.
2. Should compiler emit a warning (or even an error) if the specified
configuration file was not found? Obviously absence of default config file
should be silently ignored, as well as empty CLANGCFG variable. But what if
configuration specified by --config is not found? This looks like a severe
error, as user expectation are broken.
3. Default config file may be searched for in  the directory where clang
executable resides. Should configuration specified by --config be searched
in this directory as well? I would say no, because a user who need tuning
configurations may prepare them in home directory or use those provided by
installation in system directories. Ability to place default config into
binary directory is convenient for compiler developer or CI tools, they may
uses several variants of compiler simultaneously.
4. Format of proposed config file is in fact gnu response file. YAML format
mentioned by Richard looks nice but it requires development of proper
parser. I would propose at first implement the simple format. In future
other format can be supported, we can distinguish formats by putting a
directive like '#:format=yaml' or even automatically.
5. Some comments may be reserved for future use. Format directive mentioned
above is an example. The sequence '#:' proposed as marker is absolutely
arbitrary, any other prefix may be used. Now compiler may warn if it sees
such comment. Probably we do not need to bother about the future extensions
now.
6. Using response files in the form @file can imitate include directive. If
a user do not want to copy-and-past pieces of config files, he may
structure them using this feature.


Thanks,
--Serge
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.llvm.org/pipermail/cfe-dev/attachments/20160920/e4adc23f/attachment.html>