llvm.org GIT mirror llvm / 966519d
[docs][llvm-objcopy] Write documentation for llvm-objcopy This patch addresses https://bugs.llvm.org/show_bug.cgi?id=42183 by replacing the stub markdown doc for llvm-objcopy with a full one describing the current options available in llvm-objcopy. Reviewed by: jakehehrlich, MaskRay Differential Revision: https://reviews.llvm.org/D63820 git-svn-id: https://llvm.org/svn/llvm-project/llvm/trunk@365042 91177308-0d34-0410-b5e6-96231b3b80d8 James Henderson a month ago
2 changed file(s) with 482 addition(s) and 16 deletion(s). Raw diff Collapse all Expand all
+0
-16
docs/CommandGuide/llvm-objcopy.md less more
None # llvm-objcopy - object copying tool
1
2 ## SYNOPSIS
3
4 **llvm-objcopy** [*options*]
5
6 ## DESCRIPTION
7
8 **llvm-objcopy** is a tool to copy and manipulate objects.
9
10 The tool is still in active development, but in most scenarios it works as a
11 drop-in replacement for GNU's **objcopy**.
12
13 ## SEE ALSO
14
15 [llvm-strip](llvm-strip.html)
0 llvm-objcopy - object copying and editing tool
1 ==============================================
2
3 .. program:: llvm-objcopy
4
5 SYNOPSIS
6 --------
7
8 :program:`llvm-objcopy` [*options*] *input* [*output*]
9
10 DESCRIPTION
11 -----------
12
13 :program:`llvm-objcopy` is a tool to copy and manipulate objects. In basic
14 usage, it makes a semantic copy of the input to the output. If any options are
15 specified, the output may be modified along the way, e.g. by removing sections.
16
17 If no output file is specified, the input file is modified in-place. If "-" is
18 specified for the input file, the input is read from the program's standard
19 input stream. If "-" is specified for the output file, the output is written to
20 the standard output stream of the program.
21
22 If the input is an archive, any requested operations will be applied to each
23 archive member individually.
24
25 The tool is still in active development, but in most scenarios it works as a
26 drop-in replacement for GNU's :program:`objcopy`.
27
28 GENERIC AND CROSS-PLATFORM OPTIONS
29 ----------------------------------
30
31 The following options are either agnostic of the file format, or apply to
32 multiple file formats.
33
34 .. option:: --add-gnu-debuglink
35
36 Add a .gnu_debuglink section for ```` to the output.
37
38 .. option:: --disable-deterministic-archives, -U
39
40 Use real values for UIDs, GIDs and timestamps when updating archive member
41 headers.
42
43 .. option:: --discard-all, -x
44
45 Remove most local symbols from the output. Different file formats may limit
46 this to a subset of the local symbols. For example, file and section symbols in
47 ELF objects will not be discarded.
48
49 .. option:: --enable-deterministic-archives, -D
50
51 Enable deterministic mode when copying archives, i.e. use 0 for archive member
52 header UIDs, GIDs and timestamp fields. On by default.
53
54 .. option:: --help, -h
55
56 Print a summary of command line options.
57
58 .. option:: --only-section
, -j
59
60 Remove all sections from the output, except for sections named ``
``.
61 Can be specified multiple times to keep multiple sections.
62
63 .. option:: --regex
64
65 If specified, symbol and section names specified by other switches are treated
66 as extended POSIX regular expression patterns.
67
68 .. option:: --remove-section
, -R
69
70 Remove the specified section from the output. Can be specified multiple times
71 to remove multiple sections simultaneously.
72
73 .. option:: --strip-all-gnu
74
75 Remove all symbols, debug sections and relocations from the output. This option
76 is equivalent to GNU :program:`objcopy`'s ``--strip-all`` switch.
77
78 .. option:: --strip-all, -S
79
80 For ELF objects, remove from the output all symbols and non-alloc sections not
81 within segments, except for .gnu.warning sections and the section name table.
82
83 For COFF objects, remove all symbols, debug sections, and relocations from the
84 output.
85
86 .. option:: --strip-debug, -g
87
88 Remove all debug sections from the output.
89
90 .. option:: --strip-symbol , -N
91
92 Remove all symbols named ```` from the output. Can be specified
93 multiple times to remove multiple symbols.
94
95 .. option:: --strip-symbols
96
97 Remove all symbols whose names appear in the file ````, from the
98 output. In the file, each line represents a single symbol name, with leading
99 and trailing whitespace ignored, as is anything following a '#'. Can be
100 specified multiple times to read names from multiple files.
101
102 .. option:: --strip-unneeded-symbol
103
104 Remove from the output all symbols named ```` that are local or
105 undefined and are not required by any relocation.
106
107 .. option:: --strip-unneeded-symbols
108
109 Remove all symbols whose names appear in the file ````, from the
110 output, if they are local or undefined and are not required by any relocation.
111 In the file, each line represents a single symbol name, with leading and
112 trailing whitespace ignored, as is anything following a '#'. Can be specified
113 multiple times to read names from multiple files.
114
115 .. option:: --strip-unneeded
116
117 Remove from the output all local or undefined symbols that are not required by
118 relocations.
119
120 .. option:: --version, -V
121
122 Display the version of this program.
123
124 COFF-SPECIFIC OPTIONS
125 ---------------------
126
127 The following options are implemented only for COFF objects. If used with other
128 objects, :program:`llvm-objcopy` will either emit an error or silently ignore
129 them.
130
131 .. option:: --only-keep-debug
132
133 Remove the contents of non-debug sections from the output, but keep the section
134 headers.
135
136 ELF-SPECIFIC OPTIONS
137 --------------------
138
139 The following options are implemented only for ELF objects. If used with other
140 objects, :program:`llvm-objcopy` will either emit an error or silently ignore
141 them.
142
143 .. option:: --add-section
144
145 Add a section named ``
`` with the contents of ```` to the
146 output. The section will be of type `SHT_NOTE`, if the name starts with
147 ".note". Otherwise, it will have type `SHT_PROGBITS`. Can be specified multiple
148 times to add multiple sections.
149
150 .. option:: --add-symbol =[
:][,]
151
152 Add to the output a new symbol called ```` to the symbol table, in the
153 section named ``
``, with value ````. If ``
`` is not
154 specified, the symbol is added as an absolute symbol. The ```` affect
155 the symbol properties. Accepted values are:
156
157 - `global` = the symbol will have global binding.
158 - `local` = the symbol will have local binding.
159 - `weak` = the symbol will have weak binding.
160 - `default` = the symbol will have default visibility.
161 - `hidden` = the symbol will have hidden visibility.
162 - `file` = the symbol will be an `STT_FILE` symbol.
163 - `section` = the symbol will be an `STT_SECTION` symbol.
164 - `object` = the symbol will be an `STT_OBJECT` symbol.
165 - `function` = the symbol will be an `STT_FUNC` symbol.
166 - `indirect-function` = the symbol will be an `STT_GNU_IFUNC` symbol.
167
168 Additionally, the following flags are accepted but ignored: `debug`,
169 `constructor`, `warning`, `indirect`, `synthetic`, `unique-object`, `before`.
170
171 Can be specified multiple times to add multiple symbols.
172
173 .. option:: --allow-broken-links
174
175 Allow llvm-objcopy to remove sections even if it would leave invalid section
176 references. Any invalid sh_link fields will be set to zero.
177
178 .. option:: --binary-architecture , -B
179
180 Specify the architecture to use, when transforming an architecture-less format
181 (e.g. binary) to another format. Valid options are:
182
183 - `aarch64`
184 - `arm`
185 - `i386`
186 - `i386:x86-64`
187 - `mips`
188 - `powerpc:common64`
189 - `riscv:rv32`
190 - `riscv:rv64`
191 - `sparc`
192 - `sparcel`
193 - `x86-64`
194
195 .. option:: --build-id-link-dir
196
197 Set the directory used by :option:`--build-id-link-input` and
198 :option:`--build-id-link-output`.
199
200 .. option:: --build-id-link-input
201
202 Hard-link the input to ``/xx/xxx``, where ```` is the directory
203 specified by :option:`--build-id-link-dir`. The path used is derived from the
204 hex build ID.
205
206 .. option:: --build-id-link-output
207
208 Hard-link the output to ``/xx/xxx``, where ```` is the directory
209 specified by :option:`--build-id-link-dir`. The path used is derived from the
210 hex build ID.
211
212 .. option:: --change-start , --adjust-start
213
214 Add ```` to the program's start address. Can be specified multiple
215 times, in which case the values will be applied cumulatively.
216
217 .. option:: --compress-debug-sections [