[clang] [clang][docs] Document clang-cl options in the command line reference (PR #233116)
via cfe-commits
cfe-commits at lists.llvm.org
Sat Oct 17 10:27:15 PDT 2026
llvmorg-github-actions[bot] wrote:
<!--LLVM PR SUMMARY COMMENT-->
@llvm/pr-subscribers-clang
Author: Demo_mod (Glitch-On)
<details>
<summary>Changes</summary>
The user's manual carries a pasted copy of `clang-cl /?`. It goes stale as soon as an option changes and duplicates the help text already in Options.td. This generates that list in ClangCommandLineReference instead and replaces the dump in the manual with a pointer to it.
ClangOptionDocs.td now also includes options visible to clang-cl, and `cl_Group` gets a `DocName` and `DocBrief` so they land in a "clang-cl options" section next to the clang-dxc one. The compile-only and ignored subgroups are flattened into it, matching how `/?` prints them.
Two emitter changes were needed to make the output usable:
- Folding clang-cl aliases into the entries of the options they alias would mislead on a page about clang. `-Wall` means `-Weverything` only under clang-cl, and with the mask widened the `-W<warning>` entry said exactly that. The emitter now documents an alias on its own when it is not visible to the primary program (the first `VisibilityMask` entry). With this, every existing clang entry on the page is byte-for-byte unchanged.
- The "(equivalent to ...)" note is dropped when it would repeat the option itself, as for `/O1` aliasing `/O` with argument `1`.
`/volatile:iso` and `/volatile:ms` had no `Group` and so showed up among the generic compilation options; they are put in the existing `_SLASH_volatile_Group`. Alias options match through the aliased option, so this only affects help and docs grouping.
Checked by regenerating the page with the rebuilt clang-tblgen and diffing against the current output, and by building the clang HTML docs with Sphinx: no warnings on either page, and the links between the manual and the new section resolve in both directions. Every flag from the removed dump appears in the generated section except `/?` itself, which Sphinx cannot take as an option name; the section text points at `clang-cl /?` for that.
Not included: the broader editing pass the issue suggests for the rest of the manual, and clang-dxc-only flags such as `/Zpc`, which are missing from the page for the same reason clang-cl ones were. Adding `DXCOption` to the mask would be a one-line follow-up.
Fixes #<!-- -->165059
---
Patch is 77.34 KiB, truncated to 20.00 KiB below, full version: https://github.com/llvm/llvm-project/pull/233116.diff
4 Files Affected:
- (modified) clang/docs/UsersManual.md (+5-920)
- (modified) clang/include/clang/Options/ClangOptionDocs.td (+10-2)
- (modified) clang/include/clang/Options/Options.td (+14-5)
- (modified) clang/utils/TableGen/ClangOptionDocEmitter.cpp (+35-10)
``````````diff
diff --git a/clang/docs/UsersManual.md b/clang/docs/UsersManual.md
index 96d1c4e009c71a..4d79195e5dc766 100644
--- a/clang/docs/UsersManual.md
+++ b/clang/docs/UsersManual.md
@@ -5296,926 +5296,11 @@ clang-cl.exe: error: no such file or directory: '/foobar'
Please [file a bug](https://github.com/llvm/llvm-project/issues/new?labels=clang-cl)
for any valid cl.exe flags that clang-cl does not understand.
-Execute `clang-cl /?` to see a list of supported options:
-
-> ```
-> CL.EXE COMPATIBILITY OPTIONS:
-> /? Display available options
-> /arch:<value> Set architecture for code generation
-> /arm64EC Set build target to arm64ec
-> /Brepro- Write current time into COFF output (default)
-> /Brepro Do not write current time into COFF output (breaks link.exe /incremental)
-> /clang:<arg> Pass <arg> to the clang driver
-> /C Do not discard comments when preprocessing
-> /c Compile only
-> /d1PP Retain macro definitions in /E mode
-> /d1reportAllClassLayout Dump record layout information
-> /d2epilogunwindrequirev2
-> Require generation of unwind v2 (epilog) information for x64 Windows
-> /d2epilogunwind Best effort generate unwind v2 (epilog) information for x64 Windows
-> /diagnostics:caret Enable caret and column diagnostics (default)
-> /diagnostics:classic Disable column and caret diagnostics
-> /diagnostics:column Disable caret diagnostics but keep column info
-> /diasdkdir <dir> Path to the DIA SDK
-> /D <macro[=value]> Define macro
-> /EH<value> Set exception handling model
-> /EP Disable linemarker output and preprocess to stdout
-> /execution-charset:<value>
-> Set runtime encoding, supports only UTF-8
-> /external:env:<var> Add dirs in env var <var> to include search path with warnings suppressed
-> /external:I <dir> Add directory to include search path with warnings suppressed
-> /external:W0 Ignore warnings from system headers (default)
-> /external:W1 Enable -Wsystem-headers
-> /external:W2 Enable -Wsystem-headers
-> /external:W3 Enable -Wsystem-headers
-> /external:W4 Enable -Wsystem-headers
-> /E Preprocess to stdout
-> /FA<value> Output assembly code file during compilation
-> /Fa<file or dir/> Set assembly output file name (with /FA)
-> /Fe<file or dir/> Set output executable file name
-> /FI <value> Include file before parsing
-> /Fi<file> Set preprocess output file name (with /P)
-> /Fo<file or dir/> Set output object file (with /c)
-> /Fp<file> Set pch file name (with /Yc and /Yu)
-> /fsanitize=address Enable AddressSanitizer
-> /funcoverride:<function>
-> Mark <function> as being replaceable by the Windows kernel loader
-> /GA Assume thread-local variables are defined in the executable
-> /Gd Set __cdecl as a default calling convention
-> /GF- Disable string pooling
-> /GF Enable string pooling (default)
-> /GR- Do not emit RTTI data
-> /Gregcall4 Set __regcall4 as a default calling convention to respect __regcall ABI v.4
-> /Gregcall Set __regcall as a default calling convention
-> /GR Emit RTTI data (default)
-> /Gr Set __fastcall as a default calling convention
-> /GS- Disable buffer security check
-> /GS Enable buffer security check (default)
-> /Gs Use stack probes (default)
-> /Gs<value> Set stack probe size (default 4096)
-> /guard:<value> Enable Control Flow Guard with /guard:cf, or only the table with /guard:cf,nochecks. Enable EH Continuation Guard with /guard:ehcont
-> /Gv Set __vectorcall as a default calling convention
-> /Gw- Do not put each data item in its own section (default)
-> /Gw Put each data item in its own section
-> /GX- Deprecated (like not passing /EH)
-> /GX Deprecated; use /EHsc
-> /Gy- Do not put each function in its own section (default)
-> /Gy Put each function in its own section
-> /Gz Set __stdcall as a default calling convention
-> /help Display available options
-> /hotpatch Create hotpatchable image
-> /imsvc <dir> Add <dir> to system include search path, as if in %INCLUDE%
-> /I <dir> Add directory to include search path
-> /JMC- Disable just-my-code debugging (default)
-> /JMC Enable just-my-code debugging
-> /J Make char type unsigned
-> /LDd Create debug DLL
-> /LD Create DLL
-> /link <options> Forward options to the linker
-> /MDd Use DLL debug run-time
-> /MD Use DLL run-time
-> /MTd Use static debug run-time
-> /MT Use static run-time
-> /O1 Optimize for size (like /Og /Os /Oy /Ob2 /GF /Gy)
-> /O2 Optimize for speed (like /Og /Oi /Ot /Oy /Ob2 /GF /Gy)
-> /Ob0 Disable function inlining
-> /Ob1 Only inline functions explicitly or implicitly marked inline
-> /Ob2 Inline functions as deemed beneficial by the compiler
-> /Ob3 Same as /Ob2
-> /Od Disable optimization
-> /Og No effect
-> /Oi- Disable use of builtin functions
-> /Oi Enable use of builtin functions
-> /openmp- Disable OpenMP support
-> /openmp:experimental Enable OpenMP support with experimental SIMD support
-> /openmp Enable OpenMP support
-> /Os Optimize for size (like clang -Os)
-> /Ot Optimize for speed (like clang -O3)
-> /Ox Deprecated (like /Og /Oi /Ot /Oy /Ob2); use /O2
-> /Oy- Disable frame pointer omission (x86 only, default)
-> /Oy Enable frame pointer omission (x86 only)
-> /O<flags> Set multiple /O flags at once; e.g. '/O2y-' for '/O2 /Oy-'
-> /o <file or dir/> Deprecated (set output file name); use /Fe or /Fe
-> /permissive- Disable non conforming code from compiling (default)
-> /permissive Enable some non conforming code to compile
-> /P Preprocess to file
-> /Qgather- Disable generation of gather instructions in auto-vectorization(x86 only)
-> /QIntel-jcc-erratum Align branches within 32-byte boundaries to mitigate the performance impact of the Intel JCC erratum.
-> /Qscatter- Disable generation of scatter instructions in auto-vectorization(x86 only)
-> /Qvec- Disable the loop vectorization passes
-> /Qvec Enable the loop vectorization passes
-> /showFilenames- Do not print the name of each compiled file (default)
-> /showFilenames Print the name of each compiled file
-> /showIncludes:user Like /showIncludes but omit system headers
-> /showIncludes Print info about included files to stderr
-> /source-charset:<value> Set source encoding, supports only UTF-8
-> /std:<value> Set language version (c++14,c++17,c++20,c++23preview,c++26preview,c++latest,c11,c17)
-> /TC Treat all source files as C
-> /Tc <file> Treat <file> as C source file
-> /TP Treat all source files as C++
-> /Tp <file> Treat <file> as C++ source file
-> /tune:<value> Set CPU for optimization without affecting instruction set
-> /utf-8 Set source and runtime encoding to UTF-8 (default)
-> /U <macro> Undefine macro
-> /vctoolsdir <dir> Path to the VCToolChain
-> /vctoolsversion <value> For use with /winsysroot, defaults to newest found
-> /vd<value> Control vtordisp placement
-> /vlen=256 Set vector length of 256 bits for autovectorization and other optimizations
-> /vlen=512 Set vector length of 512 bits for autovectorization and other optimizations
-> /vlen Set default vector length for autovectorization and other optimizations
-> /vmb Use a best-case representation method for member pointers
-> /vmg Use a most-general representation for member pointers
-> /vmm Set the default most-general representation to multiple inheritance
-> /vms Set the default most-general representation to single inheritance
-> /vmv Set the default most-general representation to virtual inheritance
-> /W0 Disable all warnings
-> /W1 Enable -Wall
-> /W2 Enable -Wall
-> /W3 Enable -Wall
-> /W4 Enable -Wall and -Wextra
-> /Wall Enable -Weverything
-> /winsdkdir <dir> Path to the Windows SDK
-> /winsdkversion <value> Full version of the Windows SDK, defaults to newest found
-> /winsysroot <dir> Same as "/diasdkdir <dir>/DIA SDK" /vctoolsdir <dir>/VC/Tools/MSVC/<vctoolsversion> "/winsdkdir <dir>/Windows Kits/10"
-> /WX- Do not treat warnings as errors (default)
-> /WX Treat warnings as errors
-> /w Disable all warnings
-> /X Do not add %INCLUDE% to include search path
-> /Y- Disable precompiled headers, overrides /Yc and /Yu
-> /Yc<filename> Generate a pch file for all code up to and including <filename>
-> /Yu<filename> Load a pch file and use it instead of all code up to and including <filename>
-> /Z7 Enable CodeView debug information in object files
-> /Zc:__STDC__ Define __STDC__
-> /Zc:alignedNew- Disable C++17 aligned allocation functions
-> /Zc:alignedNew Enable C++17 aligned allocation functions
-> /Zc:char8_t- Disable char8_t from c++2a
-> /Zc:char8_t Enable char8_t from C++2a
-> /Zc:dllexportInlines- Do not dllexport/dllimport inline member functions of dllexport/import classes
-> /Zc:dllexportInlines dllexport/dllimport inline member functions of dllexport/import classes (default)
-> /Zc:sizedDealloc- Disable C++14 sized global deallocation functions
-> /Zc:sizedDealloc Enable C++14 sized global deallocation functions
-> /Zc:strictStrings Treat string literals as const
-> /Zc:threadSafeInit- Disable thread-safe initialization of static variables
-> /Zc:threadSafeInit Enable thread-safe initialization of static variables
-> /Zc:tlsGuards- Disable on-demand initialization of thread-local variables
-> /Zc:tlsGuards Enable on-demand initialization of thread-local variables
-> /Zc:trigraphs- Disable trigraphs (default)
-> /Zc:trigraphs Enable trigraphs
-> /Zc:twoPhase- Disable two-phase name lookup in templates (default)
-> /Zc:twoPhase Enable two-phase name lookup in templates
-> /Zc:wchar_t- Disable C++ builtin type wchar_t
-> /Zc:wchar_t Enable C++ builtin type wchar_t (default)
-> /ZH:MD5 Use MD5 for file checksums in debug info (default)
-> /ZH:SHA1 Use SHA1 for file checksums in debug info
-> /ZH:SHA_256 Use SHA256 for file checksums in debug info
-> /Zi Like /Z7
-> /Zl Do not let object file auto-link default libraries
-> /Zp Set default maximum struct packing alignment to 1
-> /Zp<value> Set default maximum struct packing alignment
-> /Zs Run the preprocessor, parser and semantic analysis stages
->
-> OPTIONS:
-> -### Print (but do not run) the commands to run for this compilation
-> --analyze Run the static analyzer
-> --config=<file> Specify configuration file
-> --cuda-compile-host-device
-> Compile CUDA code for both host and device (default). Has no effect on non-CUDA compilations.
-> --cuda-device-only Compile CUDA code for device only
-> --cuda-feature=<value> Manually specify the CUDA feature to use
-> --cuda-host-only Compile CUDA code for host only. Has no effect on non-CUDA compilations.
-> --cuda-include-ptx=<value>
-> Include PTX for the following GPU architecture (e.g. sm_35) or 'all'. May be specified more than once.
-> --cuda-noopt-device-debug
-> Enable device-side debug info generation. Disables ptxas optimizations.
-> --cuda-path-ignore-env Ignore environment variables to detect CUDA installation
-> --cuda-path=<value> CUDA installation path
-> -cuid=<value> An ID for compilation unit, which should be the same for the same compilation unit but different for different compilation units. It is used to externalize device-side static variables for single source offloading languages CUDA and HIP so that they can be accessed by the host code of the same compilation unit.
-> -darwin-target-variant <value>
-> Generate code for an additional runtime variant of the deployment target
-> -emit-ast Emit Clang AST files for source inputs
-> --end-no-unused-arguments
-> Start emitting warnings for unused driver arguments
-> -faddrsig Emit an address-significance table
-> -fansi-escape-codes Use ANSI escape codes for diagnostics
-> -fblocks Enable the 'blocks' language feature
-> -fcaret-diagnostics-max-lines=<value>
-> Set the maximum number of source lines to show in a caret diagnostic (0 = no limit).
-> -fcf-protection=<value> Instrument control-flow architecture protection
-> -fcf-protection Enable cf-protection in 'full' mode
-> -fcodegen-data-generate=<path>
-> Emit codegen data into the object file. LLD for MachO (currently) merges them into the specified <path>.
-> -fcodegen-data-generate Emit codegen data into the object file. LLD for MachO (currently) merges them into default.cgdata.
-> -fcodegen-data-use=<path>
-> Use codegen data read from the specified <path>.
-> -fcodegen-data-use Use codegen data read from default.cgdata to optimize the binary
-> -fcolor-diagnostics Enable colors in diagnostics
-> -fcommon Place uninitialized global variables in a common block
-> -fcomplete-member-pointers
-> Require member pointer base types to be complete if they would be significant under the Microsoft ABI
-> -fcoverage-compilation-dir=<value>
-> The compilation directory to embed in the coverage mapping.
-> -fcoverage-mapping Generate coverage mapping to enable code coverage analysis
-> -fcoverage-mcdc Enable MC/DC criteria when generating code coverage
-> -fcrash-diagnostics-dir=<dir>
-> Put crash-report files in <dir>
-> -fcrash-diagnostics=<value>
-> Set level of crash diagnostic reporting, (option: off, compiler, all)
-> -fcrash-diagnostics Enable crash diagnostic reporting (default)
-> -fcs-profile-generate=<directory>
-> Generate instrumented code to collect context sensitive execution counts into <directory>/default.profraw (overridden by LLVM_PROFILE_FILE env var)
-> -fcs-profile-generate Generate instrumented code to collect context sensitive execution counts into default.profraw (overridden by LLVM_PROFILE_FILE env var)
-> -fcuda-short-ptr Use 32-bit pointers for accessing const/local/shared address spaces
-> -fdebug-compilation-dir=<value>
-> The compilation directory to embed in the debug info
-> -fdebug-macro Emit macro debug information
-> -fdelayed-template-parsing
-> Parse templated function definitions at the end of the translation unit
-> -fdelete-null-pointer-checks
-> Treat usage of null pointers as undefined behavior (default)
-> -fdevirtualize-speculatively
-> Enables speculative devirtualization optimization.
-> -fdiagnostics-absolute-paths
-> Print absolute paths in diagnostics
-> -fdiagnostics-color=<value>
-> When to use colors in diagnostics
-> -fdiagnostics-parseable-fixits
-> Print fix-its in machine parseable form
-> -fdriver-only Only run the driver.
-> -feliminate-unused-debug-types
-> Do not emit debug info for defined but unused types
-> -fexcess-precision=<value>
-> Allows control over excess precision on targets where native support for the precision types is not available. By default, excess precision is used to calculate intermediate results following the rules specified in ISO C99.
-> -fexperimental-library Control whether unstable and experimental library features are enabled. This option enables various library features that are either experimental (also known as TSes), or have been but are not stable yet in the selected Standard Library implementation. It is not recommended to use this option in production code, since neither ABI nor API stability are guaranteed. This is intended to provide a preview of features that will ship in the future for experimentation purposes
-> -fexperimental-sanitize-metadata-ignorelist=<value>
-> Disable sanitizer metadata for modules and functions that match the provided special case list
-> -fexperimental-sanitize-metadata=<value>
-> Specify the type of metadata to emit for binary analysis sanitizers
-> -ffile-compilation-dir=<value>
-> The compilation directory to embed in the debug info and coverage mapping.
-> -ffile-reproducible Use the target's platform-specific path separator character when expanding the __FILE__ macro
-> -ffixed-x10 Reserve the x10 register (AArch64/RISC-V only)
-> -ffixed-x11 Reserve the x11 register (AArch64/RISC-V only)
-> -ffixed-x12 Reserve the x12 register (AArch64/RISC-V only)
-> -ffixed-x13 Reserve the x13 register (AArch64/RISC-V only)
-> -ffixed-x14 Reserve the x14 register (AArch64/RISC-V only)
-> -ffixed-x15 Reserve the x15 register (AArch64/RISC-V only)
-> -ffixed-x16 Reserve the x16 register (AArch64/RISC-V only)
-> -ffixed-x17 Reserve the x17 register (AArch64/RISC-V only)
-> -ffixed-x18 Reserve the x18 register (AArch64/RISC-V only)
-> -ffixed-x19 Reserve the x19 register (AArch64/RISC-V only)
-> -ffixed-x1 Reserve the x1 register (AArch64/RISC-V only)
-> -ffixed-x20 Reserve the x20 register (AArch64/RISC-V only)
-> -ffixed-x21 Reserve the x21 register (AArch64/RISC-V only)
-> -ffixed-x22 Reserve the x22 register (AArch64/RISC-V only)
-> -ffixed-x23 Reserve the x23 register (AArch64/RISC-V only)
-> -ffixed-x24 Reserve the x24 register (AArch64/RISC-V only)
-> -ffixed-x25 Reserve the x25 register (AArch64/RISC-V only)
-> -ffixed-x26 Reserve the x26 register (AArch64/RISC...
[truncated]
``````````
</details>
https://github.com/llvm/llvm-project/pull/233116
More information about the cfe-commits
mailing list