[cfe-dev] Quick RFC about some consistency guidelines for the Clang driver

[Chandler Carruth]

I've run into a large number of cases recently where the inconsistencies
and patterns of flags in the Clang driver cause folks building and
supporting toolchains including Clang grief (due to lack of controls), as
well as causing user confusion and misunderstanding. I would like to fix
many of these cases, but before doing so I wanted to see if we could reach
consensus on some general guidelines for how to name and make consistent
flags in Clang's driver.

1) The goal of Clang's driver is to be drop-in compatible with GCC in many
(most?) situations. This often trumps all other concerns, so I list it
first.

2) GCC's commandline syntax establishes some nice consistent naming
patterns that I think it is worthwhile for Clang to continue following
where suitable. While Clang is not GCC, and they needn't go the same
direction, developers on Unix-y systems have largely internalized these
patterns, and so we might as well leverage this. These are modeled as
'option group's for Clang flags that provide common semantic buckets. When
adding a flag that fits into one of these buckets, these option groups and
the accompanying syntax should be used. For example, a flag changing the
language's semantic model shoulf be in the 'f_Group', and should be spelled
'-fmy-special-feature'.

3) For flags which the driver accepts as high-level "toolchain" style
options, and consequentially don't fit in any of the existing option groups
(or have i missed one?), prefer a double-dash syntax to distinguish them:
'--gcc-toolchain' for example to tell the driver where to find a GCC
toolchain. Note that how we spell this is a bikeshed, but I think it is
somewhat pointless to try to paint this bikeshed in a color other than
double-dash given the prevalence of it in the Unix world these days.

4) All boolean flags should be reversible by adding a complemented flag
spelling. This is particularly important when building up multi-system
build configurations where you may not have the ability to edit a lower
level configuration's option set, but you can append new options.

5) All flags should provide at least a "joined" spelling when they accept a
value. This can often significantly simplify life when trying to properly
quote and group options in build configurations. Unless there is some
unusual reason to deviate, the pattern should be:
  - If the flag is a single letter, double letter, or 'sigil' and the
joined form has no '=' or other marker, it should be JoinedOrSeparate. This
follows the syntax used by '-I'.
  - Otherwise, the flag is text and would need a '=' character in the
joined form, only the joined form should be provided.
While this would be a deviation from the current flag syntax, I think it is
a much healthier path forward, and we can always grandfather in existing
flags as necessary.

6) Existing spellings should be preserved and kept working going forward.
(Duh...)


Does this seem like a reasonable direction? Any vehement objections? I'd
really like to start work making #3, #4, and #5 true as they are blocking
some of my use cases, but I don't want to create confusion by starting down
this path without general agreement.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.llvm.org/pipermail/cfe-dev/attachments/20130615/af87f32e/attachment.html>