1LLVM-AR(1) LLVM LLVM-AR(1)
2
6 llvm-ar - LLVM archiver
7
9 llvm-ar [-]{dmpqrstx}[abcDilLNoOPsSTuUvV] [relpos] [count] archive
10 [files...]
11
13 The llvm-ar command is similar to the common Unix utility, ar. It ar‐
14 chives several files, such as objects and LLVM bitcode files into a
15 single archive library that can be linked into a program. However, the
16 archive can contain any kind of file. By default, llvm-ar generates a
17 symbol table that makes linking faster because only the symbol table
18 needs to be consulted, not each individual file member of the archive.
19 The llvm-ar command can be used to read archive files in SVR4, GNU, BSD
21 , Big Archive, and Darwin format, and write in the GNU, BSD, Big Ar‐
22 chive, and Darwin style archive files. If an SVR4 format archive is
23 used with the r (replace), d (delete), m (move) or q (quick update) op‐
24 erations, the archive will be reconstructed in the format defined by
25 --format.
26 Here's where llvm-ar departs from previous ar implementations:
28 The following option is not supported
30 [f] - truncate inserted filenames
31 The following options are ignored for compatibility
33 --plugin=<string> - load a plugin which adds support for other file
34 formats
35 [l] - ignored in ar
37 Symbol Table
39 Since llvm-ar supports bitcode files, the symbol table it creates
40 includes both native and bitcode symbols.
41 Deterministic Archives
43 By default, llvm-ar always uses zero for timestamps and UIDs/GIDs to
44 write archives in a deterministic mode. This is equivalent to the D
45 modifier being enabled by default. If you wish to maintain compati‐
46 bility with other ar implementations, you can pass the U modifier to
47 write actual timestamps and UIDs/GIDs.
48 Windows Paths
50 When on Windows llvm-ar treats the names of archived files in the
51 same case sensitive manner as the operating system. When on a
52 non-Windows machine llvm-ar does not consider character case.
53
55 llvm-ar operations are compatible with other ar implementations. How‐
56 ever, there are a few modifiers (L) that are not found in other ar im‐
57 plementations. The options for llvm-ar specify a single basic Operation
58 to perform on the archive, a variety of Modifiers for that Operation,
59 the name of the archive file, and an optional list of file names. If
60 the files option is not specified, it generally means either "none" or
61 "all" members, depending on the operation. The Options, Operations and
62 Modifiers are explained in the sections below.
63 The minimal set of options is at least one operator and the name of the
65 archive.
66 Operations
68 d [NT] Delete files from the archive. The N and T modifiers apply to
69 this operation. The files options specify which members should
70 be removed from the archive. It is not an error if a specified
71 file does not appear in the archive. If no files are specified,
72 the archive is not modified.
73 m [abi]
75 Move files from one location in the archive to another. The a,
76 b, and i modifiers apply to this operation. The files will all
77 be moved to the location given by the modifiers. If no modifiers
78 are used, the files will be moved to the end of the archive. If
79 no files are specified, the archive is not modified.
80 p [v] Print files to the standard output stream. If no files are spec‐
82 ified, the entire archive is printed. With the v modifier,
83 llvm-ar also prints out the name of the file being output.
84 Printing binary files is ill-advised as they might confuse your
85 terminal settings. The p operation never modifies the archive.
86 q [LT] Quickly append files to the end of the archive without removing
88 duplicates. If no files are specified, the archive is not modi‐
89 fied. The behavior when appending one archive to another depends
90 upon whether the L and T modifiers are used:
91 • Appending a regular archive to a regular archive will append
93 the archive file. If the L modifier is specified the members
94 will be appended instead.
95 • Appending a regular archive to a thin archive requires the T
97 modifier and will append the archive file. The L modifier is
98 not supported.
99 • Appending a thin archive to a regular archive will append the
101 archive file. If the L modifier is specified the members will
102 be appended instead.
103 • Appending a thin archive to a thin archive will always quick
105 append its members.
106 r [abTu]
108 Replace existing files or insert them at the end of the archive
109 if they do not exist. The a, b, T and u modifiers apply to this
110 operation. If no files are specified, the archive is not modi‐
111 fied.
112 t[v] .. option:: t [vO]
114 Print the table of contents. Without any modifiers, this operation
115 just prints the names of the members to the standard output stream.
116 With the v modifier, llvm-ar also prints out the file type (B=bit‐
117 code, S=symbol table, blank=regular file), the permission mode, the
118 owner and group, are ignored when extracting files and set to place‐
119 holder values when adding size, and the date. With the O modifier,
120 display member offsets. If any files are specified, the listing is
121 only for those files. If no files are specified, the table of con‐
122 tents for the whole archive is printed.
123 V A synonym for the --version option.
125 x [oP] Extract archive members back to files. The o modifier applies to
127 this operation. This operation retrieves the indicated files
128 from the archive and writes them back to the operating system's
129 file system. If no files are specified, the entire archive is
130 extracted.
131 Modifiers (operation specific)
133 The modifiers below are specific to certain operations. See the Opera‐
134 tions section to determine which modifiers are applicable to which op‐
135 erations.
136 a When inserting or moving member files, this option specifies the
138 destination of the new files as being after the relpos member.
139 If relpos is not found, the files are placed at the end of the
140 archive. relpos cannot be consumed without either a, b or i.
141 b When inserting or moving member files, this option specifies the
143 destination of the new files as being before the relpos member.
144 If relpos is not found, the files are placed at the end of the
145 archive. relpos cannot be consumed without either a, b or i.
146 This modifier is identical to the i modifier.
147 i A synonym for the b option.
149 L When quick appending an archive, instead quick append its mem‐
151 bers. This is a feature for llvm-ar that is not found in gnu-ar.
152 N When extracting or deleting a member that shares its name with
154 another member, the count parameter allows you to supply a posi‐
155 tive whole number that selects the instance of the given name,
156 with "1" indicating the first instance. If N is not specified
157 the first member of that name will be selected. If count is not
158 supplied, the operation fails.*count* cannot be
159 o When extracting files, use the modification times of any files
161 as they appear in the archive. By default files extracted from
162 the archive use the time of extraction.
163 O Display member offsets inside the archive.
165 T Alias for --thin. In many ar implementations T has a different
167 meaning, as specified by X/Open System interface.
168 v When printing files or the archive table of contents, this modi‐
170 fier instructs llvm-ar to include additional information in the
171 output.
172 Modifiers (generic)
174 The modifiers below may be applied to any operation.
175 c For the r (replace)and q (quick update) operations, llvm-ar will
177 always create the archive if it doesn't exist. Normally,
178 llvm-ar will print a warning message indicating that the archive
179 is being created. Using this modifier turns off that warning.
180 D Use zero for timestamps and UIDs/GIDs. This is set by default.
182 P Use full paths when matching member names rather than just the
184 file name. This can be useful when manipulating an archive gen‐
185 erated by another archiver, as some allow paths as member names.
186 This is the default behavior for thin archives.
187 s This modifier requests that an archive index (or symbol table)
189 be added to the archive, as if using ranlib. The symbol table
190 will contain all the externally visible functions and global
191 variables defined by all the bitcode files in the archive. By
192 default llvm-ar generates symbol tables in archives. This can
193 also be used as an operation.
194 S This modifier is the opposite of the s modifier. It instructs
196 llvm-ar to not build the symbol table. If both s and S are used,
197 the last modifier to occur in the options will prevail.
198 u Only update archive members with files that have more recent
200 timestamps.
201 U Use actual timestamps and UIDs/GIDs.
203 Other
205 --format=<type>
206 This option allows for default, gnu, darwin or bsd <type> to be
207 selected. When creating an archive, <type> will default to that
208 of the host machine.
209 -h, --help
211 Print a summary of command-line options and their meanings.
212 -M This option allows for MRI scripts to be read through the stan‐
214 dard input stream. No other options are compatible with this op‐
215 tion.
216 --output=<dir>
218 Specify a directory where archive members should be extracted
219 to. By default the current working directory is used.
220 --rsp-quoting=<type>
222 This option selects the quoting style ``<type>`` for response files,
224 either
225 ``posix`` or ``windows``. The default when on Windows is ``windows``,
227 otherwise the
228 default is ``posix``.
230 --thin When creating or modifying an archive, this option specifies
232 that the archive will be thin. By default, archives are not cre‐
233 ated as thin archives and when modifying a thin archive, it will
234 be converted to a regular archive.
235 --version
237 Display the version of the llvm-ar executable.
238 -X mode
240 Specifies the type of object file llvm-ar will recognise. The
241 mode must be one of the following:
242 32 Process only 32-bit object files.
244 64 Process only 64-bit object files.
246 32_64 Process both 32-bit and 64-bit object files.
248 any Process all object files.
250 The default is to process 32-bit object files (ignore 64-bit ob‐
252 jects). The mode can also be set with the OBJECT_MODE environ‐
253 ment variable. For example, OBJECT_MODE=64 causes ar to process
254 any 64-bit objects and ignore 32-bit objects. The -X flag over‐
255 rides the OBJECT_MODE variable.
256 @<FILE>
258 Read command-line options and commands from response file
259 <FILE>.
260
262 llvm-ar understands a subset of the MRI scripting interface commonly
263 supported by archivers following in the ar tradition. An MRI script
264 contains a sequence of commands to be executed by the archiver. The -M
265 option allows for an MRI script to be passed to llvm-ar through the
266 standard input stream.
267 Note that llvm-ar has known limitations regarding the use of MRI
269 scripts:
270 • Each script can only create one archive.
272 • Existing archives can not be modified.
274 MRI Script Commands
276 Each command begins with the command's name and must appear on its own
277 line. Some commands have arguments, which must be separated from the
278 name by whitespace. An MRI script should begin with either a CREATE or
279 CREATETHIN command and will typically end with a SAVE command. Any text
280 after either '*' or ';' is treated as a comment.
281 CREATE archive
283 Begin creation of a regular archive with the specified name.
284 Subsequent commands act upon this archive.
285 CREATETHIN archive
287 Begin creation of a thin archive with the specified name. Subse‐
288 quent commands act upon this archive.
289 ADDLIB archive
291 Append the contents of archive to the current archive.
292 ADDMOD <file>
294 Append <file> to the current archive.
295 DELETE <file>
297 Delete the member of the current archive whose file name, ex‐
298 cluding directory components, matches <file>.
299 SAVE Write the current archive to the path specified in the previous
301 CREATE/CREATETHIN command.
302 END Ends the MRI script (optional).
304
306 If llvm-ar succeeds, it will exit with 0. Otherwise, if an error oc‐
307 curs, it will exit with a non-zero value.
308
310 Maintained by the LLVM Team (https://llvm.org/).
311
313 2003-2023, LLVM Project
31416 2023-07-20 LLVM-AR(1)