[cfe-dev] Configuration files

Tue Sep 27 11:58:48 PDT 2016

----- Original Message -----
> From: "Matthias Braun via cfe-dev" <cfe-dev at lists.llvm.org>
> To: "Serge Pavlov" <sepavloff at gmail.com>
> Cc: "Richard Smith" <richard at metafoo.co.uk>, "Clang Dev" <cfe-dev at lists.llvm.org>
> Sent: Tuesday, September 27, 2016 1:45:09 PM
> Subject: Re: [cfe-dev] Configuration files
> 
> 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)

I agree with both points.

> - Automatically picking up options from user or system configuration
> files is too dangerous IMO!

There are definitely good user-experience reasons to want to do this - It might be nice to have some global configuration file that causes Clang to default to using -march=native or use some particular include path (setting CPATH and friends often works, but can also be flaky). The problem is indeed build system interaction, dealing with incompatible options, etc. For many things our last-option-wins scheme will do the right thing, but it is not clear, for example, that -nostdinc would have the expected effect if the config file adds include paths.

 -Hal

> 
> - Matthias
> 
> > 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
> > 	@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
> > 
> > _______________________________________________
> > cfe-dev mailing list
> > cfe-dev at lists.llvm.org
> > http://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-dev
> 
> _______________________________________________
> cfe-dev mailing list
> cfe-dev at lists.llvm.org
> http://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-dev
> 

-- 
Hal Finkel
Lead, Compiler Technology and Programming Languages
Leadership Computing Facility
Argonne National Laboratory