[clang][Docs] Move debug info flags into groups #169942
Open
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This moves a few existing debug info flags that were floating in the general pool of unorganised flags over to the existing groups for debug info flags (so that they are presented together in documentation). As a tiny further tweak, this also fixes the spelling of "DWARF" in the flag docs for consistency with other flags.
jryans
requested review from
CarlosAlbertoEnciso,
OCHyams,
SLTozer and
jmorse
jryans
added
documentation
clang
Member
|
@llvm/pr-subscribers-clang Author: J. Ryan Stinnett (jryans) ChangesThis moves a few existing debug info flags that were floating in the general pool of unorganised flags over to the existing groups for debug info flags (so that they are presented together in documentation). As a tiny further tweak, this also fixes the spelling of "DWARF" in the flag docs for consistency with other flags. Full diff: https://github.com/llvm/llvm-project/pull/169942.diff 1 Files Affected:
diff --git a/clang/include/clang/Options/Options.td b/clang/include/clang/Options/Options.td
index 756d6deed7130..d31bd7d6be322 100644
--- a/clang/include/clang/Options/Options.td
+++ b/clang/include/clang/Options/Options.td
@@ -4765,25 +4765,25 @@ def ggdb3 : Flag<["-"], "ggdb3">, Group<ggdbN_Group>;
def glldb : Flag<["-"], "glldb">, Group<gTune_Group>;
def gsce : Flag<["-"], "gsce">, Group<gTune_Group>;
def gdbx : Flag<["-"], "gdbx">, Group<gTune_Group>;
-// Equivalent to our default dwarf version. Forces usual dwarf emission when
+// Equivalent to our default DWARF version. Forces usual DWARF emission when
// CodeView is enabled.
def gdwarf : Flag<["-"], "gdwarf">, Group<g_Group>,
Visibility<[ClangOption, CLOption, DXCOption, FlangOption]>,
- HelpText<"Generate source-level debug information with the default dwarf version">;
+ HelpText<"Generate source-level debug information with the default DWARF version">;
let Visibility = [ClangOption, FlangOption] in {
def gdwarf_2 : Flag<["-"], "gdwarf-2">, Group<g_Group>,
- HelpText<"Generate source-level debug information with dwarf version 2">;
+ HelpText<"Generate source-level debug information with DWARF version 2">;
def gdwarf_3 : Flag<["-"], "gdwarf-3">, Group<g_Group>,
- HelpText<"Generate source-level debug information with dwarf version 3">;
+ HelpText<"Generate source-level debug information with DWARF version 3">;
def gdwarf_4 : Flag<["-"], "gdwarf-4">, Group<g_Group>,
- HelpText<"Generate source-level debug information with dwarf version 4">;
+ HelpText<"Generate source-level debug information with DWARF version 4">;
def gdwarf_5 : Flag<["-"], "gdwarf-5">, Group<g_Group>,
- HelpText<"Generate source-level debug information with dwarf version 5">;
+ HelpText<"Generate source-level debug information with DWARF version 5">;
def gdwarf_6
: Flag<["-"], "gdwarf-6">,
Group<g_Group>,
- HelpText<"Generate source-level debug information with dwarf version 6">;
+ HelpText<"Generate source-level debug information with DWARF version 6">;
}
def gdwarf64 : Flag<["-"], "gdwarf64">, Group<g_Group>,
Visibility<[ClangOption, CC1Option, CC1AsOption]>,
@@ -4793,7 +4793,7 @@ def gdwarf32 : Flag<["-"], "gdwarf32">, Group<g_Group>,
Visibility<[ClangOption, CC1Option, CC1AsOption]>,
HelpText<"Enables DWARF32 format for ELF binaries, if debug information emission is enabled.">;
-def gcodeview : Flag<["-"], "gcodeview">,
+def gcodeview : Flag<["-"], "gcodeview">, Group<g_Group>,
HelpText<"Generate CodeView debug information">,
Visibility<[ClangOption, CC1Option, CC1AsOption, CLOption, DXCOption]>,
MarshallingInfoFlag<CodeGenOpts<"EmitCodeView">>;
@@ -4801,17 +4801,20 @@ defm codeview_ghash : BoolOption<"g", "codeview-ghash",
CodeGenOpts<"CodeViewGHash">, DefaultFalse,
PosFlag<SetTrue, [], [ClangOption, CC1Option],
"Emit type record hashes in a .debug$H section">,
- NegFlag<SetFalse>, BothFlags<[], [ClangOption, CLOption, DXCOption]>>;
+ NegFlag<SetFalse>, BothFlags<[], [ClangOption, CLOption, DXCOption]>>,
+ Group<g_flags_Group>;
defm codeview_command_line : BoolOption<"g", "codeview-command-line",
CodeGenOpts<"CodeViewCommandLine">, DefaultTrue,
PosFlag<SetTrue, [], [ClangOption], "Emit compiler path and command line into CodeView debug information">,
NegFlag<SetFalse, [], [ClangOption], "Don't emit compiler path and command line into CodeView debug information">,
- BothFlags<[], [ClangOption, CLOption, DXCOption, CC1Option]>>;
+ BothFlags<[], [ClangOption, CLOption, DXCOption, CC1Option]>>,
+ Group<g_flags_Group>;
defm inline_line_tables : BoolGOption<"inline-line-tables",
CodeGenOpts<"NoInlineLineTables">, DefaultFalse,
NegFlag<SetTrue, [], [ClangOption, CC1Option],
"Don't emit inline line tables.">,
- PosFlag<SetFalse>, BothFlags<[], [ClangOption, CLOption, DXCOption]>>;
+ PosFlag<SetFalse>, BothFlags<[], [ClangOption, CLOption, DXCOption]>>,
+ Group<g_flags_Group>;
def gfull : Flag<["-"], "gfull">, Group<g_Group>;
def gused : Flag<["-"], "gused">, Group<g_Group>;
@@ -4836,7 +4839,8 @@ defm strict_dwarf : BoolOption<"g", "strict-dwarf",
defm omit_unreferenced_methods : BoolGOption<"omit-unreferenced-methods",
CodeGenOpts<"DebugOmitUnreferencedMethods">, DefaultFalse,
NegFlag<SetFalse>,
- PosFlag<SetTrue, [], [CC1Option]>, BothFlags<[], [ClangOption, CLOption, DXCOption]>>;
+ PosFlag<SetTrue, [], [CC1Option]>, BothFlags<[], [ClangOption, CLOption, DXCOption]>>,
+ Group<g_flags_Group>;
defm column_info : BoolOption<"g", "column-info",
CodeGenOpts<"DebugColumnInfo">, DefaultTrue,
NegFlag<SetFalse, [], [ClangOption, CC1Option]>,
@@ -4903,6 +4907,7 @@ defm structor_decl_linkage_names
"Attach linkage names to C++ constructor/destructor "
"declarations in DWARF.">,
BothFlags<[], [ClangOption, CLOption, CC1Option]>>,
+ Group<g_flags_Group>,
DocBrief<[{On some ABIs (e.g., Itanium), constructors and destructors may have multiple variants. Historically, when generating DWARF, Clang did not attach ``DW_AT_linkage_name`` to structor DIEs because there were multiple possible manglings (depending on the structor variant) that could be used. With ``-gstructor-decl-linkage-names``, for ABIs with structor variants, we attach a "unified" mangled name to structor declarations DIEs which debuggers can use to look up all the definitions for a structor declaration. E.g., a "unified" mangled name ``_ZN3FooC4Ev`` may have multiple definitions associated with it such as ``_ZN3FooC1Ev`` and ``_ZN3FooC2Ev``.
Enabling this flag results in a better interactive debugging experience (both GDB and LLDB have support for understanding these "unified" linkage names). However, it comes with a significant increase in debug-info size (particularly the `.debug_str` section). As an escape hatch, users can disable this feature using ``-gno-structor-decl-linkage-names``.}]>;
@@ -4911,7 +4916,8 @@ defm key_instructions : BoolGOption<"key-instructions",
NegFlag<SetFalse>, PosFlag<SetTrue, [], [],
"Enable Key Instructions, which reduces the jumpiness of debug stepping in optimized C/C++ code"
" in some debuggers. DWARF only.">,
- BothFlags<[], [ClangOption, CLOption, CC1Option]>>;
+ BothFlags<[], [ClangOption, CLOption, CC1Option]>>,
+ Group<g_flags_Group>;
def headerpad__max__install__names : Joined<["-"], "headerpad_max_install_names">;
def help : Flag<["-", "--"], "help">,
Visibility<[ClangOption, CC1Option, CC1AsOption,
@@ -8530,7 +8536,7 @@ def main_file_name : Separate<["-"], "main-file-name">,
Visibility<[CC1Option, CC1AsOption]>,
MarshallingInfoString<CodeGenOpts<"MainFileName">>;
def split_dwarf_output : Separate<["-"], "split-dwarf-output">,
- HelpText<"File name to use for split dwarf debug info output">,
+ HelpText<"File name to use for split DWARF debug info output">,
Visibility<[CC1Option, CC1AsOption, FC1Option]>,
MarshallingInfoString<CodeGenOpts<"SplitDwarfOutput">>;
@@ -8564,7 +8570,7 @@ def dependent_lib : Joined<["--"], "dependent-lib=">,
MarshallingInfoStringVector<CodeGenOpts<"DependentLibraries">>;
def split_dwarf_file : Separate<["-"], "split-dwarf-file">,
- HelpText<"Name of the split dwarf debug info file to encode in the object file">,
+ HelpText<"Name of the split DWARF debug info file to encode in the object file">,
MarshallingInfoString<CodeGenOpts<"SplitDwarfFile">>;
} // let Visibility = [CC1Option, FC1Option]
|
Member
|
@llvm/pr-subscribers-debuginfo Author: J. Ryan Stinnett (jryans) ChangesThis moves a few existing debug info flags that were floating in the general pool of unorganised flags over to the existing groups for debug info flags (so that they are presented together in documentation). As a tiny further tweak, this also fixes the spelling of "DWARF" in the flag docs for consistency with other flags. Full diff: https://github.com/llvm/llvm-project/pull/169942.diff 1 Files Affected:
diff --git a/clang/include/clang/Options/Options.td b/clang/include/clang/Options/Options.td
index 756d6deed7130..d31bd7d6be322 100644
--- a/clang/include/clang/Options/Options.td
+++ b/clang/include/clang/Options/Options.td
@@ -4765,25 +4765,25 @@ def ggdb3 : Flag<["-"], "ggdb3">, Group<ggdbN_Group>;
def glldb : Flag<["-"], "glldb">, Group<gTune_Group>;
def gsce : Flag<["-"], "gsce">, Group<gTune_Group>;
def gdbx : Flag<["-"], "gdbx">, Group<gTune_Group>;
-// Equivalent to our default dwarf version. Forces usual dwarf emission when
+// Equivalent to our default DWARF version. Forces usual DWARF emission when
// CodeView is enabled.
def gdwarf : Flag<["-"], "gdwarf">, Group<g_Group>,
Visibility<[ClangOption, CLOption, DXCOption, FlangOption]>,
- HelpText<"Generate source-level debug information with the default dwarf version">;
+ HelpText<"Generate source-level debug information with the default DWARF version">;
let Visibility = [ClangOption, FlangOption] in {
def gdwarf_2 : Flag<["-"], "gdwarf-2">, Group<g_Group>,
- HelpText<"Generate source-level debug information with dwarf version 2">;
+ HelpText<"Generate source-level debug information with DWARF version 2">;
def gdwarf_3 : Flag<["-"], "gdwarf-3">, Group<g_Group>,
- HelpText<"Generate source-level debug information with dwarf version 3">;
+ HelpText<"Generate source-level debug information with DWARF version 3">;
def gdwarf_4 : Flag<["-"], "gdwarf-4">, Group<g_Group>,
- HelpText<"Generate source-level debug information with dwarf version 4">;
+ HelpText<"Generate source-level debug information with DWARF version 4">;
def gdwarf_5 : Flag<["-"], "gdwarf-5">, Group<g_Group>,
- HelpText<"Generate source-level debug information with dwarf version 5">;
+ HelpText<"Generate source-level debug information with DWARF version 5">;
def gdwarf_6
: Flag<["-"], "gdwarf-6">,
Group<g_Group>,
- HelpText<"Generate source-level debug information with dwarf version 6">;
+ HelpText<"Generate source-level debug information with DWARF version 6">;
}
def gdwarf64 : Flag<["-"], "gdwarf64">, Group<g_Group>,
Visibility<[ClangOption, CC1Option, CC1AsOption]>,
@@ -4793,7 +4793,7 @@ def gdwarf32 : Flag<["-"], "gdwarf32">, Group<g_Group>,
Visibility<[ClangOption, CC1Option, CC1AsOption]>,
HelpText<"Enables DWARF32 format for ELF binaries, if debug information emission is enabled.">;
-def gcodeview : Flag<["-"], "gcodeview">,
+def gcodeview : Flag<["-"], "gcodeview">, Group<g_Group>,
HelpText<"Generate CodeView debug information">,
Visibility<[ClangOption, CC1Option, CC1AsOption, CLOption, DXCOption]>,
MarshallingInfoFlag<CodeGenOpts<"EmitCodeView">>;
@@ -4801,17 +4801,20 @@ defm codeview_ghash : BoolOption<"g", "codeview-ghash",
CodeGenOpts<"CodeViewGHash">, DefaultFalse,
PosFlag<SetTrue, [], [ClangOption, CC1Option],
"Emit type record hashes in a .debug$H section">,
- NegFlag<SetFalse>, BothFlags<[], [ClangOption, CLOption, DXCOption]>>;
+ NegFlag<SetFalse>, BothFlags<[], [ClangOption, CLOption, DXCOption]>>,
+ Group<g_flags_Group>;
defm codeview_command_line : BoolOption<"g", "codeview-command-line",
CodeGenOpts<"CodeViewCommandLine">, DefaultTrue,
PosFlag<SetTrue, [], [ClangOption], "Emit compiler path and command line into CodeView debug information">,
NegFlag<SetFalse, [], [ClangOption], "Don't emit compiler path and command line into CodeView debug information">,
- BothFlags<[], [ClangOption, CLOption, DXCOption, CC1Option]>>;
+ BothFlags<[], [ClangOption, CLOption, DXCOption, CC1Option]>>,
+ Group<g_flags_Group>;
defm inline_line_tables : BoolGOption<"inline-line-tables",
CodeGenOpts<"NoInlineLineTables">, DefaultFalse,
NegFlag<SetTrue, [], [ClangOption, CC1Option],
"Don't emit inline line tables.">,
- PosFlag<SetFalse>, BothFlags<[], [ClangOption, CLOption, DXCOption]>>;
+ PosFlag<SetFalse>, BothFlags<[], [ClangOption, CLOption, DXCOption]>>,
+ Group<g_flags_Group>;
def gfull : Flag<["-"], "gfull">, Group<g_Group>;
def gused : Flag<["-"], "gused">, Group<g_Group>;
@@ -4836,7 +4839,8 @@ defm strict_dwarf : BoolOption<"g", "strict-dwarf",
defm omit_unreferenced_methods : BoolGOption<"omit-unreferenced-methods",
CodeGenOpts<"DebugOmitUnreferencedMethods">, DefaultFalse,
NegFlag<SetFalse>,
- PosFlag<SetTrue, [], [CC1Option]>, BothFlags<[], [ClangOption, CLOption, DXCOption]>>;
+ PosFlag<SetTrue, [], [CC1Option]>, BothFlags<[], [ClangOption, CLOption, DXCOption]>>,
+ Group<g_flags_Group>;
defm column_info : BoolOption<"g", "column-info",
CodeGenOpts<"DebugColumnInfo">, DefaultTrue,
NegFlag<SetFalse, [], [ClangOption, CC1Option]>,
@@ -4903,6 +4907,7 @@ defm structor_decl_linkage_names
"Attach linkage names to C++ constructor/destructor "
"declarations in DWARF.">,
BothFlags<[], [ClangOption, CLOption, CC1Option]>>,
+ Group<g_flags_Group>,
DocBrief<[{On some ABIs (e.g., Itanium), constructors and destructors may have multiple variants. Historically, when generating DWARF, Clang did not attach ``DW_AT_linkage_name`` to structor DIEs because there were multiple possible manglings (depending on the structor variant) that could be used. With ``-gstructor-decl-linkage-names``, for ABIs with structor variants, we attach a "unified" mangled name to structor declarations DIEs which debuggers can use to look up all the definitions for a structor declaration. E.g., a "unified" mangled name ``_ZN3FooC4Ev`` may have multiple definitions associated with it such as ``_ZN3FooC1Ev`` and ``_ZN3FooC2Ev``.
Enabling this flag results in a better interactive debugging experience (both GDB and LLDB have support for understanding these "unified" linkage names). However, it comes with a significant increase in debug-info size (particularly the `.debug_str` section). As an escape hatch, users can disable this feature using ``-gno-structor-decl-linkage-names``.}]>;
@@ -4911,7 +4916,8 @@ defm key_instructions : BoolGOption<"key-instructions",
NegFlag<SetFalse>, PosFlag<SetTrue, [], [],
"Enable Key Instructions, which reduces the jumpiness of debug stepping in optimized C/C++ code"
" in some debuggers. DWARF only.">,
- BothFlags<[], [ClangOption, CLOption, CC1Option]>>;
+ BothFlags<[], [ClangOption, CLOption, CC1Option]>>,
+ Group<g_flags_Group>;
def headerpad__max__install__names : Joined<["-"], "headerpad_max_install_names">;
def help : Flag<["-", "--"], "help">,
Visibility<[ClangOption, CC1Option, CC1AsOption,
@@ -8530,7 +8536,7 @@ def main_file_name : Separate<["-"], "main-file-name">,
Visibility<[CC1Option, CC1AsOption]>,
MarshallingInfoString<CodeGenOpts<"MainFileName">>;
def split_dwarf_output : Separate<["-"], "split-dwarf-output">,
- HelpText<"File name to use for split dwarf debug info output">,
+ HelpText<"File name to use for split DWARF debug info output">,
Visibility<[CC1Option, CC1AsOption, FC1Option]>,
MarshallingInfoString<CodeGenOpts<"SplitDwarfOutput">>;
@@ -8564,7 +8570,7 @@ def dependent_lib : Joined<["--"], "dependent-lib=">,
MarshallingInfoStringVector<CodeGenOpts<"DependentLibraries">>;
def split_dwarf_file : Separate<["-"], "split-dwarf-file">,
- HelpText<"Name of the split dwarf debug info file to encode in the object file">,
+ HelpText<"Name of the split DWARF debug info file to encode in the object file">,
MarshallingInfoString<CodeGenOpts<"SplitDwarfFile">>;
} // let Visibility = [CC1Option, FC1Option]
|
jryans
changed the title
jmorse
approved these changes
Dec 1, 2025
Member
jmorse
left a comment
jmorse
left a comment
There was a problem hiding this comment.
/me squints -- so because this is only changing the grouping of options and how they're presented when displayed, this is essentially NFC as far as the input/output of the compilation process goes? Assuming I've got that right, LGTM.
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
This moves a few existing debug info flags that were floating in the general pool of unorganised flags over to the existing groups for debug info flags (so that they are presented together in documentation).
As a tiny further tweak, this also fixes the spelling of "DWARF" in the flag docs for consistency with other flags.