[llvm] [llvm-objcopy] Improve help messages (PR #82830)
via llvm-commits
llvm-commits at lists.llvm.org
Fri Feb 23 13:01:41 PST 2024
llvmbot wrote:
<!--LLVM PR SUMMARY COMMENT-->
@llvm/pr-subscribers-llvm-binary-utilities
Author: Fangrui Song (MaskRay)
<details>
<summary>Changes</summary>
https://reviews.llvm.org/D63820 added
llvm/docs/CommandGuide/llvm-objcopy.rst with clearer semantics, e.g.
```
Read a list of names from the file <filename> and mark defined symbols with those names as global in the output
instead of the help message
Read a list of symbols from <filename> and marks them global" (omits "defined")
Rename sections called <old> to <new> in the output
instead of the help message
Rename a section from old to new (multiple sections may be named <old>
```
Sync the help messages to incorporate the CommandGuide improvement.
While here, switch to the conventional imperative sentences for a few
options.
---
Full diff: https://github.com/llvm/llvm-project/pull/82830.diff
3 Files Affected:
- (modified) llvm/docs/CommandGuide/llvm-objcopy.rst (+1-1)
- (modified) llvm/tools/llvm-objcopy/CommonOpts.td (+15-12)
- (modified) llvm/tools/llvm-objcopy/ObjcopyOpts.td (+37-38)
``````````diff
diff --git a/llvm/docs/CommandGuide/llvm-objcopy.rst b/llvm/docs/CommandGuide/llvm-objcopy.rst
index 0fb3c4bed643a5..9559fc3d86c4f8 100644
--- a/llvm/docs/CommandGuide/llvm-objcopy.rst
+++ b/llvm/docs/CommandGuide/llvm-objcopy.rst
@@ -450,7 +450,7 @@ them.
Set the type of section ``<section>`` to the integer ``<type>``. Can be
specified multiple times to update multiple sections.
-.. option:: --set-start-addr <addr>
+.. option:: --set-start <addr>
Set the start address of the output to ``<addr>``. Overrides any previously
specified :option:`--change-start` or :option:`--adjust-start` options.
diff --git a/llvm/tools/llvm-objcopy/CommonOpts.td b/llvm/tools/llvm-objcopy/CommonOpts.td
index 4222532a1a38f7..d41ccd953f516d 100644
--- a/llvm/tools/llvm-objcopy/CommonOpts.td
+++ b/llvm/tools/llvm-objcopy/CommonOpts.td
@@ -7,6 +7,9 @@ multiclass Eq<string name, string help> {
HelpText<help>;
}
+def grp_coff : OptionGroup<"kind">, HelpText<"OPTIONS (COFF specific)">;
+def grp_macho : OptionGroup<"kind">, HelpText<"OPTIONS (Mach-O specific)">;
+
def help : Flag<["--"], "help">;
def h : Flag<["-"], "h">, Alias<help>;
@@ -39,13 +42,13 @@ def p : Flag<["-"], "p">,
HelpText<"Alias for --preserve-dates">;
def strip_all : Flag<["--"], "strip-all">,
- HelpText<"Remove non-allocated sections outside segments. "
- ".gnu.warning* and .ARM.attribute sections are not "
- "removed">;
+ HelpText<"For ELF, remove all symbols and non-alloc sections not "
+ "segments, except for .gnu.warning*, .ARM.attribute, and the section name table. "
+ "For COFF and Mach-O, remove all symbols, debug sections, and relocations">;
def strip_all_gnu
: Flag<["--"], "strip-all-gnu">,
- HelpText<"Compatible with GNU's --strip-all">;
+ HelpText<"Remove all symbols, debug sections and relocations. Compatible with GNU's --strip-all">;
def strip_debug : Flag<["--"], "strip-debug">,
HelpText<"Remove all debug sections">;
@@ -64,7 +67,7 @@ def R : JoinedOrSeparate<["-"], "R">,
def strip_sections
: Flag<["--"], "strip-sections">,
- HelpText<"Remove all section headers and all sections not in segments">;
+ HelpText<"Remove all section headers and all section data not within segments">;
defm strip_symbol : Eq<"strip-symbol", "Strip <symbol>">,
MetaVarName<"symbol">;
@@ -75,17 +78,17 @@ def N : JoinedOrSeparate<["-"], "N">,
defm keep_section : Eq<"keep-section", "Keep <section>">,
MetaVarName<"section">;
-defm keep_symbol : Eq<"keep-symbol", "Do not remove symbol <symbol>">,
+defm keep_symbol : Eq<"keep-symbol", "When removing symbols, do not remove <symbol>">,
MetaVarName<"symbol">;
def K : JoinedOrSeparate<["-"], "K">,
Alias<keep_symbol>,
HelpText<"Alias for --keep-symbol">;
def keep_file_symbols : Flag<["--"], "keep-file-symbols">,
- HelpText<"Do not remove file symbols">;
+ HelpText<"Keep symbols of type STT_FILE, even if they would otherwise be stripped">;
def keep_undefined : Flag<["--"], "keep-undefined">,
- HelpText<"Do not remove undefined symbols">;
+ HelpText<"Do not remove undefined symbols">, Group<grp_macho>;
def only_keep_debug
: Flag<["--"], "only-keep-debug">,
@@ -94,16 +97,16 @@ def only_keep_debug
"sections useful for debugging purposes">;
def discard_locals : Flag<["--"], "discard-locals">,
- HelpText<"Remove compiler-generated local symbols, (e.g. "
- "symbols starting with .L)">;
+ HelpText<"Remove local symbols starting with .L">;
def X : Flag<["-"], "X">,
Alias<discard_locals>,
HelpText<"Alias for --discard-locals">;
def discard_all
: Flag<["--"], "discard-all">,
- HelpText<"Remove all local symbols except file and section symbols. Also "
- "remove all debug sections">;
+ HelpText<"Remove most local symbols. Different file formats may limit this to a subset. "
+ "For ELF, file and section symbols are not discarded. "
+ "Additionally, remove all debug sections">;
def x : Flag<["-"], "x">,
Alias<discard_all>,
HelpText<"Alias for --discard-all">;
diff --git a/llvm/tools/llvm-objcopy/ObjcopyOpts.td b/llvm/tools/llvm-objcopy/ObjcopyOpts.td
index bd041fabbdd7ac..0b0cab0abaf2cb 100644
--- a/llvm/tools/llvm-objcopy/ObjcopyOpts.td
+++ b/llvm/tools/llvm-objcopy/ObjcopyOpts.td
@@ -6,28 +6,25 @@ def B : JoinedOrSeparate<["-"], "B">,
Alias<binary_architecture>,
HelpText<"Alias for --binary-architecture">;
-defm target : Eq<"target", "Format of the input and output file">,
+defm target : Eq<"target", "Equivalent to --input-target and --output-target for the specified format">,
Values<"binary">;
def F : JoinedOrSeparate<["-"], "F">,
Alias<target>,
HelpText<"Alias for --target">;
-defm input_target : Eq<"input-target", "Format of the input file">,
- Values<"binary">;
+defm input_target : Eq<"input-target", "Read the input as the specified format">, MetaVarName<"format">;
def I : JoinedOrSeparate<["-"], "I">,
Alias<input_target>,
HelpText<"Alias for --input-target">;
-defm output_target : Eq<"output-target", "Format of the output file">,
- Values<"binary">;
+defm output_target : Eq<"output-target", "Write the output as the specified format">, MetaVarName<"format">;
def O : JoinedOrSeparate<["-"], "O">,
Alias<output_target>,
HelpText<"Alias for --output-target">;
-defm new_symbol_visibility : Eq<"new-symbol-visibility", "Visibility of "
- "symbols generated for binary input or added"
- " with --add-symbol unless otherwise"
- " specified. The default value is 'default'">;
+defm new_symbol_visibility
+ : Eq<"new-symbol-visibility", "Specirty the visibility of symbols automatically "
+ "created when using binary input or --add-symbol. The default is 'default'">;
def compress_debug_sections
: Joined<["--"], "compress-debug-sections=">,
@@ -39,8 +36,8 @@ def : Flag<["--"], "compress-debug-sections">, Alias<compress_debug_sections>,
def decompress_debug_sections : Flag<["--"], "decompress-debug-sections">,
HelpText<"Decompress DWARF debug sections">;
defm split_dwo
- : Eq<"split-dwo", "Equivalent to extract-dwo on the input file to "
- "<dwo-file>, then strip-dwo on the input file">,
+ : Eq<"split-dwo", "Equivalent to --extract-dwo and <dwo-file> as the output file and no other options, "
+ "and then --strip-dwo on the input file">,
MetaVarName<"dwo-file">;
defm add_gnu_debuglink
@@ -49,17 +46,15 @@ defm add_gnu_debuglink
defm rename_section
: Eq<"rename-section",
- "Renames a section from old to new, optionally with specified flags. "
- "Flags supported for GNU compatibility: alloc, load, noload, "
- "readonly, exclude, debug, code, data, rom, share, contents, merge, "
- "strings, large">,
+ "Rename sections called <old> to <new>, and apply any specified <flag> values. "
+ "See --set-section-flags for a list of supported flags">,
MetaVarName<"old=new[,flag1,...]">;
defm redefine_symbol
: Eq<"redefine-sym", "Change the name of a symbol old to new">,
MetaVarName<"old=new">;
defm redefine_symbols
: Eq<"redefine-syms",
- "Reads a list of symbol pairs from <filename> and runs as if "
+ "Read a list of symbol pairs from <filename> and runs as if "
"--redefine-sym=<old>=<new> is set for each one. <filename> "
"contains two symbols per line separated with whitespace and may "
"contain comments beginning with '#'. Leading and trailing "
@@ -74,7 +69,7 @@ def j : JoinedOrSeparate<["-"], "j">,
HelpText<"Alias for --only-section">;
defm add_section
: Eq<"add-section",
- "Make a section named <section> with the contents of <file>">,
+ "Add a section named <section> with the contents of <file>">,
MetaVarName<"section=file">;
defm set_section_alignment
@@ -83,8 +78,8 @@ defm set_section_alignment
defm set_section_flags
: Eq<"set-section-flags",
- "Set section flags for a given section. Flags supported for GNU "
- "compatibility: alloc, load, noload, readonly, exclude, debug, code, "
+ "Set section properties based on the specified <flags>. Supported flag names are: "
+ "alloc, load, noload, readonly, exclude, debug, code, "
"data, rom, share, contents, merge, strings, large">,
MetaVarName<"section=flag1[,flag2,...]">;
@@ -97,24 +92,25 @@ def S : Flag<["-"], "S">,
Alias<strip_all>,
HelpText<"Alias for --strip-all">;
def strip_dwo : Flag<["--"], "strip-dwo">,
- HelpText<"Remove all DWARF .dwo sections from file">;
+ HelpText<"Remove all DWARF .dwo sections">;
def strip_non_alloc
: Flag<["--"], "strip-non-alloc">,
- HelpText<"Remove all non-allocated sections outside segments">;
+ HelpText<"Remove all non-allocated sections that are not within segments">;
defm strip_unneeded_symbol
: Eq<"strip-unneeded-symbol",
- "Remove symbol <symbol> if it is not needed by relocations">,
+ "Remove all symbols named <symbol> that are local or undefined and "
+ "are not required by any relocation">,
MetaVarName<"symbol">;
defm strip_unneeded_symbols
: Eq<"strip-unneeded-symbols",
- "Reads a list of symbols from <filename> and removes them "
- "if they are not needed by relocations">,
+ "Remove all symbols whose names appear in the file <file>, if they "
+ "are local or undefined and are not required by any relocation">,
MetaVarName<"filename">;
defm subsystem
: Eq<"subsystem",
- "Set PE subsystem and version">,
- MetaVarName<"name[:version]">;
+ "Set the PE subsystem, optionally subsystem version">,
+ MetaVarName<"name[:version]">, Group<grp_coff>;
def extract_dwo
: Flag<["--"], "extract-dwo">,
@@ -132,11 +128,13 @@ def localize_hidden
: Flag<["--"], "localize-hidden">,
HelpText<
"Mark all symbols that have hidden or internal visibility as local">;
-defm localize_symbol : Eq<"localize-symbol", "Mark <symbol> as local">,
- MetaVarName<"symbol">;
+defm localize_symbol
+ : Eq<"localize-symbol", "Mark any defined non-common symbol named <symbol> as local">,
+ MetaVarName<"symbol">;
defm localize_symbols
: Eq<"localize-symbols",
- "Reads a list of symbols from <filename> and marks them local">,
+ "Read a list of names from <filename> and mark any defined non-common "
+ "symbols with those names as local">,
MetaVarName<"filename">;
def L : JoinedOrSeparate<["-"], "L">,
@@ -148,13 +146,14 @@ defm globalize_symbol : Eq<"globalize-symbol", "Mark <symbol> as global">,
defm globalize_symbols
: Eq<"globalize-symbols",
- "Reads a list of symbols from <filename> and marks them global">,
+ "Read a list of symbols from <filename> and mark defined symbols"
+ " with those names as global">,
MetaVarName<"filename">;
defm keep_global_symbol
: Eq<"keep-global-symbol",
- "Convert all symbols except <symbol> to local. May be repeated to "
- "convert all except a set of symbols to local">,
+ "Mark all symbols local, except for symbols with the name <symbol>. "
+ "Can be specified multiple times to ignore multiple symbols">,
MetaVarName<"symbol">;
def G : JoinedOrSeparate<["-"], "G">,
Alias<keep_global_symbol>,
@@ -162,34 +161,34 @@ def G : JoinedOrSeparate<["-"], "G">,
defm keep_global_symbols
: Eq<"keep-global-symbols",
- "Reads a list of symbols from <filename> and runs as if "
+ "Read a list of symbols from <filename> and run as if "
"--keep-global-symbol=<symbol> is set for each one. <filename> "
"contains one symbol per line and may contain comments beginning with "
"'#'. Leading and trailing whitespace is stripped from each line. May "
"be repeated to read symbols from many files">,
MetaVarName<"filename">;
-defm weaken_symbol : Eq<"weaken-symbol", "Mark <symbol> as weak">,
+defm weaken_symbol : Eq<"weaken-symbol", "Mark any global symbol named <symbol> as weak">,
MetaVarName<"symbol">;
defm weaken_symbols
: Eq<"weaken-symbols",
- "Reads a list of symbols from <filename> and marks them weak">,
+ "Read a list of symbols from <filename> and mark global symbols with those names as weak">,
MetaVarName<"filename">;
def W : JoinedOrSeparate<["-"], "W">,
Alias<weaken_symbol>,
HelpText<"Alias for --weaken-symbol">;
def weaken : Flag<["--"], "weaken">,
- HelpText<"Mark all global symbols as weak">;
+ HelpText<"Mark all defined global symbols as weak">;
defm strip_symbols
: Eq<"strip-symbols",
- "Reads a list of symbols from <filename> and removes them">,
+ "Remove all symbols whose names appear in the file <filename>">,
MetaVarName<"filename">;
defm keep_symbols
: Eq<"keep-symbols",
- "Reads a list of symbols from <filename> and runs as if "
+ "Read a list of symbols from <filename> and runs as if "
"--keep-symbol=<symbol> is set for each one. <filename> "
"contains one symbol per line and may contain comments beginning with "
"'#'. Leading and trailing whitespace is stripped from each line. May "
``````````
</details>
https://github.com/llvm/llvm-project/pull/82830
More information about the llvm-commits
mailing list