1LLVM-AR(1)                           LLVM                           LLVM-AR(1)
2
3
4

NAME

6       llvm-ar - LLVM archiver
7

SYNOPSIS

9       llvm-ar   [-]{dmpqrstx}[abcDilLNoOPsSTuUvV]  [relpos]  [count]  archive
10       [files...]
11

DESCRIPTION

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
20       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
26       Here's where llvm-ar departs from previous ar implementations:
27
28       The following option is not supported
29          [f] - truncate inserted filenames
30
31       The following options are ignored for compatibility
32          --plugin=<string>  - load a plugin which adds support for other file
33          formats
34
35          [l] - ignored in ar
36
37       Symbol Table
38          Since llvm-ar supports bitcode files, the symbol  table  it  creates
39          includes both native and bitcode symbols.
40
41       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
48       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

OPTIONS

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
63       The minimal set of options is at least one operator and the name of the
64       archive.
65
66   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
73       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
80       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
86       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
91              • 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
95              • 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
99              • 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
103              • Appending a thin archive to a thin archive will  always  quick
104                append its members.
105
106       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
112       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
123       V      A synonym for the --version option.
124
125       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
131   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
136       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
141       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
147       i      A synonym for the b option.
148
149       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
152       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
159       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
163       O      Display member offsets inside the archive.
164
165       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
170       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
174   Modifiers (generic)
175       The modifiers below may be applied to any operation.
176
177       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
182       D      Use zero for timestamps and UIDs/GIDs. This is set by default.
183
184       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
189       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
196       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
200       u      Only  update  archive  members  with files that have more recent
201              timestamps.
202
203       U      Use actual timestamps and UIDs/GIDs.
204
205   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
211       -h, --help
212              Print a summary of command-line options and their meanings.
213
214       -M     This option allows for MRI scripts to be read through the  stan‐
215              dard input stream. No other options are compatible with this op‐
216              tion.
217
218       --version
219              Display the version of the llvm-ar executable.
220
221       @<FILE>
222              Read  command-line  options  and  commands  from  response  file
223              <FILE>.
224

MRI SCRIPTS

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
232       Note  that  llvm-ar  has  known  limitations  regarding  the use of MRI
233       scripts:
234
235       • Each script can only create one archive.
236
237       • Existing archives can not be modified.
238
239   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
246       CREATE archive
247              Begin creation of a regular archive  with  the  specified  name.
248              Subsequent commands act upon this archive.
249
250       CREATETHIN archive
251              Begin creation of a thin archive with the specified name. Subse‐
252              quent commands act upon this archive.
253
254       ADDLIB archive
255              Append the contents of archive to the current archive.
256
257       ADDMOD <file>
258              Append <file> to the current archive.
259
260       DELETE <file>
261              Delete the member of the current archive whose  file  name,  ex‐
262              cluding directory components, matches <file>.
263
264       SAVE   Write  the current archive to the path specified in the previous
265              CREATE/CREATETHIN command.
266
267       END    Ends the MRI script (optional).
268

EXIT STATUS

270       If llvm-ar succeeds, it will exit with 0.  Otherwise, if an  error  oc‐
271       curs, it will exit with a non-zero value.
272

AUTHOR

274       Maintained by the LLVM Team (https://llvm.org/).
275
277       2003-2023, LLVM Project
278
279
280
281
28211                                2023-07-20                        LLVM-AR(1)
Impressum