Add documentation for Multilib custom flags

[vhscampos]

This patch is the fourth step to extend the current multilib system to support the selection of library variants which do not correspond to existing command-line options.

Proposal can be found in https://discourse.llvm.org/t/rfc-multilib-custom-flags/81058

The multilib mechanism supports libraries that target code generation or language options such as --target, -mcpu, -mfpu, -mbranch-protection. However, some library variants are particular to features that do not correspond to any command-line options. Examples include variants for multithreading and semihosting.

This work introduces a way to instruct the multilib system to consider these features in library selection. This particular patch updates the documentation.

[llvmbot]

@llvm/pr-subscribers-clang

Author: Victor Campos (vhscampos)

Changes

---

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

1 Files Affected:

• (modified) clang/docs/Multilib.rst (+116)

diff --git a/clang/docs/Multilib.rst b/clang/docs/Multilib.rst
index 7637d0db9565b8..7c165d149d7a4c 100644
--- a/clang/docs/Multilib.rst
+++ b/clang/docs/Multilib.rst
@@ -122,6 +122,104 @@ 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
+      ExtraBuildArgs: [-D__SINGLE_THREAD__]
+    - Name: multithreaded
+    Default: no-multithreaded
+
+* Name: the name to categorize a flag.
+* Values: a list of flag *Value*s (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
+most commonly used value.
+
+Each flag *Value* is defined as:
+
+* Name: name of the value. This is the string to be used in
+  ``-fmultilib-flag=<string>``.
+* ExtraBuildArgs: a list of strings corresponding to the extra build arguments
+  used to build a library variant that's in accordance to this specific custom
+  flag value.
+
+The namespace of flag values is common across all flags. This means that flag
+value names must be unique.
+
+Usage of custom flags in the *Variants* specifications
+------------------------------------------------------
+
+Library variants should list their requirement on one or more custom flags like
+they do for any other flag. Each requirement must be listed as
+``-fmultilib-flag=<value>``.
+
+A variant that does not specify a requirement on one particular flag can be
+matched against any value of that flag.
+
+Use of ``-print-multi-lib`` by build systems
+--------------------------------------------
+
+Some library build systems use the ``-print-multi-lib`` command-line option to
+query what library variants are shipped or supported by the target compiler and
+what command-line options should be used to build the variants.
+
+In this use case, a build system queries the target toolchain about what library
+variants should be built. With this information in hand, the build system may
+launch the build of each variant using the collected command-line arguments.
+
+For example, in *newlib*, multithreading is enabled by default and can be
+disabled by defining the ``__SINGLE_THREAD__`` macro. Therefore a multilib YAML
+file that is used to drive a *newlib* build must encode this information in the
+output of ``-print-multi-lib``.
+
+To account for this use case, custom flag values may specify the
+*ExtraBuildArgs* field. This optional field is a list of strings to be printed
+alongside the other command-line arguments in the output of
+``-print-multi-lib``. In the example of *newlib* and its multithreading support,
+a variant specific for single threaded execution should list
+``-D__SINGLE_THREAD__`` in its corresponding flag value's *ExtraBuildArgs*
+field.
+
+Since this information is specific for users of ``-print-multi-lib``, that is,
+for *builders* of library variants, it has no relevance in library *selection*.
+
 Stability
 =========
 
@@ -222,6 +320,24 @@ For a more comprehensive example see
     # Flags is a list of one or more strings.
     Flags: [--target=thumbv7m-none-eabi]
 
+  # Custom flag declarations. Each item is a different declaration.
+  Flags:
+    # Name of the flag
+  - Name: multithreaded
+    # List of custom flag values
+    Values:
+      # Name of the custom flag value. To be used in -fmultilib-flag=<string>.
+    - Name: no-multithreaded
+      # Extra build arguments to be printed with -print-multi-lib. Useful for
+      # specifying extra arguments for building the the associated library
+      # variant(s).
+      ExtraBuildArgs: [-D__SINGLE_THREAD__]
+    - Name: multithreaded
+    # Default flag value. If no value for this flag declaration is used in the
+    # command-line, the multilib system will use this one. Must be equal to one
+    # of the flag value names from this flag declaration.
+    Default: no-multithreaded
+
 Design principles
 =================
 

[lenary]

LGTM

[lenary]

I'm still happy with this, and it is for docs, so I don't think the barrier to landing it is very high.