[PATCH] D24933: Enable configuration files in clang

Sat Oct 7 22:32:19 PDT 2017

hfinkel added a comment.

Some suggested improvements to the English in the documentation...

================
Comment at: docs/UsersManual.rst:700
+
+Configuration files group command line options and allow to specify all of
+them just by referencing the configuration file. They may be used, for
----------------
Configuration files group command-line options and allow all of them to be specified just by ...

================
Comment at: docs/UsersManual.rst:702
+them just by referencing the configuration file. They may be used, for
+instance, to collect options required to tune compilation for particular
+target, such as -L, -I, -l, --sysroot, codegen options etc.
----------------
instance -> example

"for instance" and "for example" are essentially the same, but for consistency, "for example" is much more common in this document, so we should standardize.

================
Comment at: docs/UsersManual.rst:703
+instance, to collect options required to tune compilation for particular
+target, such as -L, -I, -l, --sysroot, codegen options etc.
+
----------------
options, etc.

================
Comment at: docs/UsersManual.rst:706
+The command line option `--config` can be used to specify configuration
+file in a Clang invocation. For instance:
+
----------------
instance -> example

================
Comment at: docs/UsersManual.rst:714
+If the provided argument contains a directory separator, it is considered as
+a file path, options are read from that file. Otherwise the argument is treated
+as a file name and is searched for sequentially in the directories:
----------------
and options are

================
Comment at: docs/UsersManual.rst:719
+    - the directory where Clang executable resides.
+Both user and system directory for configuration files are specified during
+clang build using cmake parameters, CLANG_CONFIG_FILE_USER_DIR and
----------------
directory -> directories

================
Comment at: docs/UsersManual.rst:720
+Both user and system directory for configuration files are specified during
+clang build using cmake parameters, CLANG_CONFIG_FILE_USER_DIR and
+CLANG_CONFIG_FILE_SYSTEM_DIR respectively. The first found file is used. It is
----------------
cmake -> CMake

================
Comment at: docs/UsersManual.rst:721
+clang build using cmake parameters, CLANG_CONFIG_FILE_USER_DIR and
+CLANG_CONFIG_FILE_SYSTEM_DIR respectively. The first found file is used. It is
+an error if the required file cannot be found.
----------------
The first file found is used.

================
Comment at: docs/UsersManual.rst:724
+
+Another way to specify configuration file is to encode it in executable name. For
+instance, if Clang executable is named `armv7l-clang` (it may be a symbolic link
----------------
specify a configuration file

================
Comment at: docs/UsersManual.rst:725
+Another way to specify configuration file is to encode it in executable name. For
+instance, if Clang executable is named `armv7l-clang` (it may be a symbolic link
+to `clang`), then Clang will search file `armv7l.cfg` in the directory where Clang
----------------
if the Clang executable

================
Comment at: docs/UsersManual.rst:726
+instance, if Clang executable is named `armv7l-clang` (it may be a symbolic link
+to `clang`), then Clang will search file `armv7l.cfg` in the directory where Clang
+resides.
----------------
will search for file

================
Comment at: docs/UsersManual.rst:729
+
+If driver mode is specified in invocation, Clang tries to find file specific for
+the specified mode. For instance, if executable file is `x86_64-clang-cl`, Clang
----------------
If a driver mode

================
Comment at: docs/UsersManual.rst:729
+
+If driver mode is specified in invocation, Clang tries to find file specific for
+the specified mode. For instance, if executable file is `x86_64-clang-cl`, Clang
----------------
hfinkel wrote:
> If a driver mode
to find a file

================
Comment at: docs/UsersManual.rst:730
+If driver mode is specified in invocation, Clang tries to find file specific for
+the specified mode. For instance, if executable file is `x86_64-clang-cl`, Clang
+first looks for `x86_64-cl.cfg` and if it is not found, looks for `x86_64.cfg'.
----------------
if the executable is named `x86_64-clang-cl`

================
Comment at: docs/UsersManual.rst:733
+
+If command line contains options that effectively changes target architecture
+(these are -m32, -EL and some other) and configuration file starts with architecture
----------------
If the command line

================
Comment at: docs/UsersManual.rst:733
+
+If command line contains options that effectively changes target architecture
+(these are -m32, -EL and some other) and configuration file starts with architecture
----------------
hfinkel wrote:
> If the command line
changes -> change

================
Comment at: docs/UsersManual.rst:734
+If command line contains options that effectively changes target architecture
+(these are -m32, -EL and some other) and configuration file starts with architecture
+name, Clang tries to load config file for effective architecture. For instance,
----------------
-EL, and some others

================
Comment at: docs/UsersManual.rst:734
+If command line contains options that effectively changes target architecture
+(these are -m32, -EL and some other) and configuration file starts with architecture
+name, Clang tries to load config file for effective architecture. For instance,
----------------
hfinkel wrote:
> -EL, and some others
and the configuration file starts with an architecture name

================
Comment at: docs/UsersManual.rst:735
+(these are -m32, -EL and some other) and configuration file starts with architecture
+name, Clang tries to load config file for effective architecture. For instance,
+invocation:
----------------
load the configuration file for the effective

================
Comment at: docs/UsersManual.rst:735
+(these are -m32, -EL and some other) and configuration file starts with architecture
+name, Clang tries to load config file for effective architecture. For instance,
+invocation:
----------------
hfinkel wrote:
> load the configuration file for the effective
instance -> example

================
Comment at: docs/UsersManual.rst:742
+
+makes Clang to search file `i368.cfg` first, and if it is not found, Clang looks
+for the file `x86_64.cfg`.
----------------
causes Clang search for a file named `i368.cfg` first, and if no such file is found, Clang looks for the file `x86_64.cfg`.

================
Comment at: docs/UsersManual.rst:745
+
+The configuration file consists of command line options specified on one or several
+lines. Lines composed of whitespace characters only are ignored as well as lines in
----------------
command-line options

================
Comment at: docs/UsersManual.rst:745
+
+The configuration file consists of command line options specified on one or several
+lines. Lines composed of whitespace characters only are ignored as well as lines in
----------------
hfinkel wrote:
> command-line options
several -> more

(several generally implies more than two, so saying "one or several" actually excludes two)

================
Comment at: docs/UsersManual.rst:748
+which the first non-blank character is `#`. Long options may be split between several
+lines by trailing backslash. Here is an example of config file:
+
----------------
by a trailing

================
Comment at: docs/UsersManual.rst:748
+which the first non-blank character is `#`. Long options may be split between several
+lines by trailing backslash. Here is an example of config file:
+
----------------
hfinkel wrote:
> by a trailing
example of a configuration file

================
Comment at: docs/UsersManual.rst:762
+
+Files included by directives `@file` in configuration files are resolved relative to
+the including file. For instance if a config file `~/.llvm/target.cfg` contains
----------------
included by `@file` directives

================
Comment at: docs/UsersManual.rst:763
+Files included by directives `@file` in configuration files are resolved relative to
+the including file. For instance if a config file `~/.llvm/target.cfg` contains
+directive `@os/linux.opts`, the file `linux.opts` is searched for in the directory
----------------
For example, if a configuration file

================
Comment at: docs/UsersManual.rst:763
+Files included by directives `@file` in configuration files are resolved relative to
+the including file. For instance if a config file `~/.llvm/target.cfg` contains
+directive `@os/linux.opts`, the file `linux.opts` is searched for in the directory
----------------
hfinkel wrote:
> For example, if a configuration file
contains the directive

https://reviews.llvm.org/D24933