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
56 implementations. The options for llvm-ar specify a single basic Opera‐
57 tion to perform on the archive, a variety of Modifiers for that Opera‐
58 tion, the name of the archive file, and an optional list of file names.
59 If the files option is not specified, it generally means either "none"
60 or "all" members, depending on the operation. The Options, Operations
61 and 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
134 operations.
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 When creating or modifying an archive, this option specifies
166 that the archive will be thin. By default, archives are not cre‐
167 ated as thin archives and when modifying a thin archive, it will
168 be converted to a regular archive.
169 v When printing files or the archive table of contents, this modi‐
171 fier instructs llvm-ar to include additional information in the
172 output.
173 Modifiers (generic)
175 The modifiers below may be applied to any operation.
176 c For the r (replace)and q (quick update) operations, llvm-ar will
178 always create the archive if it doesn't exist. Normally,
179 llvm-ar will print a warning message indicating that the archive
180 is being created. Using this modifier turns off that warning.
181 D Use zero for timestamps and UIDs/GIDs. This is set by default.
183 P Use full paths when matching member names rather than just the
185 file name. This can be useful when manipulating an archive gen‐
186 erated by another archiver, as some allow paths as member names.
187 This is the default behavior for thin archives.
188 s This modifier requests that an archive index (or symbol table)
190 be added to the archive, as if using ranlib. The symbol table
191 will contain all the externally visible functions and global
192 variables defined by all the bitcode files in the archive. By
193 default llvm-ar generates symbol tables in archives. This can
194 also be used as an operation.
195 S This modifier is the opposite of the s modifier. It instructs
197 llvm-ar to not build the symbol table. If both s and S are used,
198 the last modifier to occur in the options will prevail.
199 u Only update archive members with files that have more recent
201 timestamps.
202 U Use actual timestamps and UIDs/GIDs.
204 Other
206 --format=<type>
207 This option allows for default, gnu, darwin or bsd <type> to be
208 selected. When creating an archive, <type> will default to that
209 of the host machine.
210 -h, --help
212 Print a summary of command-line options and their meanings.
213 -M This option allows for MRI scripts to be read through the stan‐
215 dard input stream. No other options are compatible with this
216 option.
217 --version
219 Display the version of the llvm-ar executable.
220 @<FILE>
222 Read command-line options and commands from response file
223 <FILE>.
224
226 llvm-ar understands a subset of the MRI scripting interface commonly
227 supported by archivers following in the ar tradition. An MRI script
228 contains a sequence of commands to be executed by the archiver. The -M
229 option allows for an MRI script to be passed to llvm-ar through the
230 standard input stream.
231 Note that llvm-ar has known limitations regarding the use of MRI
233 scripts:
234 · Each script can only create one archive.
236 · Existing archives can not be modified.
238 MRI Script Commands
240 Each command begins with the command's name and must appear on its own
241 line. Some commands have arguments, which must be separated from the
242 name by whitespace. An MRI script should begin with either a CREATE or
243 CREATETHIN command and will typically end with a SAVE command. Any text
244 after either '*' or ';' is treated as a comment.
245 CREATE archive
247 Begin creation of a regular archive with the specified name.
248 Subsequent commands act upon this archive.
249 CREATETHIN archive
251 Begin creation of a thin archive with the specified name. Subse‐
252 quent commands act upon this archive.
253 ADDLIB archive
255 Append the contents of archive to the current archive.
256 ADDMOD <file>
258 Append <file> to the current archive.
259 DELETE <file>
261 Delete the member of the current archive whose file name,
262 excluding directory components, matches <file>.
263 SAVE Write the current archive to the path specified in the previous
265 CREATE/CREATETHIN command.
266 END Ends the MRI script (optional).
268
270 If llvm-ar succeeds, it will exit with 0. Otherwise, if an error
271 occurs, it will exit with a non-zero value.
272
274 Maintained by the LLVM Team (https://llvm.org/).
275
277 2003-2020, LLVM Project
27811 2020-10-15 LLVM-AR(1)