[cfe-dev] [RFC] Should `clang -help` be refined/improved?

[Andrzej Warzynski via cfe-dev]

Hi all,

We are in the process of adding Flang-specific options to libclangDriver 
and want to make sure that we don't pollute `clang -help` or `flang 
-help` with irrelevant options.

# *PROBLEM IN GENERAL*
I have been looking at clang/include/Driver/Options.td (and various 
files that define/modify/print compiler driver options) and I am not 
sure what the expected implementation and behaviour should be. For 
example, looking at ClangFlags [1], should `clang -help` display options 
flagged as `CC1Option` and `CC1AsOption`?  Shouldn't these be reserved 
for `clang -cc1 -help` and `clang -cc1as -help`, respectively?

What about `DriverOption` and `NoDriverOption`? Based on the 
descriptions in Options.td [2], I would assume that only one of these 
flags is be needed. Also, the current implementation of libclangDriver 
seem to focus on `clang -help` vs `clang-cl -help` split [3]. Lastly, 
`clang -help` prints a lot of options - should all of these be printed?

I'm bringing this up because we want to add Flang-specific options (i.e. 
an option that's printed by `flang -help`, but not printed by `clang 
-help`), and that's proving quite tricky. To this end, we recently have 
submitted a patch that adds yet another item in ClangFlags (see 
`NoClangOption` in [4], still in review!). However, it feels that if 
libclangDriver was stricter about filtering the options (based on the 
flags), we could avoid that.

# *PROBLEM IN DETAIL*
IIUC, libclangDriver should clearly define what flags should be 
included/excluded when passing `-help` to `clang` and other tools. 
Currently this is a bit vague (from Driver.cpp [5]):

```
unsigned IncludedFlagsBitmask = 0;
```

It boils down to "print most of the options available". Wouldn't the 
following, more explicit approach, be preferred (example for `clang`):

```
unsigned IncludedFlagsBitmask =
     options::DriverOption |
     options::NoArgumentUnused |
     options::CoreOption |
     options::LinkOption
```

? However, there's a problem with this approach too: `clang -help` will 
stop working as the definition of `help` contains none of the above 
flags [6]:

```
def help : Flag<["-", "--"], "help">, Flags<[CC1Option,CC1AsOption, 
FC1Option, FlangOption]>,
   HelpText<"Display available options">;
```

This can be fixed by e.g. adding `CoreOption` to the definition above. 
But there will be more options with similar problem. There's also a 
group of options that contain no flags at all (so it's hard to classify 
them). What should happen with them?

# *LLVM's OPTTABLE*
Perhaps we should improve this in LLVM in OptTable.{h|cpp} instead? For 
instance, what's the relation between FlagsToExclude and FlagsToInclude 
[7]? Which one takes precedence? Note that any changes in LLVM's 
OptTable will have impact beyond Clang and Flang, so I don't want dive 
too deep into this in this RFC. But I suspect that refining that API a 
bit could help Clang and Flang.

# *SUGGESTION*
I think that some of these issues could be resolved (or at least 
improved) if:
  * all options defined in clang's Options.td were required to contain a 
flag or otherwise be ignored
  * every flag clearly communicated the mode (e.g. compiler driver vs 
frontend driver) in which particular option is available (i.e. there 
should be no need for `DriverOption` _and_ `NoDriverOption`)
  * every tool (e.g. `clang` or `clang -cc1`) was more explicit about 
the supported options (or, at least, options displayed when passing `-help`)

Do these suggestions make sense? Is my reasoning valid? Or did I get it 
completely wrong? :)

Thanks for reading!
On behalf of the Arm Fortran team,
-Andrzej

[1] 
https://github.com/llvm/llvm-project/blob/25692b7765e2364896a0136f5b54dde3de2dd563/clang/include/clang/Driver/Options.h#L26-L40
[2] 
https://github.com/llvm/llvm-project/blob/25692b7765e2364896a0136f5b54dde3de2dd563/clang/include/clang/Driver/Options.td#L19-L20
[3] 
https://github.com/llvm/llvm-project/blob/25692b7765e2364896a0136f5b54dde3de2dd563/clang/lib/Driver/Driver.cpp#L5261-L5279
[4] https://reviews.llvm.org/D87989
[5] 
https://github.com/llvm/llvm-project/blob/25692b7765e2364896a0136f5b54dde3de2dd563/clang/lib/Driver/Driver.cpp#L5263
[6] 
https://github.com/llvm/llvm-project/blob/master/clang/include/clang/Driver/Options.td#L2131-L2132
[7] 
https://github.com/llvm/llvm-project/blob/25692b7765e2364896a0136f5b54dde3de2dd563/llvm/include/llvm/Option/OptTable.h#L173-L175