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      Alias  for  --thin. In many ar implementations T has a different
166              meaning, as specified by X/Open System interface.
167
168       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
172   Modifiers (generic)
173       The modifiers below may be applied to any operation.
174
175       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
180       D      Use zero for timestamps and UIDs/GIDs. This is set by default.
181
182       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
187       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
194       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
198       u      Only  update  archive  members  with files that have more recent
199              timestamps.
200
201       U      Use actual timestamps and UIDs/GIDs.
202
203   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
209       -h, --help
210              Print a summary of command-line options and their meanings.
211
212       -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
216       --rsp-quoting=<type>
217
218       This option selects the quoting style ``<type>``  for  response  files,
219       either
220
221       ``posix``  or  ``windows``. The default when on Windows is ``windows``,
222       otherwise the
223
224       default is ``posix``.
225
226       --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
231       --version
232              Display the version of the llvm-ar executable.
233
234       @<FILE>
235              Read  command-line  options  and  commands  from  response  file
236              <FILE>.
237

MRI SCRIPTS

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
245       Note that llvm-ar has  known  limitations  regarding  the  use  of  MRI
246       scripts:
247
248       • Each script can only create one archive.
249
250       • Existing archives can not be modified.
251
252   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
259       CREATE archive
260              Begin  creation  of  a  regular archive with the specified name.
261              Subsequent commands act upon this archive.
262
263       CREATETHIN archive
264              Begin creation of a thin archive with the specified name. Subse‐
265              quent commands act upon this archive.
266
267       ADDLIB archive
268              Append the contents of archive to the current archive.
269
270       ADDMOD <file>
271              Append <file> to the current archive.
272
273       DELETE <file>
274              Delete  the  member  of the current archive whose file name, ex‐
275              cluding directory components, matches <file>.
276
277       SAVE   Write the current archive to the path specified in the  previous
278              CREATE/CREATETHIN command.
279
280       END    Ends the MRI script (optional).
281

EXIT STATUS

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

AUTHOR

287       Maintained by the LLVM Team (https://llvm.org/).
288
290       2003-2023, LLVM Project
291
292
293
294
29514                                2023-07-20                        LLVM-AR(1)
Impressum