[cfe-dev] Configuration files
Matthias Braun via cfe-dev
cfe-dev at lists.llvm.org
Tue Sep 27 11:45:09 PDT 2016
Sorry for being late to the discussion,
I think automatic user defaults are a bad idea: Right now when you invoke clang without any additional options you know that you are in a well known state. Build systems and projects rely on this having unknown compiler options active because the user put them into his configuration file is a recipe for disaster IMO! The example below "-std=c++14 -fcxx-exception" already illustrates a situation in which settings are used that can break the compilation of many projects!
- I'm fine with a commandline option triggering reading a config file (@file)
- Using a different executable name/symlinks to trigger loading of config files may be fine as well (build systems should not pick up myarch-clang by accident)
- Automatically picking up options from user or system configuration files is too dangerous IMO!
> On Sep 20, 2016, at 12:13 AM, Serge Pavlov via cfe-dev <cfe-dev at lists.llvm.org> wrote:
> 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
> 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 ------
> 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.
> cfe-dev mailing list
> cfe-dev at lists.llvm.org
More information about the cfe-dev