[libOption] - Add flag allowing to print options aliases in help text.

[grimar]

Summary

Goint to use it in LLD.
In short this is PR30422, previously LLD did not show
aliases in help text. With this it is possible.

[ruiu]

Please wait until we decide how we print out the lld options in the help message.

[grimar]

In D35476#812068, @ruiu wrote:

Please wait until we decide how we print out the lld options in the help message.

Ok. Going to rebase this after rL308293 though.

But just in case - the way we will choose for LLD (render all or some of aliases)
should not affect this patch (except if we choose possible way to ignore aliases
rendering at all, which I believe not an option).

Because this patch only implements aliases rendering, and hidden flags handling is
independent and already was implemented before this change.

[grimar]

• Rebased.

[grimar]

• Reimplemented.

ShowAliases flag allows to specify that alias should take HelpText from its
parent option. In that case we can have for example:

def auxiliary: S<"auxiliary">, HelpText<"Set DT_AUXILIARY field to the specified name">;
def alias_auxiliary: Separate<["-"], "f">, Alias<auxiliary>;

and show both options in help:

--auxiliary <value> Set DT_AUXILIARY field to the specified name
-f <value>              Set DT_AUXILIARY field to the specified name

Without that change we would render only first line in --help.

[grimar]

• Change argument name, added lost description.

[ruiu]

The new behavior is probably fine, but I don't think you needed to change the parameter name.

[grimar]

In D35476#819118, @ruiu wrote:

The new behavior is probably fine, but I don't think you needed to change the parameter name.

I changed newly introduced ShowAliases to InferHelpText because first one is not completelly correctly
reflects the action performed.

If we have HelpText specified for alias:
def alias_version_V: Flag<["-"], "V">, Alias<version>, HelpText<"blah blah">;
then regardless of ShowAliases flag value, this option will be shown.
Because old logic prints all options with HelpText at first place (and I did not change it here).

Probably we can name it ShowAllAliases ? With description saying it will trigger rendering all
aliases regardless they have HelpText explicitly set or not.

[grimar]

• Updated in according to my latest comment. (renamed argument to ShowAllAliases).

[ruiu]

LGTM

include/llvm/Option/OptTable.h

194–197

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.

lib/Option/OptTable.cpp

478–481

If an alias doesn't have a help text, show a help text for the aliased option instead.

include/llvm/Option/OptTable.h

public:
   /// \brief Render the help text for an option table.
   ///
   /// \param OS - The stream to write the help text to.
   /// \param Name - The name to use in the usage line.
   /// \param Title - The title to use in the usage line.
   /// \param FlagsToInclude - If non-zero, only include options with any
   ///                         of these flags set.
   /// \param FlagsToExclude - Exclude options with any of these flags set.
-  void PrintHelp(raw_ostream &OS, const char *Name,
-                 const char *Title, unsigned FlagsToInclude,
-                 unsigned FlagsToExclude) const;
+  /// \param ShowAllAliases - If true then aliases without explicitly set
+  ///                         HelpText will be rendered, inheriting it from
+  ///                         aliased option.
+  void PrintHelp(raw_ostream &OS, const char *Name, const char *Title,
+                 unsigned FlagsToInclude, unsigned FlagsToExclude,
+                 bool ShowAllAliases) const;
 
-  void PrintHelp(raw_ostream &OS, const char *Name,
-                  const char *Title, bool ShowHidden = false) const;
+  void PrintHelp(raw_ostream &OS, const char *Name, const char *Title,
+                 bool ShowHidden = false, bool ShowAllAliases = false) const;
 };
 
 } // end namespace opt
 
 } // end namespace llvm
 
 #endif // LLVM_OPTION_OPTTABLE_H

lib/Option/OptTable.cpp

static const char *getOptionHelpGroup(const OptTable &Opts, OptSpecifier Id) {
   if (const char *GroupHelp = Opts.getOptionHelpText(GroupID))
     return GroupHelp;
 
   // Otherwise keep looking.
   return getOptionHelpGroup(Opts, GroupID);
 }
 
 void OptTable::PrintHelp(raw_ostream &OS, const char *Name, const char *Title,
-                         bool ShowHidden) const {
+                         bool ShowHidden, bool ShowAllAliases) const {
   PrintHelp(OS, Name, Title, /*Include*/ 0, /*Exclude*/
-            (ShowHidden ? 0 : HelpHidden));
+            (ShowHidden ? 0 : HelpHidden), ShowAllAliases);
 }
 
-
 void OptTable::PrintHelp(raw_ostream &OS, const char *Name, const char *Title,
-                         unsigned FlagsToInclude,
-                         unsigned FlagsToExclude) const {
+                         unsigned FlagsToInclude, unsigned FlagsToExclude,
+                         bool ShowAllAliases) const {
   OS << "OVERVIEW: " << Title << "\n";
   OS << '\n';
   OS << "USAGE: " << Name << " [options] <inputs>\n";
   OS << '\n';
 
   // Render help text into a map of group-name to a list of (option, help)
   // pairs.
   using helpmap_ty = std::map<std::string, std::vector<OptionInfo>>;
   helpmap_ty GroupedOptionHelp;
 
   for (unsigned i = 0, e = getNumOptions(); i != e; ++i) {
     unsigned Id = i + 1;
 
     // FIXME: Split out option groups.
     if (getOptionKind(Id) == Option::GroupClass)
       continue;
 
     unsigned Flags = getInfo(Id).Flags;
     if (FlagsToInclude && !(Flags & FlagsToInclude))
       continue;
     if (Flags & FlagsToExclude)
       continue;
 
-    if (const char *Text = getOptionHelpText(Id)) {
+    // Aliases usually do not have help text set explicitly. If we want to show
+    // such aliases in help, we use associated aliased option help text value.
+    // If both alias and aliased option has no text, that proably means option
+    // is ignored.
+    const char *HelpText = getOptionHelpText(Id);
+    if (!HelpText && ShowAllAliases) {
+      const Option Alias = getOption(Id).getAlias();
+      if (Alias.isValid())
+        HelpText = getOptionHelpText(Alias.getID());
+    }
+
+    if (HelpText) {
       const char *HelpGroup = getOptionHelpGroup(*this, Id);
       const std::string &OptName = getOptionHelpName(*this, Id);
-      GroupedOptionHelp[HelpGroup].push_back({OptName, Text});
+      GroupedOptionHelp[HelpGroup].push_back({OptName, HelpText});
     }
   }
 
   for (helpmap_ty::iterator it = GroupedOptionHelp .begin(),
          ie = GroupedOptionHelp.end(); it != ie; ++it) {
     if (it != GroupedOptionHelp .begin())
       OS << "\n";
     PrintHelpOptionList(OS, it->first, it->second);
   }
 
   OS.flush();
 }