[Option] Add "Visibility" field and clone the OptTable APIs to use it

This splits OptTable's "Flags" field into "Flags" and "Visibility",
updates the places where we instantiate Option tables, and adds
variants of the OptTable APIs that use Visibility mask instead of
Include/Exclude flags.

We need to do this to clean up a bunch of complexity in the clang
driver's option handling - there's a whole slew of flags like
CoreOption, NoDriverOption, and FlangOnlyOption there today to try to
handle all of the permutations of flags that the various drivers need,
but it really doesn't scale well, as can be seen by things like the
somewhat recently introduced CLDXCOption.

Instead, we'll provide an additive model for visibility that's
separate from the other flags. For things like "HelpHidden", which is
used as a "subtractive" modifier for option visibility, we leave that
in "Flags" and handle it as a special case.

Note that we don't actually update the users of the Include/Exclude
APIs here or change the flags that exist in clang at all - that will
come in a follow up that refactors clang's Options.td to use the
increased flexibility this change allows.

Differential Revision: https://reviews.llvm.org/D157149

Author: bogner

clang-tools-extra/clangd/CompileCommands.cpp

@@ -494,7 +494,7 @@ llvm::ArrayRef<ArgStripper::Rule> ArgStripper::rulesFor(llvm::StringRef Arg) {
   static constexpr llvm::ArrayRef<llvm::StringLiteral> NAME(                   \
       NAME##_init, std::size(NAME##_init) - 1);
 #define OPTION(PREFIX, PREFIXED_NAME, ID, KIND, GROUP, ALIAS, ALIASARGS,       \
-               FLAGS, PARAM, HELP, METAVAR, VALUES)                            \
+               FLAGS, VISIBILITY, PARAM, HELP, METAVAR, VALUES)                \
   Prefixes[DriverID::OPT_##ID] = PREFIX;
 #include "clang/Driver/Options.inc"
 #undef OPTION
@@ -506,7 +506,7 @@ llvm::ArrayRef<ArgStripper::Rule> ArgStripper::rulesFor(llvm::StringRef Arg) {
       const void *AliasArgs;
     } AliasTable[] = {
 #define OPTION(PREFIX, PREFIXED_NAME, ID, KIND, GROUP, ALIAS, ALIASARGS,       \
-               FLAGS, PARAM, HELP, METAVAR, VALUES)                            \
+               FLAGS, VISIBILITY, PARAM, HELP, METAVAR, VALUES)                \
   {DriverID::OPT_##ID, DriverID::OPT_##ALIAS, ALIASARGS},
 #include "clang/Driver/Options.inc"
 #undef OPTION

clang/lib/Frontend/CompilerInvocation.cpp

@@ -423,9 +423,9 @@ static T extractMaskValue(T KeyPath) {
 
 #define PARSE_OPTION_WITH_MARSHALLING(                                         \
     ARGS, DIAGS, PREFIX_TYPE, SPELLING, ID, KIND, GROUP, ALIAS, ALIASARGS,     \
-    FLAGS, PARAM, HELPTEXT, METAVAR, VALUES, SHOULD_PARSE, ALWAYS_EMIT,        \
-    KEYPATH, DEFAULT_VALUE, IMPLIED_CHECK, IMPLIED_VALUE, NORMALIZER,          \
-    DENORMALIZER, MERGER, EXTRACTOR, TABLE_INDEX)                              \
+    FLAGS, VISIBILITY, PARAM, HELPTEXT, METAVAR, VALUES, SHOULD_PARSE,         \
+    ALWAYS_EMIT, KEYPATH, DEFAULT_VALUE, IMPLIED_CHECK, IMPLIED_VALUE,         \
+    NORMALIZER, DENORMALIZER, MERGER, EXTRACTOR, TABLE_INDEX)                  \
   if ((FLAGS)&options::CC1Option) {                                            \
     KEYPATH = MERGER(KEYPATH, DEFAULT_VALUE);                                  \
     if (IMPLIED_CHECK)                                                         \
@@ -440,9 +440,9 @@ static T extractMaskValue(T KeyPath) {
 // with lifetime extension of the reference.
 #define GENERATE_OPTION_WITH_MARSHALLING(                                      \
     CONSUMER, PREFIX_TYPE, SPELLING, ID, KIND, GROUP, ALIAS, ALIASARGS, FLAGS, \
-    PARAM, HELPTEXT, METAVAR, VALUES, SHOULD_PARSE, ALWAYS_EMIT, KEYPATH,      \
-    DEFAULT_VALUE, IMPLIED_CHECK, IMPLIED_VALUE, NORMALIZER, DENORMALIZER,     \
-    MERGER, EXTRACTOR, TABLE_INDEX)                                            \
+    VISIBILKITY, PARAM, HELPTEXT, METAVAR, VALUES, SHOULD_PARSE, ALWAYS_EMIT,  \
+    KEYPATH, DEFAULT_VALUE, IMPLIED_CHECK, IMPLIED_VALUE, NORMALIZER,          \
+    DENORMALIZER, MERGER, EXTRACTOR, TABLE_INDEX)                              \
   if ((FLAGS)&options::CC1Option) {                                            \
     [&](const auto &Extracted) {                                               \
       if (ALWAYS_EMIT ||                                                       \

lld/MachO/DriverUtils.cpp

@@ -44,9 +44,13 @@ using namespace lld::macho;
 
 // Create table mapping all options defined in Options.td
 static constexpr OptTable::Info optInfo[] = {
-#define OPTION(X1, X2, ID, KIND, GROUP, ALIAS, X7, X8, X9, X10, X11, X12)      \
-  {X1, X2, X10,         X11,         OPT_##ID, Option::KIND##Class,            \
-   X9, X8, OPT_##GROUP, OPT_##ALIAS, X7,       X12},
+#define OPTION(PREFIX, NAME, ID, KIND, GROUP, ALIAS, ALIASARGS, FLAGS,         \
+               VISIBILITY, PARAM, HELPTEXT, METAVAR, VALUES)                   \
+  {PREFIX,      NAME,        HELPTEXT,                                         \
+   METAVAR,     OPT_##ID,    opt::Option::KIND##Class,                         \
+   PARAM,       FLAGS,       VISIBILITY,                                       \
+   OPT_##GROUP, OPT_##ALIAS, ALIASARGS,                                        \
+   VALUES},
 #include "Options.inc"
 #undef OPTION
 };

lld/MinGW/Driver.cpp

@@ -71,9 +71,13 @@ enum {
 
 // Create table mapping all options defined in Options.td
 static constexpr opt::OptTable::Info infoTable[] = {
-#define OPTION(X1, X2, ID, KIND, GROUP, ALIAS, X7, X8, X9, X10, X11, X12)      \
-  {X1, X2, X10,         X11,         OPT_##ID, opt::Option::KIND##Class,       \
-   X9, X8, OPT_##GROUP, OPT_##ALIAS, X7,       X12},
+#define OPTION(PREFIX, NAME, ID, KIND, GROUP, ALIAS, ALIASARGS, FLAGS,         \
+               VISIBILITY, PARAM, HELPTEXT, METAVAR, VALUES)                   \
+  {PREFIX,      NAME,        HELPTEXT,                                         \
+   METAVAR,     OPT_##ID,    opt::Option::KIND##Class,                         \
+   PARAM,       FLAGS,       VISIBILITY,                                       \
+   OPT_##GROUP, OPT_##ALIAS, ALIASARGS,                                        \
+   VALUES},
 #include "Options.inc"
 #undef OPTION
 };

lld/wasm/Driver.cpp

@@ -111,9 +111,13 @@ bool link(ArrayRef<const char *> args, llvm::raw_ostream &stdoutOS,
 
 // Create table mapping all options defined in Options.td
 static constexpr opt::OptTable::Info optInfo[] = {
-#define OPTION(X1, X2, ID, KIND, GROUP, ALIAS, X7, X8, X9, X10, X11, X12)      \
-  {X1, X2, X10,         X11,         OPT_##ID, opt::Option::KIND##Class,       \
-   X9, X8, OPT_##GROUP, OPT_##ALIAS, X7,       X12},
+#define OPTION(PREFIX, NAME, ID, KIND, GROUP, ALIAS, ALIASARGS, FLAGS,         \
+               VISIBILITY, PARAM, HELPTEXT, METAVAR, VALUES)                   \
+  {PREFIX,      NAME,        HELPTEXT,                                         \
+   METAVAR,     OPT_##ID,    opt::Option::KIND##Class,                         \
+   PARAM,       FLAGS,       VISIBILITY,                                       \
+   OPT_##GROUP, OPT_##ALIAS, ALIASARGS,                                        \
+   VALUES},
 #include "Options.inc"
 #undef OPTION
 };

llvm/include/llvm/Option/OptParser.td

@@ -73,6 +73,13 @@ def RenderJoined : OptionFlag;
 // (only sensible on joined options).
 def RenderSeparate : OptionFlag;
 
+// Define Visibility categories
+
+class OptionVisibility {}
+
+// Explicit specifier for default visibility
+def Default : OptionVisibility;
+
 // Define the option group class.
 
 class OptionGroup<string name> {
@@ -81,6 +88,7 @@ class OptionGroup<string name> {
   string HelpText = ?;
   OptionGroup Group = ?;
   list<OptionFlag> Flags = [];
+  list<OptionVisibility> Vis = [];
 }
 
 // Define the option class.
@@ -97,6 +105,7 @@ class Option<list<string> prefixes, string name, OptionKind kind> {
   string Values = ?;
   code ValuesCode = ?;
   list<OptionFlag> Flags = [];
+  list<OptionVisibility> Vis = [Default];
   OptionGroup Group = ?;
   Option Alias = ?;
   list<string> AliasArgs = [];
@@ -141,6 +150,7 @@ class Alias<Option alias> { Option Alias = alias; }
 class AliasArgs<list<string> aliasargs> { list<string> AliasArgs = aliasargs; }
 class EnumName<string name> { string EnumName = name; }
 class Flags<list<OptionFlag> flags> { list<OptionFlag> Flags = flags; }
+class Vis<list<OptionVisibility> vis> { list<OptionVisibility> Vis = vis; }
 class Group<OptionGroup group> { OptionGroup Group = group; }
 class HelpText<string text> { string HelpText = text; }
 class MetaVarName<string name> { string MetaVarName = name; }

llvm/include/llvm/Option/OptTable.h

@@ -30,6 +30,18 @@ class ArgList;
 class InputArgList;
 class Option;
 
+/// Helper for overload resolution while transitioning from
+/// FlagsToInclude/FlagsToExclude APIs to VisibilityMask APIs.
+class Visibility {
+  unsigned Mask = ~0U;
+
+public:
+  explicit Visibility(unsigned Mask) : Mask(Mask) {}
+  Visibility() = default;
+
+  operator unsigned() const { return Mask; }
+};
+
 /// Provide access to the Option info table.
 ///
 /// The OptTable class provides a layer of indirection which allows Option
@@ -51,6 +63,7 @@ class OptTable {
     unsigned char Kind;
     unsigned char Param;
     unsigned int Flags;
+    unsigned int Visibility;
     unsigned short GroupID;
     unsigned short AliasID;
     const char *AliasArgs;
@@ -180,10 +193,8 @@ class OptTable {
   /// string includes prefix dashes "-" as well as values "=l".
   /// \param [out] NearestString - The nearest option string found in the
   /// OptTable.
-  /// \param [in] FlagsToInclude - Only find options with any of these flags.
-  /// Zero is the default, which includes all flags.
-  /// \param [in] FlagsToExclude - Don't find options with this flag. Zero
-  /// is the default, and means exclude nothing.
+  /// \param [in] VisibilityMask - Only include options with any of these
+  ///                              visibility flags set.
   /// \param [in] MinimumLength - Don't find options shorter than this length.
   /// For example, a minimum length of 3 prevents "-x" from being considered
   /// near to "-S".
@@ -192,13 +203,29 @@ class OptTable {
   ///
   /// \return The edit distance of the nearest string found.
   unsigned findNearest(StringRef Option, std::string &NearestString,
-                       unsigned FlagsToInclude = 0, unsigned FlagsToExclude = 0,
+                       Visibility VisibilityMask = Visibility(),
                        unsigned MinimumLength = 4,
                        unsigned MaximumDistance = UINT_MAX) const;
 
+  unsigned findNearest(StringRef Option, std::string &NearestString,
+                       unsigned FlagsToInclude, unsigned FlagsToExclude = 0,
+                       unsigned MinimumLength = 4,
+                       unsigned MaximumDistance = UINT_MAX) const;
+
+private:
+  unsigned
+  internalFindNearest(StringRef Option, std::string &NearestString,
+                      unsigned MinimumLength, unsigned MaximumDistance,
+                      std::function<bool(const Info &)> ExcludeOption) const;
+
+public:
+  bool findExact(StringRef Option, std::string &ExactString,
+                 Visibility VisibilityMask = Visibility()) const {
+    return findNearest(Option, ExactString, VisibilityMask, 4, 0) == 0;
+  }
+
   bool findExact(StringRef Option, std::string &ExactString,
-                 unsigned FlagsToInclude = 0,
-                 unsigned FlagsToExclude = 0) const {
+                 unsigned FlagsToInclude, unsigned FlagsToExclude = 0) const {
     return findNearest(Option, ExactString, FlagsToInclude, FlagsToExclude, 4,
                        0) == 0;
   }
@@ -209,18 +236,26 @@ class OptTable {
   /// \param [in,out] Index - The current parsing position in the argument
   /// string list; on return this will be the index of the next argument
   /// string to parse.
-  /// \param [in] FlagsToInclude - Only parse options with any of these flags.
-  /// Zero is the default which includes all flags.
-  /// \param [in] FlagsToExclude - Don't parse options with this flag.  Zero
-  /// is the default and means exclude nothing.
+  /// \param [in] VisibilityMask - Only include options with any of these
+  /// visibility flags set.
   ///
   /// \return The parsed argument, or 0 if the argument is missing values
   /// (in which case Index still points at the conceptual next argument string
   /// to parse).
+  std::unique_ptr<Arg>
+  ParseOneArg(const ArgList &Args, unsigned &Index,
+              Visibility VisibilityMask = Visibility()) const;
+
   std::unique_ptr<Arg> ParseOneArg(const ArgList &Args, unsigned &Index,
-                                   unsigned FlagsToInclude = 0,
-                                   unsigned FlagsToExclude = 0) const;
+                                   unsigned FlagsToInclude,
+                                   unsigned FlagsToExclude) const;
+
+private:
+  std::unique_ptr<Arg>
+  internalParseOneArg(const ArgList &Args, unsigned &Index,
+                      std::function<bool(const Option &)> ExcludeOption) const;
 
+public:
   /// Parse an list of arguments into an InputArgList.
   ///
   /// The resulting InputArgList will reference the strings in [\p ArgBegin,
@@ -233,16 +268,25 @@ class OptTable {
   /// \param MissingArgIndex - On error, the index of the option which could
   /// not be parsed.
   /// \param MissingArgCount - On error, the number of missing options.
-  /// \param FlagsToInclude - Only parse options with any of these flags.
-  /// Zero is the default which includes all flags.
-  /// \param FlagsToExclude - Don't parse options with this flag.  Zero
-  /// is the default and means exclude nothing.
+  /// \param VisibilityMask - Only include options with any of these
+  /// visibility flags set.
   /// \return An InputArgList; on error this will contain all the options
   /// which could be parsed.
   InputArgList ParseArgs(ArrayRef<const char *> Args, unsigned &MissingArgIndex,
-                         unsigned &MissingArgCount, unsigned FlagsToInclude = 0,
+                         unsigned &MissingArgCount,
+                         Visibility VisibilityMask = Visibility()) const;
+
+  InputArgList ParseArgs(ArrayRef<const char *> Args, unsigned &MissingArgIndex,
+                         unsigned &MissingArgCount, unsigned FlagsToInclude,
                          unsigned FlagsToExclude = 0) const;
 
+private:
+  InputArgList
+  internalParseArgs(ArrayRef<const char *> Args, unsigned &MissingArgIndex,
+                    unsigned &MissingArgCount,
+                    std::function<bool(const Option &)> ExcludeOption) const;
+
+public:
   /// A convenience helper which handles optional initial options populated from
   /// an environment variable, expands response files recursively and parses
   /// options.
@@ -253,26 +297,32 @@ class OptTable {
   /// could be parsed.
   InputArgList parseArgs(int Argc, char *const *Argv, OptSpecifier Unknown,
                          StringSaver &Saver,
-                         function_ref<void(StringRef)> ErrorFn) const;
+                         std::function<void(StringRef)> ErrorFn) const;
 
   /// Render the help text for an option table.
   ///
   /// \param OS - The stream to write the help text to.
   /// \param Usage - USAGE: Usage
   /// \param Title - OVERVIEW: Title
-  /// \param FlagsToInclude - If non-zero, only include options with any
-  ///                         of these flags set.
-  /// \param FlagsToExclude - Exclude options with any of these flags set.
+  /// \param VisibilityMask - Only in                 Visibility VisibilityMask,clude options with any of these
+  ///                         visibility flags set.
+  /// \param ShowHidden     - If true, display options marked as HelpHidden
   /// \param ShowAllAliases - If true, display all options including aliases
   ///                         that don't have help texts. By default, we display
   ///                         only options that are not hidden and have help
   ///                         texts.
+  void printHelp(raw_ostream &OS, const char *Usage, const char *Title,
+                 bool ShowHidden = false, bool ShowAllAliases = false,
+                 Visibility VisibilityMask = Visibility()) const;
+
   void printHelp(raw_ostream &OS, const char *Usage, const char *Title,
                  unsigned FlagsToInclude, unsigned FlagsToExclude,
                  bool ShowAllAliases) const;
 
-  void printHelp(raw_ostream &OS, const char *Usage, const char *Title,
-                 bool ShowHidden = false, bool ShowAllAliases = false) const;
+private:
+  void internalPrintHelp(raw_ostream &OS, const char *Usage, const char *Title,
+                         bool ShowHidden, bool ShowAllAliases,
+                         std::function<bool(const Info &)> ExcludeOption) const;
 };
 
 /// Specialization of OptTable
@@ -305,31 +355,32 @@ class PrecomputedOptTable : public OptTable {
 
 } // end namespace llvm
 
-#define LLVM_MAKE_OPT_ID_WITH_ID_PREFIX(ID_PREFIX, PREFIX, PREFIXED_NAME, ID,  \
-                                        KIND, GROUP, ALIAS, ALIASARGS, FLAGS,  \
-                                        PARAM, HELPTEXT, METAVAR, VALUES)      \
+#define LLVM_MAKE_OPT_ID_WITH_ID_PREFIX(                                       \
+    ID_PREFIX, PREFIX, PREFIXED_NAME, ID, KIND, GROUP, ALIAS, ALIASARGS,       \
+    FLAGS, VISIBILITY, PARAM, HELPTEXT, METAVAR, VALUES)                       \
   ID_PREFIX##ID
 
 #define LLVM_MAKE_OPT_ID(PREFIX, PREFIXED_NAME, ID, KIND, GROUP, ALIAS,        \
-                         ALIASARGS, FLAGS, PARAM, HELPTEXT, METAVAR, VALUES)   \
+                         ALIASARGS, FLAGS, VISIBILITY, PARAM, HELPTEXT,        \
+                         METAVAR, VALUES)                                      \
   LLVM_MAKE_OPT_ID_WITH_ID_PREFIX(OPT_, PREFIX, PREFIXED_NAME, ID, KIND,       \
-                                  GROUP, ALIAS, ALIASARGS, FLAGS, PARAM,       \
-                                  HELPTEXT, METAVAR, VALUE)
+                                  GROUP, ALIAS, ALIASARGS, FLAGS, VISIBILITY,  \
+                                  PARAM, HELPTEXT, METAVAR, VALUE)
 
 #define LLVM_CONSTRUCT_OPT_INFO_WITH_ID_PREFIX(                                \
     ID_PREFIX, PREFIX, PREFIXED_NAME, ID, KIND, GROUP, ALIAS, ALIASARGS,       \
-    FLAGS, PARAM, HELPTEXT, METAVAR, VALUES)                                   \
+    FLAGS, VISIBILITY, PARAM, HELPTEXT, METAVAR, VALUES)                       \
   llvm::opt::OptTable::Info {                                                  \
     PREFIX, PREFIXED_NAME, HELPTEXT, METAVAR, ID_PREFIX##ID,                   \
-        llvm::opt::Option::KIND##Class, PARAM, FLAGS, ID_PREFIX##GROUP,        \
-        ID_PREFIX##ALIAS, ALIASARGS, VALUES                                    \
+        llvm::opt::Option::KIND##Class, PARAM, FLAGS, VISIBILITY,              \
+        ID_PREFIX##GROUP, ID_PREFIX##ALIAS, ALIASARGS, VALUES                  \
   }
 
 #define LLVM_CONSTRUCT_OPT_INFO(PREFIX, PREFIXED_NAME, ID, KIND, GROUP, ALIAS, \
-                                ALIASARGS, FLAGS, PARAM, HELPTEXT, METAVAR,    \
-                                VALUES)                                        \
-  LLVM_CONSTRUCT_OPT_INFO_WITH_ID_PREFIX(OPT_, PREFIX, PREFIXED_NAME, ID,      \
-                                         KIND, GROUP, ALIAS, ALIASARGS, FLAGS, \
-                                         PARAM, HELPTEXT, METAVAR, VALUES)
+                                ALIASARGS, FLAGS, VISIBILITY, PARAM, HELPTEXT, \
+                                METAVAR, VALUES)                               \
+  LLVM_CONSTRUCT_OPT_INFO_WITH_ID_PREFIX(                                      \
+      OPT_, PREFIX, PREFIXED_NAME, ID, KIND, GROUP, ALIAS, ALIASARGS, FLAGS,   \
+      VISIBILITY, PARAM, HELPTEXT, METAVAR, VALUES)
 
 #endif // LLVM_OPTION_OPTTABLE_H

llvm/include/llvm/Option/Option.h

@@ -37,6 +37,10 @@ enum DriverFlag {
   RenderSeparate   = (1 << 3)
 };
 
+enum DriverVisibility {
+  Default = (1 << 0),
+};
+
 /// Option - Abstract representation for a single form of driver
 /// argument.
 ///
@@ -183,6 +187,11 @@ class Option {
     return Info->Flags & Val;
   }
 
+  /// Test if this option has the visibility flag \a Val.
+  bool hasVisibilityFlag(unsigned Val) const {
+    return Info->Visibility & Val;
+  }
+
   /// getUnaliasedOption - Return the final option this option
   /// aliases (itself, if the option has no alias).
   const Option getUnaliasedOption() const {

llvm/lib/ExecutionEngine/JITLink/COFFDirectiveParser.cpp

@@ -36,6 +36,7 @@ static constexpr const ArrayRef<StringLiteral>
     PrefixTable(PrefixTable_init, std::size(PrefixTable_init) - 1);
 
 // Create table mapping all options defined in COFFOptions.td
+using namespace llvm::opt;
 static constexpr opt::OptTable::Info infoTable[] = {
 #define OPTION(...)                                                            \
   LLVM_CONSTRUCT_OPT_INFO_WITH_ID_PREFIX(COFF_OPT_, __VA_ARGS__),