[clang-cl] Document behavior difference of strict aliasing in clang-cl vs clang.

[huihzhang]

Add an user note to pass -fstrict-aliasing explicitly for clang-cl at optimization levels O3 and below to enable TBAA.
Also add help text for -f[no-]strict-aliasing.

[llvmbot]

@llvm/pr-subscribers-clang

Changes

Add an user note to pass -fstrict-aliasing explicitly for clang-cl at optimization levels O3 and below to enable TBAA.
Also add help text for -f[no-]strict-aliasing.

---

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

2 Files Affected:

• (modified) clang/docs/UsersManual.rst (+16)
• (modified) clang/include/clang/Driver/Options.td (+4-2)

diff --git a/clang/docs/UsersManual.rst b/clang/docs/UsersManual.rst
index 25bbd72c81f7a3b..704a634ffd8c8c4 100644
--- a/clang/docs/UsersManual.rst
+++ b/clang/docs/UsersManual.rst
@@ -4383,6 +4383,7 @@ Execute ``clang-cl /?`` to see a list of supported options:
       -fno-sanitize-trap=<value>
                               Disable trapping for specified sanitizers
       -fno-standalone-debug   Limit debug information produced to reduce size of debug binary
+      -fno-strict-aliasing    Disable optimizations based on strict aliasing rules (default)
       -fobjc-runtime=<value>  Specify the target Objective-C runtime kind and version
       -fprofile-exclude-files=<value>
                               Instrument only functions from files where names don't match all the regexes separated by a semi-colon
@@ -4444,6 +4445,7 @@ Execute ``clang-cl /?`` to see a list of supported options:
                               behavior. See user manual for available checks
       -fsplit-lto-unit        Enables splitting of the LTO unit.
       -fstandalone-debug      Emit full debug info for all types used by the program
+      -fstrict-aliasing	      Enable optimizations based on strict aliasing rules
       -fsyntax-only           Run the preprocessor, parser and semantic analysis stages
       -fwhole-program-vtables Enables whole-program vtable optimization. Requires -flto
       -gcodeview-ghash        Emit type record hashes in a .debug$H section
@@ -4722,3 +4724,17 @@ The Visual C++ Toolset has a slightly more elaborate mechanism for detection.
     The registry information is used to help locate the installation as a final
     fallback.  This is only possible for pre-VS2017 installations and is
     considered deprecated.
+
+Restrictions and Limitations compared to Clang
+----------------------------------------------
+
+Strict Aliasing
+^^^^^^^^^^^^^^^
+
+Strict aliasing (TBAA) is turned off by default in clang-cl at optimization
+levels O3 and below, and turned on at Ofast. Whereas in clang, strict aliasing
+is turned on by default for all optimization levels.
+
+To enable LLVM optimizations based on strict aliasing rules (e.g., optimizations
+based on type of expressions in C/C++), user will need to explicitly pass
+`-fstrict-aliasing` to clang-cl when compiling at O3 and below.
diff --git a/clang/include/clang/Driver/Options.td b/clang/include/clang/Driver/Options.td
index 5415b18d3f406df..2109513364dba14 100644
--- a/clang/include/clang/Driver/Options.td
+++ b/clang/include/clang/Driver/Options.td
@@ -3152,7 +3152,8 @@ defm diagnostics_show_line_numbers : BoolFOption<"diagnostics-show-line-numbers"
 def fno_stack_protector : Flag<["-"], "fno-stack-protector">, Group<f_Group>,
   HelpText<"Disable the use of stack protectors">;
 def fno_strict_aliasing : Flag<["-"], "fno-strict-aliasing">, Group<f_Group>,
-  Flags<[NoXarchOption]>, Visibility<[ClangOption, CLOption, DXCOption]>;
+  Flags<[NoXarchOption]>, Visibility<[ClangOption, CLOption, DXCOption]>,
+  HelpText<"Disable optimizations based on strict aliasing rules (default)">;
 def fstruct_path_tbaa : Flag<["-"], "fstruct-path-tbaa">, Group<f_Group>;
 def fno_struct_path_tbaa : Flag<["-"], "fno-struct-path-tbaa">, Group<f_Group>;
 def fno_strict_enums : Flag<["-"], "fno-strict-enums">, Group<f_Group>;
@@ -3595,7 +3596,8 @@ def fno_debug_macro : Flag<["-"], "fno-debug-macro">, Group<f_Group>,
   Visibility<[ClangOption, CLOption, DXCOption]>,
   HelpText<"Do not emit macro debug information">;
 def fstrict_aliasing : Flag<["-"], "fstrict-aliasing">, Group<f_Group>,
-  Flags<[NoXarchOption]>, Visibility<[ClangOption, CLOption, DXCOption]>;
+  Flags<[NoXarchOption]>, Visibility<[ClangOption, CLOption, DXCOption]>,
+  HelpText<"Enable optimizations based on strict aliasing rules">;
 def fstrict_enums : Flag<["-"], "fstrict-enums">, Group<f_Group>,
   Visibility<[ClangOption, CC1Option]>,
   HelpText<"Enable optimizations based on the strict definition of an enum's "

[zmodem]

Thanks for the PR!

[zmodem]

Since the defaultness depends on which driver mode is used (clang-cl or regular clang), we should probably leave out the (default) part.

[zmodem]

clang-cl uses MSVC's -O flag, so there is no -O3 or -Ofast. So unless I'm missing something, I think we should say that it's always off by default in clang-cl.

[huihzhang]

Fixed up documentation based on review comments.

[zmodem]

Looks good to me. Thanks!