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

OPTIONS

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
64       The minimal set of options is at least one operator and the name of the
65       archive.
66
67   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
74       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
81       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
87       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
92              • 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
96              • 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
100              • 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
104              • Appending  a  thin archive to a thin archive will always quick
105                append its members.
106
107       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
113       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
124       V      A synonym for the --version option.
125
126       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
132   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
137       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
142       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
148       i      A synonym for the b option.
149
150       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
153       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
160       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
164       O      Display member offsets inside the archive.
165
166       T      Alias for --thin. In many ar implementations T has  a  different
167              meaning, as specified by X/Open System interface.
168
169       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
173   Modifiers (generic)
174       The modifiers below may be applied to any operation.
175
176       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
181       D      Use zero for timestamps and UIDs/GIDs. This is set by default.
182
183       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
188       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
195       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
199       u      Only update archive members with files  that  have  more  recent
200              timestamps.
201
202       U      Use actual timestamps and UIDs/GIDs.
203
204   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
210       -h, --help
211              Print a summary of command-line options and their meanings.
212
213       -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
217       --output=<dir>
218              Specify  a  directory  where archive members should be extracted
219              to. By default the current working directory is used.
220
221       --rsp-quoting=<type>
222
223       This option selects the quoting style ``<type>``  for  response  files,
224       either
225
226       ``posix``  or  ``windows``. The default when on Windows is ``windows``,
227       otherwise the
228
229       default is ``posix``.
230
231       --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
236       --version
237              Display the version of the llvm-ar executable.
238
239       -X mode
240              Specifies  the  type  of object file llvm-ar will recognise. The
241              mode must be one of the following:
242
243                 32     Process only 32-bit object files.
244
245                 64     Process only 64-bit object files.
246
247                 32_64  Process both 32-bit and 64-bit object files.
248
249                 any    Process all object files.
250
251              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
257       @<FILE>
258              Read  command-line  options  and  commands  from  response  file
259              <FILE>.
260

MRI SCRIPTS

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
268       Note  that  llvm-ar  has  known  limitations  regarding  the use of MRI
269       scripts:
270
271       • Each script can only create one archive.
272
273       • Existing archives can not be modified.
274
275   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
282       CREATE archive
283              Begin creation of a regular archive  with  the  specified  name.
284              Subsequent commands act upon this archive.
285
286       CREATETHIN archive
287              Begin creation of a thin archive with the specified name. Subse‐
288              quent commands act upon this archive.
289
290       ADDLIB archive
291              Append the contents of archive to the current archive.
292
293       ADDMOD <file>
294              Append <file> to the current archive.
295
296       DELETE <file>
297              Delete the member of the current archive whose  file  name,  ex‐
298              cluding directory components, matches <file>.
299
300       SAVE   Write  the current archive to the path specified in the previous
301              CREATE/CREATETHIN command.
302
303       END    Ends the MRI script (optional).
304

EXIT STATUS

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

AUTHOR

310       Maintained by the LLVM Team (https://llvm.org/).
311
313       2003-2023, LLVM Project
314
315
316
317
31816                                2023-08-24                        LLVM-AR(1)
Impressum