[Clang][Docs] Document -Xarch_ better #127890
Conversation
|
@llvm/pr-subscribers-clang Author: Joseph Huber (jhuber6) ChangesSummary: Full diff: https://github.com/llvm/llvm-project/pull/127890.diff 1 Files Affected:
diff --git a/clang/include/clang/Driver/Options.td b/clang/include/clang/Driver/Options.td
index 5ad187926e710..b5598a44758a8 100644
--- a/clang/include/clang/Driver/Options.td
+++ b/clang/include/clang/Driver/Options.td
@@ -934,6 +934,12 @@ def Xanalyzer : Separate<["-"], "Xanalyzer">,
Group<StaticAnalyzer_Group>;
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>">;
|
Summary: This argument is esoteric and previously didn't even work consistently across the targets. Now that's fixed we should document it better.
Co-authored-by: Jan Patrick Lehr <[email protected]>
Co-authored-by: Jan Patrick Lehr <[email protected]>
Co-authored-by: Jan Patrick Lehr <[email protected]>
| 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>">; |
There was a problem hiding this comment.
I think the 'special' cases of -Xarch_host and -Xarch_device should somehow be mentioned.
Can we make the help a separate record and use it for all -Xarch* option variants consistently?
There was a problem hiding this comment.
There are special cases? I thought it was self evident for offloading. But I think they are handled as different flags so I could put the help under them if that's what you mean.
There was a problem hiding this comment.
We do have them defined below as separate options, and you do already mention Xarch_device in the help message.
To the user unfamiliar with the implementation they all look like the same -Xarch_* option, but somehow get separate help message and treatment. It would be good to document a coherent picture of how it all fits together.
Can we make the help a separate record and use it for all -Xarch* option variants consistently?
Scratch that, it's a docBrief, so a single instance attached to this option is fine, I just want to expand it to include the wildcard host/device pseudo-arches that -Xarch effectively accepts.
Summary:
This argument is esoteric and previously didn't even work consistently
across the targets. Now that's fixed we should document it better.