[llvm-branch-commits] [clang] Add documentation for Multilib custom flags (PR #114998)

[Sam Elliott via llvm-branch-commits]

================
@@ -122,6 +122,76 @@ subclass and a suitable base multilib variant is present then the
 It is the responsibility of layered multilib authors to ensure that headers and
 libraries in each layer are complete enough to mask any incompatibilities.
 
+Multilib custom flags
+=====================
+
+Introduction
+------------
+
+The multilib mechanism supports library variants that correspond to target,
+code generation or language command-line flags. Examples include ``--target``,
+``-mcpu``, ``-mfpu``, ``-mbranch-protection``, ``-fno-rtti``. However, some library
+variants are particular to features that do not correspond to any command-line
+option. Multithreading and semihosting, for instance, have no associated
+compiler option.
+
+In order to support the selection of variants for which no compiler option
+exists, the multilib specification includes the concept of *custom flags*.
+These flags have no impact on code generation and are only used in the multilib
+processing.
+
+Multilib custom flags follow this format in the driver invocation:
+
+::
+
+  -fmultilib-flag=<value>
+
+They are fed into the multilib system alongside the remaining flags.
+
+Custom flag declarations
+------------------------
+
+Custom flags can be declared in the YAML file under the *Flags* section.
+
+.. code-block:: yaml
+
+  Flags:
+  - Name: multithreaded
+    Values:
+    - Name: no-multithreaded
+      MacroDefines: [__SINGLE_THREAD__]
+    - Name: multithreaded
+    Default: no-multithreaded
+
+* Name: the name to categorize a flag.
+* Values: a list of flag Values (defined below).
+* Default: it specifies the name of the value this flag should take if not
+  specified in the command-line invocation. It must be one value from the Values
+  field.
+
+A Default value is useful to save users from specifying custom flags that have a
----------------
lenary wrote:

This makes it sound like setting a default is optional, which it isn't

https://github.com/llvm/llvm-project/pull/114998