Quick RFC about some consistency guidelines for the Clang driver

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.
  1. 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.

This sounds reasonable to me.

Me too, though I worry there will be too many legacy flags laying around
for too long. Maybe we should mark all non-conforming current flags as
deprecated as soon as we get the new naming system implemented and remove
it a few releases down the road.

cheers,
--renato

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.

I'd put this different: If the interface exposed by GCC is consistent
(with other options and across different versions), we want to stay
compatible with it. If it is not consistent across versions and the
current versions make sense, we want to be compatible with that.

2) GCC's commandline syntax establishes some nice consistent naming
patterns that I think it is worthwhile for Clang to continue following
where suitable.

I agree for the -W (warning), -m and -f option groups. -g needs some
thought first and -O is a problem of its own.

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.

An alternative would be to have a --driver-var=value style. This might
more naturally translate into an (optional) configuration file later?

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.

One issue I have with the way clang behaves here is that it is not
always easy to append new options. From a build system perspective, many
source distributions in the wild append -Wall -Werror to the
CFLAGS/CXXFLAGS specified by the other and clang's behavior makes this a
lot more difficult to deal with. It would be nice to have a sticky way
to override following group flags. Something like
  -Wreallly-no-error=cast-align -Werror -Wall
as an example. I'm quite sure the FreeBSD folks will agree with me on
this.

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'.

I'd reserve this class for existing historic practise. No new flags
should be added here.

  - Otherwise, the flag is text and would need a '=' character in the
joined form, only the joined form should be provided.

Agreed.

There is one other form in use that should be reserved for this kind of
push-through usage (-Wp, -Wl, -Wa etc) and keeping this separate feels
acceptable to me. It should be explicitly mentioned that the first '='
character is the option separator.

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

It might be acceptable to clean up the list once and start an obsoletion
process now, but generally this tends to be more painful than it helps.
See history of -m486 vs -march=486 with GCC.

Joerg