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

Tue Oct 13 13:00:53 PDT 2020

On Tue, Oct 13, 2020 at 12:29 PM Reid Kleckner via cfe-dev
<cfe-dev at lists.llvm.org> wrote:
>
> +Hans
>
> I think Hans and I are the ones most responsible for the behavior of clang-cl --help. For our part, we made sure that clang-cl --help prints something useful, but did our best to leave the rest of the existing mess alone. If you make changes, please check that the clang-cl --help output remains as useful as possible, since we have made an effort to curate that with help text.
>
> I think any changes you propose in this area will probably be an improvement over the current situation.
>
> I would encourage you to try to improve the LLVM Option library if you can, but obviously it's always not straightforward. Most of the other clients (some LLVM tools, LLD) are pretty simple and easy to update for new APIs.
>
> On Wed, Oct 7, 2020 at 12:33 PM Andrzej Warzynski via cfe-dev <cfe-dev at lists.llvm.org> wrote:
>>
>> 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?

The use of DriverOption is very confusing. It served two purposes (1)
whether an option should be forwarded to gcc (for baremetal toolchain)
(2) whether an option should be forwarded for -Xarch -Xarch_host
-Xarch_device (macOS and CUDA use cases)

I have refactored (1) to use a new TableGen def 'LinkOption'. Now
DriverOption's only purpose is (2). CCed Artem who may know (2)

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

AFAIK the only users of OptTable are: clang (clang-cl), lld (lld-link,
ld.lld, wasm-ld), and llvm-symbolizer.
You can check whether their -help output changes with your refactoring.

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

-- 
宋方睿