[PATCH] D94169: [clang][driver] Restore the original help text for `-I`

Fri Jan 8 08:52:45 PST 2021

awarzynski added a comment.

Thank you all for your input. Let me summarize.

**SUGGESTION 1**
Tweak the wording to clarify that it is Clang-specific. That's a good compromise IMO. It highlights that the described semantics apply to Clang only. And I'm not aware of any other way to achieve this right now (i.e. without intrusive refactoring).

**SUGGESTION 2:**
The description of `-I` in `-help` and `ClangCommandLineReference.rst` are made independent of each other (so that `-help` can be tweaked to suit both Clang and Flang).

`ClangCommandLineReference.rst` is basically generated from `Options.td`, so any modification to Options.td will affect the user-facing docs.

>From docs/CMakeLists.txt:

  gen_rst_file_from_td(ClangCommandLineReference.rst -gen-opt-docs ../include/clang/Driver/ClangOptionDocs.td docs-clang-html)

>From ClangOptionDocs.td:

  include "Options.td"

I don't see any straightforward solution here that would allow different descriptions for `-I` in `-help` and in the user-facing docs. Not without completely refactoring how ClangCommandLineReference.rst is produced.

**SUGGESTION 3**
Ideally, we'd have one help message for `-I` for Clang and another one for Flang (in `Options.td`). Unfortunately, AFAIK, there is no easy way to tweak the output of `-help`. The current API is quite inflexible in this respect. This was brought-up at some point last year [1][2]. From the limited feedback I'm guessing that that would also require a major refactor.

**SUGGESTION 4**
We add a new definition for `-I` for Flang, e.g. `def I_for_flang`.

This solves the problem, but adds yet another option definition. Note that `libclangDriver` creates only one global list of all options:

- https://github.com/llvm/llvm-project/blob/80dee7965dffdfb866afa9d74f3a4a97453708b2/clang/lib/Driver/DriverOptions.cpp#L42-L55
- https://github.com/llvm/llvm-project/blob/80dee7965dffdfb866afa9d74f3a4a97453708b2/clang/include/clang/Driver/Options.h#L43-L52

This means that both Flang and Clang will have access to `OPT_I` and `OPT_I_for_flang` (C++ options generated from Options.td). These can be hidden from the user, but will still be available. Also, this would mean the massive table of `libclangDriver` options keeps growing.

Is that how we should proceed moving forward when option names are identical for Clang and Flang, but the semantics are slightly different?

[1] https://lists.llvm.org/pipermail/llvm-dev/2020-July/143745.html
[2] https://lists.llvm.org/pipermail/cfe-dev/2020-October/066953.html

**Few final points**
I would really appreciate a compromise that does not require any major refactoring in Clang at this stage. 
We are ready to add `-I`to Flang and we have a bunch of patches almost ready that depend on it. 
I appreciate that this is just one option, but we are likely to experience more inconsistencies like this in the near future.

Also, for reference, output from  `gcc` and `gfortran`:

  -I <dir>                    Add <dir> to the end of the main include path.

Repository:
  rG LLVM Github Monorepo

CHANGES SINCE LAST ACTION
  https://reviews.llvm.org/D94169/new/

https://reviews.llvm.org/D94169