[clang][Driver] Add a custom error option in multilib.yaml. (#105684)

Sometimes a collection of multilibs has a gap in it, where a set of
driver command-line options can't work with any of the available
libraries.

For example, the Arm MVE extension requires special startup code (you
need to initialize FPSCR.LTPSIZE), and also benefits greatly from
-mfloat-abi=hard. So a multilib provider might build a library for
systems without MVE, and another for MVE with -mfloat-abi=hard,
anticipating that that's what most MVE users would want. But then if a
user compiles for MVE _without_ -mfloat-abi=hard, thhey can't use either
of those libraries – one has an ABI mismatch, and the other will fail to
set up LTPSIZE.

In that situation, it's useful to include a multilib.yaml entry for the
unworkable intermediate situation, and have it map to a fatal error
message rather than a set of actual libraries. Then the user gets a
build failure with a sensible explanation, instead of selecting an
unworkable library and silently generating bad output. The new
regression test demonstrates this case.

This patch introduces extra syntax into multilib.yaml, so that a record
in the `Variants` list can omit the `Dir` key, and in its place, provide
a `FatalError` key. Then, if that variant is selected, the error message
is emitted as a clang diagnostic, and multilib selection fails.

In order to emit the error message in `MultilibSet::select`, I had to
pass a `Driver &` to that function, which involved plumbing one through
to every call site, and in the unit tests, constructing one specially.

Author: statham-arm

clang/docs/Multilib.rst

@@ -200,6 +200,12 @@ For a more comprehensive example see
     # to be a match.
     Flags: [--target=thumbv7m-none-eabi, -mfpu=fpv4-sp-d16]
 
+  # If there is no multilib available for a particular set of flags, and the
+  # other multilibs are not adequate fallbacks, then you can define a variant
+  # record with a FatalError key in place of the Dir key.
+  - FatalError: this multilib collection has no hard-float ABI support 
+    Flags: [--target=thumbv7m-none-eabi, -mfloat-abi=hard]
+
 
   # The second section of the file is a list of regular expressions that are
   # used to map from flags generated from command line options to custom flags.

clang/include/clang/Basic/DiagnosticDriverKinds.td

@@ -810,6 +810,8 @@ def warn_drv_missing_multilib : Warning<
   InGroup<DiagGroup<"missing-multilib">>;
 def note_drv_available_multilibs : Note<
   "available multilibs are:%0">;
+def err_drv_multilib_custom_error : Error<
+  "multilib configuration error: %0">;
 
 def err_drv_experimental_crel : Error<
   "-Wa,--allow-experimental-crel must be specified to use -Wa,--crel. "

clang/include/clang/Driver/Multilib.h

@@ -18,13 +18,16 @@
 #include "llvm/Support/SourceMgr.h"
 #include <cassert>
 #include <functional>
+#include <optional>
 #include <string>
 #include <utility>
 #include <vector>
 
 namespace clang {
 namespace driver {
 
+class Driver;
+
 /// This corresponds to a single GCC Multilib, or a segment of one controlled
 /// by a command line flag.
 /// See also MultilibBuilder for building a multilib by mutating it
@@ -48,13 +51,19 @@ class Multilib {
   // directory is not mutually exclusive with anything else.
   std::string ExclusiveGroup;
 
+  // Some Multilib objects don't actually represent library directories you can
+  // select. Instead, they represent failures of multilib selection, of the
+  // form 'Sorry, we don't have any library compatible with these constraints'.
+  std::optional<std::string> FatalError;
+
 public:
   /// GCCSuffix, OSSuffix & IncludeSuffix will be appended directly to the
   /// sysroot string so they must either be empty or begin with a '/' character.
   /// This is enforced with an assert in the constructor.
   Multilib(StringRef GCCSuffix = {}, StringRef OSSuffix = {},
            StringRef IncludeSuffix = {}, const flags_list &Flags = flags_list(),
-           StringRef ExclusiveGroup = {});
+           StringRef ExclusiveGroup = {},
+           std::optional<StringRef> FatalError = std::nullopt);
 
   /// Get the detected GCC installation path suffix for the multi-arch
   /// target variant. Always starts with a '/', unless empty
@@ -84,6 +93,10 @@ class Multilib {
   { return GCCSuffix.empty() && OSSuffix.empty() && IncludeSuffix.empty(); }
 
   bool operator==(const Multilib &Other) const;
+
+  bool isFatalError() const { return FatalError.has_value(); }
+
+  const std::string &getFatalError() const { return FatalError.value(); }
 };
 
 raw_ostream &operator<<(raw_ostream &OS, const Multilib &M);
@@ -129,7 +142,7 @@ class MultilibSet {
   const_iterator end() const { return Multilibs.end(); }
 
   /// Select compatible variants, \returns false if none are compatible
-  bool select(const Multilib::flags_list &Flags,
+  bool select(const Driver &D, const Multilib::flags_list &Flags,
               llvm::SmallVectorImpl<Multilib> &) const;
 
   unsigned size() const { return Multilibs.size(); }

clang/lib/Driver/Driver.cpp

@@ -2296,7 +2296,8 @@ bool Driver::HandleImmediateArgs(Compilation &C) {
 
   if (C.getArgs().hasArg(options::OPT_print_multi_lib)) {
     for (const Multilib &Multilib : TC.getMultilibs())
-      llvm::outs() << Multilib << "\n";
+      if (!Multilib.isFatalError())
+        llvm::outs() << Multilib << "\n";
     return false;
   }
 

clang/lib/Driver/Multilib.cpp

@@ -9,6 +9,7 @@
 #include "clang/Driver/Multilib.h"
 #include "clang/Basic/LLVM.h"
 #include "clang/Basic/Version.h"
+#include "clang/Driver/Driver.h"
 #include "llvm/ADT/DenseSet.h"
 #include "llvm/ADT/SmallString.h"
 #include "llvm/ADT/StringRef.h"
@@ -31,9 +32,10 @@ using namespace llvm::sys;
 
 Multilib::Multilib(StringRef GCCSuffix, StringRef OSSuffix,
                    StringRef IncludeSuffix, const flags_list &Flags,
-                   StringRef ExclusiveGroup)
+                   StringRef ExclusiveGroup,
+                   std::optional<StringRef> FatalError)
     : GCCSuffix(GCCSuffix), OSSuffix(OSSuffix), IncludeSuffix(IncludeSuffix),
-      Flags(Flags), ExclusiveGroup(ExclusiveGroup) {
+      Flags(Flags), ExclusiveGroup(ExclusiveGroup), FatalError(FatalError) {
   assert(GCCSuffix.empty() ||
          (StringRef(GCCSuffix).front() == '/' && GCCSuffix.size() > 1));
   assert(OSSuffix.empty() ||
@@ -94,7 +96,7 @@ MultilibSet &MultilibSet::FilterOut(FilterCallback F) {
 
 void MultilibSet::push_back(const Multilib &M) { Multilibs.push_back(M); }
 
-bool MultilibSet::select(const Multilib::flags_list &Flags,
+bool MultilibSet::select(const Driver &D, const Multilib::flags_list &Flags,
                          llvm::SmallVectorImpl<Multilib> &Selected) const {
   llvm::StringSet<> FlagSet(expandFlags(Flags));
   Selected.clear();
@@ -121,6 +123,14 @@ bool MultilibSet::select(const Multilib::flags_list &Flags,
         continue;
     }
 
+    // If this multilib is actually a placeholder containing a fatal
+    // error message written by the multilib.yaml author, display that
+    // error message, and return failure.
+    if (M.isFatalError()) {
+      D.Diag(clang::diag::err_drv_multilib_custom_error) << M.getFatalError();
+      return false;
+    }
+
     // Select this multilib.
     Selected.push_back(M);
   }
@@ -162,7 +172,8 @@ namespace {
 static const VersionTuple MultilibVersionCurrent(1, 0);
 
 struct MultilibSerialization {
-  std::string Dir;
+  std::string Dir;        // if this record successfully selects a library dir
+  std::string FatalError; // if this record reports a fatal error message
   std::vector<std::string> Flags;
   std::string Group;
 };
@@ -205,11 +216,16 @@ struct MultilibSetSerialization {
 
 template <> struct llvm::yaml::MappingTraits<MultilibSerialization> {
   static void mapping(llvm::yaml::IO &io, MultilibSerialization &V) {
-    io.mapRequired("Dir", V.Dir);
+    io.mapOptional("Dir", V.Dir);
+    io.mapOptional("FatalError", V.FatalError);
     io.mapRequired("Flags", V.Flags);
     io.mapOptional("Group", V.Group);
   }
   static std::string validate(IO &io, MultilibSerialization &V) {
+    if (V.Dir.empty() && V.FatalError.empty())
+      return "one of the 'Dir' and 'FatalError' keys must be specified";
+    if (!V.Dir.empty() && !V.FatalError.empty())
+      return "the 'Dir' and 'FatalError' keys may not both be specified";
     if (StringRef(V.Dir).starts_with("/"))
       return "paths must be relative but \"" + V.Dir + "\" starts with \"/\"";
     return std::string{};
@@ -295,14 +311,18 @@ MultilibSet::parseYaml(llvm::MemoryBufferRef Input,
   multilib_list Multilibs;
   Multilibs.reserve(MS.Multilibs.size());
   for (const auto &M : MS.Multilibs) {
-    std::string Dir;
-    if (M.Dir != ".")
-      Dir = "/" + M.Dir;
-    // We transfer M.Group straight into the ExclusiveGroup parameter for the
-    // Multilib constructor. If we later support more than one type of group,
-    // we'll have to look up the group name in MS.Groups, check its type, and
-    // decide what to do here.
-    Multilibs.emplace_back(Dir, Dir, Dir, M.Flags, M.Group);
+    if (!M.FatalError.empty()) {
+      Multilibs.emplace_back("", "", "", M.Flags, M.Group, M.FatalError);
+    } else {
+      std::string Dir;
+      if (M.Dir != ".")
+        Dir = "/" + M.Dir;
+      // We transfer M.Group straight into the ExclusiveGroup parameter for the
+      // Multilib constructor. If we later support more than one type of group,
+      // we'll have to look up the group name in MS.Groups, check its type, and
+      // decide what to do here.
+      Multilibs.emplace_back(Dir, Dir, Dir, M.Flags, M.Group);
+    }
   }
 
   return MultilibSet(std::move(Multilibs), std::move(MS.FlagMatchers));

clang/lib/Driver/ToolChains/BareMetal.cpp

@@ -58,7 +58,7 @@ static bool findRISCVMultilibs(const Driver &D,
 
     Result.Multilibs =
         MultilibSetBuilder().Either(Imac, Imafdc).makeMultilibSet();
-    return Result.Multilibs.select(Flags, Result.SelectedMultilibs);
+    return Result.Multilibs.select(D, Flags, Result.SelectedMultilibs);
   }
   if (TargetTriple.isRISCV32()) {
     MultilibBuilder Imac =
@@ -92,7 +92,7 @@ static bool findRISCVMultilibs(const Driver &D,
 
     Result.Multilibs =
         MultilibSetBuilder().Either(I, Im, Iac, Imac, Imafc).makeMultilibSet();
-    return Result.Multilibs.select(Flags, Result.SelectedMultilibs);
+    return Result.Multilibs.select(D, Flags, Result.SelectedMultilibs);
   }
   return false;
 }
@@ -182,12 +182,13 @@ static void findMultilibsFromYAML(const ToolChain &TC, const Driver &D,
   if (ErrorOrMultilibSet.getError())
     return;
   Result.Multilibs = ErrorOrMultilibSet.get();
-  if (Result.Multilibs.select(Flags, Result.SelectedMultilibs))
+  if (Result.Multilibs.select(D, Flags, Result.SelectedMultilibs))
     return;
   D.Diag(clang::diag::warn_drv_missing_multilib) << llvm::join(Flags, " ");
   std::stringstream ss;
   for (const Multilib &Multilib : Result.Multilibs)
-    ss << "\n" << llvm::join(Multilib.flags(), " ");
+    if (!Multilib.isFatalError())
+      ss << "\n" << llvm::join(Multilib.flags(), " ");
   D.Diag(clang::diag::note_drv_available_multilibs) << ss.str();
 }
 

clang/lib/Driver/ToolChains/Fuchsia.cpp

@@ -324,7 +324,7 @@ Fuchsia::Fuchsia(const Driver &D, const llvm::Triple &Triple,
 
   Multilibs.setFilePathsCallback(FilePaths);
 
-  if (Multilibs.select(Flags, SelectedMultilibs)) {
+  if (Multilibs.select(D, Flags, SelectedMultilibs)) {
     // Ensure that -print-multi-directory only outputs one multilib directory.
     Multilib LastSelected = SelectedMultilibs.back();
     SelectedMultilibs = {LastSelected};