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 and Darwin format, and write in the GNU, BSD, and Darwin style archive
22 files. If an SVR4 format archive is used with the r (replace), d
23 (delete), m (move) or q (quick update) operations, the archive will be
24 reconstructed in the format defined by --format.
25 Here's where llvm-ar departs from previous ar implementations:
27 The following option is not supported
29 [f] - truncate inserted filenames
30 The following options are ignored for compatibility
32 --plugin=<string> - load a plugin which adds support for other file
33 formats
34 [l] - ignored in ar
36 Symbol Table
38 Since llvm-ar supports bitcode files, the symbol table it creates
39 includes both native and bitcode symbols.
40 Deterministic Archives
42 By default, llvm-ar always uses zero for timestamps and UIDs/GIDs to
43 write archives in a deterministic mode. This is equivalent to the D
44 modifier being enabled by default. If you wish to maintain compati‐
45 bility with other ar implementations, you can pass the U modifier to
46 write actual timestamps and UIDs/GIDs.
47 Windows Paths
49 When on Windows llvm-ar treats the names of archived files in the
50 same case sensitive manner as the operating system. When on a
51 non-Windows machine llvm-ar does not consider character case.
52
54 llvm-ar operations are compatible with other ar implementations. How‐
55 ever, there are a few modifiers (L) that are not found in other ar im‐
56 plementations. The options for llvm-ar specify a single basic Operation
57 to perform on the archive, a variety of Modifiers for that Operation,
58 the name of the archive file, and an optional list of file names. If
59 the files option is not specified, it generally means either "none" or
60 "all" members, depending on the operation. The Options, Operations and
61 Modifiers are explained in the sections below.
62 The minimal set of options is at least one operator and the name of the
64 archive.
65 Operations
67 d [NT] Delete files from the archive. The N and T modifiers apply to
68 this operation. The files options specify which members should
69 be removed from the archive. It is not an error if a specified
70 file does not appear in the archive. If no files are specified,
71 the archive is not modified.
72 m [abi]
74 Move files from one location in the archive to another. The a,
75 b, and i modifiers apply to this operation. The files will all
76 be moved to the location given by the modifiers. If no modifiers
77 are used, the files will be moved to the end of the archive. If
78 no files are specified, the archive is not modified.
79 p [v] Print files to the standard output stream. If no files are spec‐
81 ified, the entire archive is printed. With the v modifier,
82 llvm-ar also prints out the name of the file being output.
83 Printing binary files is ill-advised as they might confuse your
84 terminal settings. The p operation never modifies the archive.
85 q [LT] Quickly append files to the end of the archive without removing
87 duplicates. If no files are specified, the archive is not modi‐
88 fied. The behavior when appending one archive to another depends
89 upon whether the L and T modifiers are used:
90 • Appending a regular archive to a regular archive will append
92 the archive file. If the L modifier is specified the members
93 will be appended instead.
94 • Appending a regular archive to a thin archive requires the T
96 modifier and will append the archive file. The L modifier is
97 not supported.
98 • Appending a thin archive to a regular archive will append the
100 archive file. If the L modifier is specified the members will
101 be appended instead.
102 • Appending a thin archive to a thin archive will always quick
104 append its members.
105 r [abTu]
107 Replace existing files or insert them at the end of the archive
108 if they do not exist. The a, b, T and u modifiers apply to this
109 operation. If no files are specified, the archive is not modi‐
110 fied.
111 t[v] .. option:: t [vO]
113 Print the table of contents. Without any modifiers, this operation
114 just prints the names of the members to the standard output stream.
115 With the v modifier, llvm-ar also prints out the file type (B=bit‐
116 code, S=symbol table, blank=regular file), the permission mode, the
117 owner and group, are ignored when extracting files and set to place‐
118 holder values when adding size, and the date. With the O modifier,
119 display member offsets. If any files are specified, the listing is
120 only for those files. If no files are specified, the table of con‐
121 tents for the whole archive is printed.
122 V A synonym for the --version option.
124 x [oP] Extract archive members back to files. The o modifier applies to
126 this operation. This operation retrieves the indicated files
127 from the archive and writes them back to the operating system's
128 file system. If no files are specified, the entire archive is
129 extracted.
130 Modifiers (operation specific)
132 The modifiers below are specific to certain operations. See the Opera‐
133 tions section to determine which modifiers are applicable to which op‐
134 erations.
135 a When inserting or moving member files, this option specifies the
137 destination of the new files as being after the relpos member.
138 If relpos is not found, the files are placed at the end of the
139 archive. relpos cannot be consumed without either a, b or i.
140 b When inserting or moving member files, this option specifies the
142 destination of the new files as being before the relpos member.
143 If relpos is not found, the files are placed at the end of the
144 archive. relpos cannot be consumed without either a, b or i.
145 This modifier is identical to the i modifier.
146 i A synonym for the b option.
148 L When quick appending an archive, instead quick append its mem‐
150 bers. This is a feature for llvm-ar that is not found in gnu-ar.
151 N When extracting or deleting a member that shares its name with
153 another member, the count parameter allows you to supply a posi‐
154 tive whole number that selects the instance of the given name,
155 with "1" indicating the first instance. If N is not specified
156 the first member of that name will be selected. If count is not
157 supplied, the operation fails.*count* cannot be
158 o When extracting files, use the modification times of any files
160 as they appear in the archive. By default files extracted from
161 the archive use the time of extraction.
162 O Display member offsets inside the archive.
164 T Alias for --thin. In many ar implementations T has a different
166 meaning, as specified by X/Open System interface.
167 v When printing files or the archive table of contents, this modi‐
169 fier instructs llvm-ar to include additional information in the
170 output.
171 Modifiers (generic)
173 The modifiers below may be applied to any operation.
174 c For the r (replace)and q (quick update) operations, llvm-ar will
176 always create the archive if it doesn't exist. Normally,
177 llvm-ar will print a warning message indicating that the archive
178 is being created. Using this modifier turns off that warning.
179 D Use zero for timestamps and UIDs/GIDs. This is set by default.
181 P Use full paths when matching member names rather than just the
183 file name. This can be useful when manipulating an archive gen‐
184 erated by another archiver, as some allow paths as member names.
185 This is the default behavior for thin archives.
186 s This modifier requests that an archive index (or symbol table)
188 be added to the archive, as if using ranlib. The symbol table
189 will contain all the externally visible functions and global
190 variables defined by all the bitcode files in the archive. By
191 default llvm-ar generates symbol tables in archives. This can
192 also be used as an operation.
193 S This modifier is the opposite of the s modifier. It instructs
195 llvm-ar to not build the symbol table. If both s and S are used,
196 the last modifier to occur in the options will prevail.
197 u Only update archive members with files that have more recent
199 timestamps.
200 U Use actual timestamps and UIDs/GIDs.
202 Other
204 --format=<type>
205 This option allows for default, gnu, darwin or bsd <type> to be
206 selected. When creating an archive, <type> will default to that
207 of the host machine.
208 -h, --help
210 Print a summary of command-line options and their meanings.
211 -M This option allows for MRI scripts to be read through the stan‐
213 dard input stream. No other options are compatible with this op‐
214 tion.
215 --rsp-quoting=<type>
217 This option selects the quoting style ``<type>`` for response files,
219 either
220 ``posix`` or ``windows``. The default when on Windows is ``windows``,
222 otherwise the
223 default is ``posix``.
225 --thin When creating or modifying an archive, this option specifies
227 that the archive will be thin. By default, archives are not cre‐
228 ated as thin archives and when modifying a thin archive, it will
229 be converted to a regular archive.
230 --version
232 Display the version of the llvm-ar executable.
233 @<FILE>
235 Read command-line options and commands from response file
236 <FILE>.
237
239 llvm-ar understands a subset of the MRI scripting interface commonly
240 supported by archivers following in the ar tradition. An MRI script
241 contains a sequence of commands to be executed by the archiver. The -M
242 option allows for an MRI script to be passed to llvm-ar through the
243 standard input stream.
244 Note that llvm-ar has known limitations regarding the use of MRI
246 scripts:
247 • Each script can only create one archive.
249 • Existing archives can not be modified.
251 MRI Script Commands
253 Each command begins with the command's name and must appear on its own
254 line. Some commands have arguments, which must be separated from the
255 name by whitespace. An MRI script should begin with either a CREATE or
256 CREATETHIN command and will typically end with a SAVE command. Any text
257 after either '*' or ';' is treated as a comment.
258 CREATE archive
260 Begin creation of a regular archive with the specified name.
261 Subsequent commands act upon this archive.
262 CREATETHIN archive
264 Begin creation of a thin archive with the specified name. Subse‐
265 quent commands act upon this archive.
266 ADDLIB archive
268 Append the contents of archive to the current archive.
269 ADDMOD <file>
271 Append <file> to the current archive.
272 DELETE <file>
274 Delete the member of the current archive whose file name, ex‐
275 cluding directory components, matches <file>.
276 SAVE Write the current archive to the path specified in the previous
278 CREATE/CREATETHIN command.
279 END Ends the MRI script (optional).
281
283 If llvm-ar succeeds, it will exit with 0. Otherwise, if an error oc‐
284 curs, it will exit with a non-zero value.
285
287 Maintained by the LLVM Team (https://llvm.org/).
288
290 2003-2023, LLVM Project
29114 2023-07-20 LLVM-AR(1)