efriedma created this revision.
efriedma added reviewers: serge-sans-paille, aaron.ballman.
Herald added a subscriber: dschuff.
Herald added a project: All.
efriedma requested review of this revision.
Herald added a subscriber: aheejin.
Herald added a project: clang.
Back when the command-line reference rst was in-tree, a lot of people missed
the "DO NOT EDIT" comment at the top, and then changes were effectively
reverted when the file was regenerated. I went through the changes, and rescued
the interesting bits of documentation that were destroyed. (Noticed when I was
trying to find our documentation for -fno-delete-null-pointer-checks, but it
was missing.)
Additional notes:
- I'm intentionally leaving out D73459 <https://reviews.llvm.org/D73459>
because I'm not sure how to port the changes to -march.
- Some options have help text in Options.td, but that text doesn't make it into
the reference. Incomplete list of such options: -fc++-static-destructors,
-frtti-data, -fplt, -fstrict-return, -funique-section-names, -fuse-init-array.
I think there's something specifically weird with boolean options, but not
completely sure what's happening.
Repository:
rG LLVM Github Monorepo
https://reviews.llvm.org/D152396
Files:
clang/include/clang/Driver/Options.td
Index: clang/include/clang/Driver/Options.td
===================================================================
--- clang/include/clang/Driver/Options.td
+++ clang/include/clang/Driver/Options.td
@@ -1421,7 +1421,8 @@
HelpText<"Generate instrumented code to collect order file into default.profraw file (overridden by '=' form of option or LLVM_PROFILE_FILE env var)">;
def fprofile_list_EQ : Joined<["-"], "fprofile-list=">,
Group<f_Group>, Flags<[CC1Option, CoreOption]>,
- HelpText<"Filename defining the list of functions/files to instrument">,
+ HelpText<"Filename defining the list of functions/files to instrument. "
+ "The file uses the sanitizer special case list format.">,
MarshallingInfoStringVector<LangOpts<"ProfileListFiles">>;
def fprofile_function_groups : Joined<["-"], "fprofile-function-groups=">,
Group<f_Group>, Flags<[CC1Option]>, MetaVarName<"<N>">,
@@ -1477,6 +1478,13 @@
def fparse_all_comments : Flag<["-"], "fparse-all-comments">, Group<f_clang_Group>, Flags<[CC1Option]>,
MarshallingInfoFlag<LangOpts<"CommentOpts.ParseAllComments">>;
def frecord_command_line : Flag<["-"], "frecord-command-line">,
+ DocBrief<[{Generate a section named ".GCC.command.line" containing the clang
+driver command-line. After linking, the section may contain multiple command
+lines, which will be individually terminated by null bytes. Separate arguments
+within a command line are combined with spaces; spaces and backslashes within an
+argument are escaped with backslashes. This format differs from the format of
+the equivalent section produced by GCC with the -frecord-gcc-switches flag.
+This option is currently only supported on ELF targets.}]>,
Group<f_clang_Group>;
def fno_record_command_line : Flag<["-"], "fno-record-command-line">,
Group<f_clang_Group>;
@@ -1484,7 +1492,10 @@
def : Flag<["-"], "fno-record-gcc-switches">, Alias<fno_record_command_line>;
def fcommon : Flag<["-"], "fcommon">, Group<f_Group>,
Flags<[CoreOption, CC1Option]>, HelpText<"Place uninitialized global variables in a common block">,
- MarshallingInfoNegativeFlag<CodeGenOpts<"NoCommon">>;
+ MarshallingInfoNegativeFlag<CodeGenOpts<"NoCommon">>,
+ DocBrief<[{Place definitions of variables with no storage class and no initializer
+(tentative definitions) in a common block, instead of generating individual
+zero-initialized definitions (default -fno-common).}]>;
def fcompile_resource_EQ : Joined<["-"], "fcompile-resource=">, Group<f_Group>;
defm complete_member_pointers : BoolOption<"f", "complete-member-pointers",
LangOpts<"CompleteMemberPointers">, DefaultFalse,
@@ -1723,7 +1734,7 @@
defm keep_static_consts : BoolFOption<"keep-static-consts",
CodeGenOpts<"KeepStaticConsts">, DefaultFalse,
PosFlag<SetTrue, [CC1Option], "Keep">, NegFlag<SetFalse, [], "Don't keep">,
- BothFlags<[NoXarchOption], " static const variables if unused">>;
+ BothFlags<[NoXarchOption], " static const variables even if unused">>;
defm fixed_point : BoolFOption<"fixed-point",
LangOpts<"FixedPoint">, DefaultFalse,
PosFlag<SetTrue, [CC1Option], "Enable">, NegFlag<SetFalse, [], "Disable">,
@@ -1854,6 +1865,17 @@
CodeGenOpts<"SanitizeAddressPoisonCustomArrayCookie">, DefaultFalse,
PosFlag<SetTrue, [], "Enable">, NegFlag<SetFalse, [], "Disable">,
BothFlags<[], " poisoning array cookies when using custom operator new[] in AddressSanitizer">>,
+ DocBrief<[{Enable "poisoning" array cookies when allocating arrays with a
+custom operator new\[\] in Address Sanitizer, preventing accesses to the
+cookies from user code. An array cookie is a small implementation-defined
+header added to certain array allocations to record metadata such as the
+length of the array. Accesses to array cookies from user code are technically
+allowed by the standard but are more likely to be the result of an
+out-of-bounds array access.
+
+An operator new\[\] is "custom" if it is not one of the allocation functions
+provided by the C++ standard library. Array cookies from non-custom allocation
+functions are always poisoned.}]>,
Group<f_clang_Group>;
defm sanitize_address_globals_dead_stripping : BoolOption<"f", "sanitize-address-globals-dead-stripping",
CodeGenOpts<"SanitizeAddressGlobalsDeadStripping">, DefaultFalse,
@@ -1869,7 +1891,10 @@
def sanitize_address_destructor_EQ
: Joined<["-"], "fsanitize-address-destructor=">,
Flags<[CC1Option]>,
- HelpText<"Set destructor type used in ASan instrumentation">,
+ HelpText<"Set the kind of module destructors emitted by "
+ "AddressSanitizer instrumentation. These destructors are "
+ "emitted to unregister instrumented global variables when "
+ "code is unloaded (e.g. via `dlclose()`).">,
Group<f_clang_Group>,
Values<"none,global">,
NormalizedValuesScope<"llvm::AsanDtorKind">,
@@ -2005,16 +2030,24 @@
NegFlag<SetFalse>>;
defm finite_math_only : BoolFOption<"finite-math-only",
LangOpts<"FiniteMathOnly">, DefaultFalse,
- PosFlag<SetTrue, [CC1Option], "", [cl_finite_math_only.KeyPath, ffast_math.KeyPath]>,
+ PosFlag<SetTrue, [CC1Option], "Allow floating-point optimizations that "
+ "assume arguments and results are not NaNs or +-inf. This defines "
+ "the \\_\\_FINITE\\_MATH\\_ONLY\\_\\_ preprocessor macro.",
+ [cl_finite_math_only.KeyPath, ffast_math.KeyPath]>,
NegFlag<SetFalse>>;
defm signed_zeros : BoolFOption<"signed-zeros",
LangOpts<"NoSignedZero">, DefaultFalse,
NegFlag<SetTrue, [CC1Option, FC1Option, FlangOption], "Allow optimizations that ignore the sign of floating point zeros",
[cl_no_signed_zeros.KeyPath, funsafe_math_optimizations.KeyPath]>,
PosFlag<SetFalse>>;
-def fhonor_nans : Flag<["-"], "fhonor-nans">, Group<f_Group>;
+def fhonor_nans : Flag<["-"], "fhonor-nans">, Group<f_Group>,
+ HelpText<"Specify that floating-point optimizations are not allowed that "
+ "assume arguments and results are not NANs.">;
def fno_honor_nans : Flag<["-"], "fno-honor-nans">, Group<f_Group>;
-def fhonor_infinities : Flag<["-"], "fhonor-infinities">, Group<f_Group>;
+def fhonor_infinities : Flag<["-"], "fhonor-infinities">,
+ Group<f_Group>,
+ HelpText<"Specify that floating-point optimizations are not allowed that "
+ "assume arguments and results are not +-inf.">;
def fno_honor_infinities : Flag<["-"], "fno-honor-infinities">, Group<f_Group>;
// This option was originally misspelt "infinites" [sic].
def : Flag<["-"], "fhonor-infinites">, Alias<fhonor_infinities>;
@@ -2065,14 +2098,25 @@
CodeGenOpts<"NullPointerIsValid">, DefaultFalse,
NegFlag<SetTrue, [CC1Option], "Do not treat usage of null pointers as undefined behavior">,
PosFlag<SetFalse, [], "Treat usage of null pointers as undefined behavior (default)">,
- BothFlags<[CoreOption]>>;
+ BothFlags<[CoreOption]>>,
+ DocBrief<[{When enabled, treat null pointer dereference, creation of a reference to null,
+or passing a null pointer to a function parameter annotated with the "nonnull"
+attribute as undefined behavior. (And, thus the optimizer may assume that any
+pointer used in such a way must not have been null and optimize away the
+branches accordingly.) On by default.}]>;
defm use_line_directives : BoolFOption<"use-line-directives",
PreprocessorOutputOpts<"UseLineDirectives">, DefaultFalse,
PosFlag<SetTrue, [CC1Option], "Use #line in preprocessed output">, NegFlag<SetFalse>>;
defm minimize_whitespace : BoolFOption<"minimize-whitespace",
PreprocessorOutputOpts<"MinimizeWhitespace">, DefaultFalse,
- PosFlag<SetTrue, [CC1Option], "Minimize whitespace when emitting preprocessor output">, NegFlag<SetFalse>>;
+ PosFlag<SetTrue, [CC1Option], "Ignore the whitespace from the input file "
+ "when emitting preprocessor output. It will only contain whitespace "
+ "when necessary, e.g. to keep two minus signs from merging into to "
+ "an increment operator. Useful with the -P option to normalize "
+ "whitespace such that two files with only formatting changes are "
+ "equal.\n\nOnly valid with -E on C-like inputs and incompatible "
+ "with -traditional-cpp.">, NegFlag<SetFalse>>;
def ffreestanding : Flag<["-"], "ffreestanding">, Group<f_Group>, Flags<[CC1Option]>,
HelpText<"Assert that the compilation takes place in a freestanding environment">,
@@ -2120,7 +2164,7 @@
Alias<fglobal_isel>;
def fexperimental_strict_floating_point : Flag<["-"], "fexperimental-strict-floating-point">,
Group<f_clang_Group>, Flags<[CC1Option]>,
- HelpText<"Enables experimental strict floating point in LLVM.">,
+ HelpText<"Enables the use of non-default rounding modes and non-default exception handling on targets that are not currently ready.">,
MarshallingInfoFlag<LangOpts<"ExpStrictFP">>;
def finput_charset_EQ : Joined<["-"], "finput-charset=">, Flags<[FlangOption, FC1Option]>, Group<f_Group>,
HelpText<"Specify the default character set for source files">;
@@ -2917,7 +2961,8 @@
defm stack_clash_protection : BoolFOption<"stack-clash-protection",
CodeGenOpts<"StackClashProtector">, DefaultFalse,
PosFlag<SetTrue, [CC1Option], "Enable">, NegFlag<SetFalse, [], "Disable">,
- BothFlags<[], " stack clash protection">>;
+ BothFlags<[], " stack clash protection">>,
+ DocBrief<"Instrument stack allocation to prevent stack clash attacks">;
def fstack_protector_strong : Flag<["-"], "fstack-protector-strong">, Group<f_Group>,
HelpText<"Enable stack protectors for some functions vulnerable to stack smashing. "
"Compared to -fstack-protector, this uses a stronger heuristic "
@@ -3164,7 +3209,10 @@
defm force_emit_vtables : BoolFOption<"force-emit-vtables",
CodeGenOpts<"ForceEmitVTables">, DefaultFalse,
PosFlag<SetTrue, [CC1Option], "Emits more virtual tables to improve devirtualization">,
- NegFlag<SetFalse>, BothFlags<[CoreOption]>>;
+ NegFlag<SetFalse>, BothFlags<[CoreOption]>>,
+ DocBrief<[{In order to improve devirtualization, forces emitting of vtables even in
+modules where it isn't necessary. It causes more inline virtual functions
+to be emitted.}]>;
defm virtual_function_elimination : BoolFOption<"virtual-function-elimination",
CodeGenOpts<"VirtualFunctionElimination">, DefaultFalse,
PosFlag<SetTrue, [CC1Option], "Enables dead virtual function elimination optimization. Requires -flto=full">,
@@ -3360,7 +3408,9 @@
def : Flag<["-"], "gno-record-gcc-switches">, Alias<gno_record_command_line>;
defm strict_dwarf : BoolOption<"g", "strict-dwarf",
CodeGenOpts<"DebugStrictDwarf">, DefaultFalse,
- PosFlag<SetTrue, [CC1Option]>, NegFlag<SetFalse>, BothFlags<[CoreOption]>>,
+ PosFlag<SetTrue, [CC1Option], "Restrict DWARF features to those defined in "
+ "the specified version, avoiding features from later versions.">,
+ NegFlag<SetFalse>, BothFlags<[CoreOption]>>,
Group<g_flags_Group>;
defm column_info : BoolOption<"g", "column-info",
CodeGenOpts<"DebugColumnInfo">, DefaultTrue,
@@ -3710,7 +3760,7 @@
HelpText<"Allow memory accesses to be unaligned (same as munaligned-access)">;
def mno_thumb : Flag<["-"], "mno-thumb">, Group<m_arm_Features_Group>;
def mrestrict_it: Flag<["-"], "mrestrict-it">, Group<m_arm_Features_Group>,
- HelpText<"Disallow generation of complex IT blocks.">;
+ HelpText<"Disallow generation of complex IT blocks. It is off by default.">;
def mno_restrict_it: Flag<["-"], "mno-restrict-it">, Group<m_arm_Features_Group>,
HelpText<"Allow generation of complex IT blocks.">;
def marm : Flag<["-"], "marm">, Alias<mno_thumb>;
@@ -3838,7 +3888,11 @@
def mno_extended_const : Flag<["-"], "mno-extended-const">, Group<m_wasm_Features_Group>;
def mexec_model_EQ : Joined<["-"], "mexec-model=">, Group<m_wasm_Features_Driver_Group>,
Values<"command,reactor">,
- HelpText<"Execution model (WebAssembly only)">;
+ HelpText<"Execution model (WebAssembly only)">,
+ DocBrief<"Select between \"command\" and \"reactor\" executable models. "
+ "Commands have a main-function which scopes the lifetime of the "
+ "program. Reactors are activated and remain active until "
+ "explicitly terminated.">;
defm amdgpu_ieee : BoolOption<"m", "amdgpu-ieee",
CodeGenOpts<"EmitIEEENaNCompliantInsts">, DefaultTrue,
@@ -3867,12 +3921,16 @@
defm unsafe_fp_atomics : BoolOption<"m", "unsafe-fp-atomics",
TargetOpts<"AllowAMDGPUUnsafeFPAtomics">, DefaultFalse,
- PosFlag<SetTrue, [CC1Option], "Enable unsafe floating point atomic instructions (AMDGPU only)">,
+ PosFlag<SetTrue, [CC1Option], "Enable generation of unsafe floating point "
+ "atomic instructions. May generate more efficient code, but may not "
+ "respect rounding and denormal modes, and may give incorrect results "
+ "for certain memory destinations. (AMDGPU only)">,
NegFlag<SetFalse>>, Group<m_Group>;
def faltivec : Flag<["-"], "faltivec">, Group<f_Group>, Flags<[NoXarchOption]>;
def fno_altivec : Flag<["-"], "fno-altivec">, Group<f_Group>, Flags<[NoXarchOption]>;
-def maltivec : Flag<["-"], "maltivec">, Group<m_ppc_Features_Group>;
+def maltivec : Flag<["-"], "maltivec">, Group<m_ppc_Features_Group>,
+ HelpText<"Enable AltiVec vector initializer syntax">;
def mno_altivec : Flag<["-"], "mno-altivec">, Group<m_ppc_Features_Group>;
def mpcrel: Flag<["-"], "mpcrel">, Group<m_ppc_Features_Group>;
def mno_pcrel: Flag<["-"], "mno-pcrel">, Group<m_ppc_Features_Group>;
@@ -3926,7 +3984,11 @@
def mno_mfcrf : Flag<["-"], "mno-mfcrf">, Alias<mno_mfocrf>;
def mpopcntd : Flag<["-"], "mpopcntd">, Group<m_ppc_Features_Group>;
def mno_popcntd : Flag<["-"], "mno-popcntd">, Group<m_ppc_Features_Group>;
-def mcrbits : Flag<["-"], "mcrbits">, Group<m_ppc_Features_Group>;
+def mcrbits : Flag<["-"], "mcrbits">, Group<m_ppc_Features_Group>,
+ HelpText<"Control the CR-bit tracking feature on PowerPC. ``-mcrbits`` "
+ "(the enablement of CR-bit tracking support) is the default for "
+ "POWER8 and above, as well as for all other CPUs when "
+ "optimization is applied (-O2 and above).">;
def mno_crbits : Flag<["-"], "mno-crbits">, Group<m_ppc_Features_Group>;
def minvariant_function_descriptors :
Flag<["-"], "minvariant-function-descriptors">, Group<m_ppc_Features_Group>;
@@ -3949,10 +4011,15 @@
Group<m_ppc_Features_Group>;
def maix_struct_return : Flag<["-"], "maix-struct-return">,
Group<m_Group>, Flags<[CC1Option]>,
- HelpText<"Return all structs in memory (PPC32 only)">;
+ HelpText<"Return all structs in memory (PPC32 only)">,
+ DocBrief<"Override the default ABI for 32-bit targets to return all "
+ "structs in memory, as in the Power 32-bit ABI for Linux (2011), "
+ "and on AIX and Darwin.">;
def msvr4_struct_return : Flag<["-"], "msvr4-struct-return">,
Group<m_Group>, Flags<[CC1Option]>,
- HelpText<"Return small structs in registers (PPC32 only)">;
+ HelpText<"Return small structs in registers (PPC32 only)">,
+ DocBrief<"Override the default ABI for 32-bit targets to return small "
+ "structs in registers, as in the System V ABI (1995).">;
def mxcoff_roptr : Flag<["-"], "mxcoff-roptr">, Group<m_Group>, Flags<[CC1Option,TargetSpecific]>,
HelpText<"Place constant objects with relocatable address values in the RO data section and add -bforceimprw to the linker flags (AIX only)">;
def mno_xcoff_roptr : Flag<["-"], "mno-xcoff-roptr">, Group<m_Group>, TargetSpecific;
@@ -5005,7 +5072,10 @@
defm ivopts : BooleanFFlag<"ivopts">, Group<clang_ignored_gcc_optimization_f_Group>;
defm semantic_interposition : BoolFOption<"semantic-interposition",
LangOpts<"SemanticInterposition">, DefaultFalse,
- PosFlag<SetTrue, [CC1Option]>, NegFlag<SetFalse>>;
+ PosFlag<SetTrue, [CC1Option]>, NegFlag<SetFalse>>,
+ DocBrief<[{Enable semantic interposition. Semantic interposition allows for the
+interposition of a symbol by another at runtime, thus preventing a range of
+inter-procedural optimisation.}]>;
defm non_call_exceptions : BooleanFFlag<"non-call-exceptions">, Group<clang_ignored_f_Group>;
defm peel_loops : BooleanFFlag<"peel-loops">, Group<clang_ignored_gcc_optimization_f_Group>;
defm permissive : BooleanFFlag<"permissive">, Group<clang_ignored_f_Group>;
_______________________________________________
cfe-commits mailing list
cfe-commits@lists.llvm.org
https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits
