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

[Victor Campos via llvm-branch-commits]

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

>From 9fcdd1760ea664a618a2c05a18e777940a9d49b6 Mon Sep 17 00:00:00 2001
From: Victor Campos <victor.campos at arm.com>
Date: Tue, 5 Nov 2024 14:22:06 +0000
Subject: [PATCH 1/3] Add documentation for Multilib custom flags

---
 clang/docs/Multilib.rst | 90 +++++++++++++++++++++++++++++++++++++++++
 1 file changed, 90 insertions(+)

diff --git a/clang/docs/Multilib.rst b/clang/docs/Multilib.rst
index 7637d0db9565b8..85cb789b9847ac 100644
--- a/clang/docs/Multilib.rst
+++ b/clang/docs/Multilib.rst
@@ -122,6 +122,78 @@ 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
+      DriverArgs: [-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>``.
+* DriverArgs: a list of strings corresponding to the extra driver arguments
+  used to build a library variant that's in accordance to this specific custom
+  flag value. These arguments are fed back into the driver if this flag *Value*
+  is enabled.
+
+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.
+
 Stability
 =========
 
@@ -222,6 +294,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 driver arguments to be printed with -print-multi-lib. Useful for
+      # specifying extra arguments for building the the associated library
+      # variant(s).
+      DriverArgs: [-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
 =================
 

>From 5799eb81ac94ec4131af146bfacdf44a9bebdd71 Mon Sep 17 00:00:00 2001
From: Victor Campos <victor.campos at arm.com>
Date: Mon, 25 Nov 2024 15:07:57 +0000
Subject: [PATCH 2/3] Fix doc build warning

---
 clang/docs/Multilib.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/clang/docs/Multilib.rst b/clang/docs/Multilib.rst
index 85cb789b9847ac..48d84087dda01c 100644
--- a/clang/docs/Multilib.rst
+++ b/clang/docs/Multilib.rst
@@ -164,7 +164,7 @@ Custom flags can be declared in the YAML file under the *Flags* section.
     Default: no-multithreaded
 
 * Name: the name to categorize a flag.
-* Values: a list of flag *Value*s (defined below).
+* 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.

>From 60ea585ab55295eb345f82fe3f07814c34a7a9cd Mon Sep 17 00:00:00 2001
From: Victor Campos <victor.campos at arm.com>
Date: Tue, 10 Dec 2024 11:05:53 +0000
Subject: [PATCH 3/3] Repurpose DriverArgs as MacroDefines

---
 clang/docs/Multilib.rst | 15 ++++++---------
 1 file changed, 6 insertions(+), 9 deletions(-)

diff --git a/clang/docs/Multilib.rst b/clang/docs/Multilib.rst
index 48d84087dda01c..fe42a3c31e3eb8 100644
--- a/clang/docs/Multilib.rst
+++ b/clang/docs/Multilib.rst
@@ -159,7 +159,7 @@ Custom flags can be declared in the YAML file under the *Flags* section.
   - Name: multithreaded
     Values:
     - Name: no-multithreaded
-      DriverArgs: [-D__SINGLE_THREAD__]
+      MacroDefines: [__SINGLE_THREAD__]
     - Name: multithreaded
     Default: no-multithreaded
 
@@ -176,10 +176,8 @@ Each flag *Value* is defined as:
 
 * Name: name of the value. This is the string to be used in
   ``-fmultilib-flag=<string>``.
-* DriverArgs: a list of strings corresponding to the extra driver arguments
-  used to build a library variant that's in accordance to this specific custom
-  flag value. These arguments are fed back into the driver if this flag *Value*
-  is enabled.
+* MacroDefines: a list of strings to be used as macro definitions. Each string
+  is fed into the driver as ``-D<string>``.
 
 The namespace of flag values is common across all flags. This means that flag
 value names must be unique.
@@ -302,10 +300,9 @@ For a more comprehensive example see
     Values:
       # Name of the custom flag value. To be used in -fmultilib-flag=<string>.
     - Name: no-multithreaded
-      # Extra driver arguments to be printed with -print-multi-lib. Useful for
-      # specifying extra arguments for building the the associated library
-      # variant(s).
-      DriverArgs: [-D__SINGLE_THREAD__]
+      # Macro definitions. Useful for defining extra macros for building the
+      # associated library variant(s).
+      MacroDefines: [__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