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

Tue Oct 13 12:29:05 PDT 2020

+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?
>
> 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
> _______________________________________________
> cfe-dev mailing list
> cfe-dev at lists.llvm.org
> https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-dev
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.llvm.org/pipermail/cfe-dev/attachments/20201013/aa93fe53/attachment.html>