[clang] [Clang][Docs] Document -Xarch_ better (PR #127890)

[Joseph Huber via cfe-commits]

https://github.com/jhuber6 updated https://github.com/llvm/llvm-project/pull/127890

>From d5efc8e10fabb0f2258e0bf5d2e4ce9c0686b911 Mon Sep 17 00:00:00 2001
From: Joseph Huber <huberjn at outlook.com>
Date: Wed, 19 Feb 2025 14:01:56 -0600
Subject: [PATCH 1/5] [Clang][Docs] Document -Xarch_ better

Summary:
This argument is esoteric and previously didn't even work consistently
across the targets. Now that's fixed we should document it better.
---
 clang/include/clang/Driver/Options.td | 15 ++++++++++++---
 1 file changed, 12 insertions(+), 3 deletions(-)

diff --git a/clang/include/clang/Driver/Options.td b/clang/include/clang/Driver/Options.td
index 5ad187926e710..2b273c3f5c24d 100644
--- a/clang/include/clang/Driver/Options.td
+++ b/clang/include/clang/Driver/Options.td
@@ -932,9 +932,18 @@ def W_Joined : Joined<["-"], "W">, Group<W_Group>,
 def Xanalyzer : Separate<["-"], "Xanalyzer">,
   HelpText<"Pass <arg> to the static analyzer">, MetaVarName<"<arg>">,
   Group<StaticAnalyzer_Group>;
-def Xarch__ : JoinedAndSeparate<["-"], "Xarch_">, Flags<[NoXarchOption]>,
-  HelpText<"Pass <arg> to the compiliation if the target matches <arch>">,
-  MetaVarName<"<arch> <arg>">;
+def Xarch__
+    : JoinedAndSeparate<["-"], "Xarch_">,
+      Flags<[NoXarchOption]>,
+      HelpText<"Pass <arg> to the compiliation if the target matches <arch>">,
+      DocBrief<
+          [{Specifies that the argument should only be used if the compileation
+  target matches the specified architecture. This can be used with the target
+  CPU, triple architecture, or offloading host and device. This is most useful
+  for separating behavior undesirable on one of the targets when combining many
+  compilation jobs, as is commong with offloading. For example, -Xarch_x86_64,
+  -Xarch_gfx90a, and -Xarch_device are all valid selectors.}]>,
+      MetaVarName<"<arch> <arg>">;
 def Xarch_host : Separate<["-"], "Xarch_host">, Flags<[NoXarchOption]>,
   HelpText<"Pass <arg> to the CUDA/HIP host compilation">, MetaVarName<"<arg>">;
 def Xarch_device : Separate<["-"], "Xarch_device">, Flags<[NoXarchOption]>,

>From 1d0394980075532f506965f3022cd378ad385f0d Mon Sep 17 00:00:00 2001
From: Joseph Huber <huberjn at outlook.com>
Date: Wed, 19 Feb 2025 14:38:28 -0600
Subject: [PATCH 2/5] Update clang/include/clang/Driver/Options.td

Co-authored-by: Jan Patrick Lehr <JanPatrick.Lehr at amd.com>
---
 clang/include/clang/Driver/Options.td | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/clang/include/clang/Driver/Options.td b/clang/include/clang/Driver/Options.td
index 2b273c3f5c24d..41a24485479f1 100644
--- a/clang/include/clang/Driver/Options.td
+++ b/clang/include/clang/Driver/Options.td
@@ -937,7 +937,7 @@ def Xarch__
       Flags<[NoXarchOption]>,
       HelpText<"Pass <arg> to the compiliation if the target matches <arch>">,
       DocBrief<
-          [{Specifies that the argument should only be used if the compileation
+          [{Specifies that the argument should only be used if the compilation
   target matches the specified architecture. This can be used with the target
   CPU, triple architecture, or offloading host and device. This is most useful
   for separating behavior undesirable on one of the targets when combining many

>From 5950eccf137fbf502d8d9f1213264c86c381afe9 Mon Sep 17 00:00:00 2001
From: Joseph Huber <huberjn at outlook.com>
Date: Wed, 19 Feb 2025 14:38:35 -0600
Subject: [PATCH 3/5] Update clang/include/clang/Driver/Options.td

Co-authored-by: Jan Patrick Lehr <JanPatrick.Lehr at amd.com>
---
 clang/include/clang/Driver/Options.td | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/clang/include/clang/Driver/Options.td b/clang/include/clang/Driver/Options.td
index 41a24485479f1..2c699c38b0c99 100644
--- a/clang/include/clang/Driver/Options.td
+++ b/clang/include/clang/Driver/Options.td
@@ -935,7 +935,7 @@ def Xanalyzer : Separate<["-"], "Xanalyzer">,
 def Xarch__
     : JoinedAndSeparate<["-"], "Xarch_">,
       Flags<[NoXarchOption]>,
-      HelpText<"Pass <arg> to the compiliation if the target matches <arch>">,
+      HelpText<"Pass <arg> to the compilation if the target matches <arch>">,
       DocBrief<
           [{Specifies that the argument should only be used if the compilation
   target matches the specified architecture. This can be used with the target

>From 9a76ea9d0142c1093164677ec4c0f8859b5b2605 Mon Sep 17 00:00:00 2001
From: Joseph Huber <huberjn at outlook.com>
Date: Wed, 19 Feb 2025 14:38:43 -0600
Subject: [PATCH 4/5] Update clang/include/clang/Driver/Options.td

Co-authored-by: Jan Patrick Lehr <JanPatrick.Lehr at amd.com>
---
 clang/include/clang/Driver/Options.td | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/clang/include/clang/Driver/Options.td b/clang/include/clang/Driver/Options.td
index 2c699c38b0c99..bc0d21a8c00e9 100644
--- a/clang/include/clang/Driver/Options.td
+++ b/clang/include/clang/Driver/Options.td
@@ -939,7 +939,7 @@ def Xarch__
       DocBrief<
           [{Specifies that the argument should only be used if the compilation
   target matches the specified architecture. This can be used with the target
-  CPU, triple architecture, or offloading host and device. This is most useful
+  CPU, triple architecture, or offloading host and device. It is most useful
   for separating behavior undesirable on one of the targets when combining many
   compilation jobs, as is commong with offloading. For example, -Xarch_x86_64,
   -Xarch_gfx90a, and -Xarch_device are all valid selectors.}]>,

>From 9b72b293ce80a2f944a85625720f89593ba0b298 Mon Sep 17 00:00:00 2001
From: Joseph Huber <huberjn at outlook.com>
Date: Wed, 19 Feb 2025 17:59:16 -0600
Subject: [PATCH 5/5] Update Options.td

---
 clang/include/clang/Driver/Options.td | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/clang/include/clang/Driver/Options.td b/clang/include/clang/Driver/Options.td
index bc0d21a8c00e9..bb74defaa28bf 100644
--- a/clang/include/clang/Driver/Options.td
+++ b/clang/include/clang/Driver/Options.td
@@ -942,7 +942,9 @@ def Xarch__
   CPU, triple architecture, or offloading host and device. It is most useful
   for separating behavior undesirable on one of the targets when combining many
   compilation jobs, as is commong with offloading. For example, -Xarch_x86_64,
-  -Xarch_gfx90a, and -Xarch_device are all valid selectors.}]>,
+  -Xarch_gfx90a, and -Xarch_device are all valid selectors. -Xarch_device will
+  forward the argument to the offloading device while -Xarch_host will target
+  the host system, which can be used to suppress incompatible GPU arguments.}]>,
       MetaVarName<"<arch> <arg>">;
 def Xarch_host : Separate<["-"], "Xarch_host">, Flags<[NoXarchOption]>,
   HelpText<"Pass <arg> to the CUDA/HIP host compilation">, MetaVarName<"<arg>">;