llvm/docs/CommandGuide/llvm-ar.rst

   1 llvm-ar - LLVM archiver
   2 =======================
   3
   4 .. program:: llvm-ar
   5
   6 SYNOPSIS
   7 --------
   8
   9 :program:`llvm-ar` [-]{dmpqrstx}[abcDilLNoOPsSTuUvV] [relpos] [count] archive [files...]
  10
  11 DESCRIPTION
  12 -----------
  13
  14 The :program:`llvm-ar` command is similar to the common Unix utility,
  15 :program:`ar`. It archives several files, such as objects and LLVM bitcode
  16 files into a single archive library that can be linked into a program. However,
  17 the archive can contain any kind of file. By default, :program:`llvm-ar`
  18 generates a symbol table that makes linking faster because only the symbol
  19 table needs to be consulted, not each individual file member of the archive.
  20
  21 The :program:`llvm-ar` command can be used to *read* archive files in SVR4, GNU,
  22 BSD , Big Archive, and Darwin format, and *write* in the GNU, BSD, Big Archive, and
  23 Darwin style archive files. If an SVR4 format archive is used with the :option:`r`
  24 (replace), :option:`d` (delete), :option:`m` (move) or :option:`q`
  25 (quick update) operations, the archive will be reconstructed in the format
  26 defined by :option:`--format`.
  27
  28 Here's where :program:`llvm-ar` departs from previous :program:`ar`
  29 implementations:
  30
  31 *The following option is not supported*
  32
  33  [f] - truncate inserted filenames
  34
  35 *The following options are ignored for compatibility*
  36
  37  --plugin=<string> - load a plugin which adds support for other file formats
  38
  39  [l] - ignored in :program:`ar`
  40
  41 *Symbol Table*
  42
  43  Since :program:`llvm-ar` supports bitcode files, the symbol table it creates
  44  includes both native and bitcode symbols.
  45
  46 *Deterministic Archives*
  47
  48  By default, :program:`llvm-ar` always uses zero for timestamps and UIDs/GIDs
  49  to write archives in a deterministic mode. This is equivalent to the
  50  :option:`D` modifier being enabled by default. If you wish to maintain
  51  compatibility with other :program:`ar` implementations, you can pass the
  52  :option:`U` modifier to write actual timestamps and UIDs/GIDs.
  53
  54 *Windows Paths*
  55
  56  When on Windows :program:`llvm-ar` treats the names of archived *files* in the same
  57  case sensitive manner as the operating system. When on a non-Windows machine
  58  :program:`llvm-ar` does not consider character case.
  59
  60 OPTIONS
  61 -------
  62
  63 :program:`llvm-ar` operations are compatible with other :program:`ar`
  64 implementations. However, there are a few modifiers (:option:`L`) that are not
  65 found in other :program:`ar` implementations. The options for
  66 :program:`llvm-ar` specify a single basic Operation to perform on the archive,
  67 a variety of Modifiers for that Operation, the name of the archive file, and an
  68 optional list of file names. If the *files* option is not specified, it
  69 generally means either "none" or "all" members, depending on the operation. The
  70 Options, Operations and Modifiers are explained in the sections below.
  71
  72 The minimal set of options is at least one operator and the name of the
  73 archive.
  74
  75 Operations
  76 ~~~~~~~~~~
  77
  78 .. option:: d [NT]
  79
  80  Delete files from the ``archive``. The :option:`N` and :option:`T` modifiers
  81  apply to this operation. The *files* options specify which members should be
  82  removed from the archive. It is not an error if a specified file does not
  83  appear in the archive. If no *files* are specified, the archive is not
  84  modified.
  85
  86 .. option:: m [abi]
  87
  88  Move files from one location in the ``archive`` to another. The :option:`a`,
  89  :option:`b`, and :option:`i` modifiers apply to this operation. The *files*
  90  will all be moved to the location given by the modifiers. If no modifiers are
  91  used, the files will be moved to the end of the archive. If no *files* are
  92  specified, the archive is not modified.
  93
  94 .. option:: p [v]
  95
  96  Print *files* to the standard output stream. If no *files* are specified, the
  97  entire ``archive`` is printed. With the :option:`v` modifier,
  98  :program:`llvm-ar` also prints out the name of the file being output. Printing
  99  binary files is  ill-advised as they might confuse your terminal settings. The
 100  :option:`p` operation never modifies the archive.
 101
 102 .. option:: q [LT]
 103
 104  Quickly append files to the end of the ``archive`` without removing
 105  duplicates. If no *files* are specified, the archive is not modified. The
 106  behavior when appending one archive to another depends upon whether the
 107  :option:`L` and :option:`T` modifiers are used:
 108
 109  * Appending a regular archive to a regular archive will append the archive
 110    file. If the :option:`L` modifier is specified the members will be appended
 111    instead.
 112
 113  * Appending a regular archive to a thin archive requires the :option:`T`
 114    modifier and will append the archive file. The :option:`L` modifier is not
 115    supported.
 116
 117  * Appending a thin archive to a regular archive will append the archive file.
 118    If the :option:`L` modifier is specified the members will be appended
 119    instead.
 120
 121  * Appending a thin archive to a thin archive will always quick append its
 122    members.
 123
 124 .. option:: r [abTu]
 125
 126  Replace existing *files* or insert them at the end of the ``archive`` if
 127  they do not exist. The :option:`a`, :option:`b`, :option:`T` and :option:`u`
 128  modifiers apply to this operation. If no *files* are specified, the archive
 129  is not modified.
 130
 131 t[v]
 132 .. option:: t [vO]
 133
 134  Print the table of contents. Without any modifiers, this operation just prints
 135  the names of the members to the standard output stream. With the :option:`v`
 136  modifier, :program:`llvm-ar` also prints out the file type (B=bitcode,
 137  S=symbol table, blank=regular file), the permission mode, the owner and group,
 138  are ignored when extracting *files* and set to placeholder values when adding
 139  size, and the date. With the :option:`O` modifier, display member offsets. If
 140  any *files* are specified, the listing is only for those files. If no *files*
 141  are specified, the table of contents for the whole archive is printed.
 142
 143 .. option:: V
 144
 145  A synonym for the :option:`--version` option.
 146
 147 .. option:: x [oP]
 148
 149  Extract ``archive`` members back to files. The :option:`o` modifier applies
 150  to this operation. This operation retrieves the indicated *files* from the
 151  archive and writes them back to the operating system's file system. If no
 152  *files* are specified, the entire archive is extracted.
 153
 154 Modifiers (operation specific)
 155 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 156
 157 The modifiers below are specific to certain operations. See the Operations
 158 section to determine which modifiers are applicable to which operations.
 159
 160 .. option:: a
 161
 162  When inserting or moving member files, this option specifies the destination
 163  of the new files as being after the *relpos* member. If *relpos* is not found,
 164  the files are placed at the end of the ``archive``. *relpos* cannot be
 165  consumed without either :option:`a`, :option:`b` or :option:`i`.
 166
 167 .. option:: b
 168
 169  When inserting or moving member files, this option specifies the destination
 170  of the new files as being before the *relpos* member. If *relpos* is not
 171  found, the files are placed at the end of the ``archive``. *relpos* cannot
 172  be consumed without either :option:`a`, :option:`b` or :option:`i`. This
 173  modifier is identical to the :option:`i` modifier.
 174
 175 .. option:: i
 176
 177  A synonym for the :option:`b` option.
 178
 179 .. option:: L
 180
 181  When quick appending an ``archive``, instead quick append its members. This
 182  is a feature for :program:`llvm-ar` that is not found in gnu-ar.
 183
 184 .. option:: N
 185
 186  When extracting or deleting a member that shares its name with another member,
 187  the *count* parameter allows you to supply a positive whole number that
 188  selects the instance of the given name, with "1" indicating the first
 189  instance. If :option:`N` is not specified the first member of that name will
 190  be selected. If *count* is not supplied, the operation fails.*count* cannot be
 191
 192 .. option:: o
 193
 194  When extracting files, use the modification times of any *files* as they
 195  appear in the ``archive``. By default *files* extracted from the archive
 196  use the time of extraction.
 197
 198 .. option:: O
 199
 200  Display member offsets inside the archive.
 201
 202 .. option:: T
 203
 204  Alias for ``--thin``. In many ar implementations ``T`` has a different
 205  meaning, as specified by X/Open System interface.
 206
 207 .. option:: v
 208
 209  When printing *files* or the ``archive`` table of contents, this modifier
 210  instructs :program:`llvm-ar` to include additional information in the output.
 211
 212 Modifiers (generic)
 213 ~~~~~~~~~~~~~~~~~~~
 214
 215 The modifiers below may be applied to any operation.
 216
 217 .. option:: c
 218
 219  For the :option:`r` (replace)and :option:`q` (quick update) operations,
 220  :program:`llvm-ar` will always create the archive if it doesn't exist.
 221  Normally, :program:`llvm-ar` will print a warning message indicating that the
 222  ``archive`` is being created. Using this modifier turns off
 223  that warning.
 224
 225 .. option:: D
 226
 227  Use zero for timestamps and UIDs/GIDs. This is set by default.
 228
 229 .. option:: P
 230
 231  Use full paths when matching member names rather than just the file name.
 232  This can be useful when manipulating an ``archive`` generated by another
 233  archiver, as some allow paths as member names. This is the default behavior
 234  for thin archives.
 235
 236 .. option:: s
 237
 238  This modifier requests that an archive index (or symbol table) be added to the
 239  ``archive``, as if using ranlib. The symbol table will contain all the
 240  externally visible functions and global variables defined by all the bitcode
 241  files in the archive. By default :program:`llvm-ar` generates symbol tables in
 242  archives. This can also be used as an operation.
 243
 244 .. option:: S
 245
 246  This modifier is the opposite of the :option:`s` modifier. It instructs
 247  :program:`llvm-ar` to not build the symbol table. If both :option:`s` and
 248  :option:`S` are used, the last modifier to occur in the options will prevail.
 249
 250 .. option:: u
 251
 252  Only update ``archive`` members with *files* that have more recent
 253  timestamps.
 254
 255 .. option:: U
 256
 257  Use actual timestamps and UIDs/GIDs.
 258
 259 Other
 260 ~~~~~
 261
 262 .. option:: --format=<type>
 263
 264  This option allows for default, gnu, darwin, bsd or coff ``<type>`` to be selected.
 265  When creating an ``archive`` with the default ``<type>``, :program:``llvm-ar``
 266  will attempt to infer it from the input files and fallback to the default
 267  toolchain target if unable to do so.
 268
 269 .. option:: -h, --help
 270
 271  Print a summary of command-line options and their meanings.
 272
 273 .. option:: -M
 274
 275  This option allows for MRI scripts to be read through the standard input
 276  stream. No other options are compatible with this option.
 277
 278 .. option:: --output=<dir>
 279
 280  Specify a directory where archive members should be extracted to. By default the
 281  current working directory is used.
 282
 283 .. option:: --rsp-quoting=<type>
 284  This option selects the quoting style ``<type>`` for response files, either
 285  ``posix`` or ``windows``. The default when on Windows is ``windows``, otherwise the
 286  default is ``posix``.
 287
 288 .. option:: --thin
 289
 290  When creating or modifying an archive, this option specifies that the
 291  ``archive`` will be thin. By default, archives are not created as thin archives
 292  and when modifying a thin archive, it will be converted to a regular archive.
 293
 294 .. option:: --version
 295
 296  Display the version of the :program:`llvm-ar` executable.
 297
 298 .. option:: -X mode
 299
 300  Specifies the type of object file :program:`llvm-ar` will recognise. The mode must be
 301  one of the following:
 302
 303    32
 304          Process only 32-bit object files.
 305    64
 306          Process only 64-bit object files.
 307    32_64
 308          Process both 32-bit and 64-bit object files.
 309    any
 310          Process all object files.
 311
 312  The default is to process 32-bit object files (ignore 64-bit objects). The mode can also
 313  be set with the OBJECT_MODE environment variable. For example, OBJECT_MODE=64 causes ar to
 314  process any 64-bit objects and ignore 32-bit objects. The -X flag overrides the OBJECT_MODE
 315  variable.
 316
 317 .. option:: @<FILE>
 318
 319   Read command-line options and commands from response file ``<FILE>``.
 320
 321 MRI SCRIPTS
 322 -----------
 323
 324 :program:`llvm-ar` understands a subset of the MRI scripting interface commonly
 325 supported by archivers following in the ar tradition. An MRI script contains a
 326 sequence of commands to be executed by the archiver. The :option:`-M` option
 327 allows for an MRI script to be passed to :program:`llvm-ar` through the
 328 standard input stream.
 329
 330 Note that :program:`llvm-ar` has known limitations regarding the use of MRI
 331 scripts:
 332
 333 * Each script can only create one archive.
 334 * Existing archives can not be modified.
 335
 336 MRI Script Commands
 337 ~~~~~~~~~~~~~~~~~~~
 338
 339 Each command begins with the command's name and must appear on its own line.
 340 Some commands have arguments, which must be separated from the name by
 341 whitespace. An MRI script should begin with either a :option:`CREATE` or
 342 :option:`CREATETHIN` command and will typically end with a :option:`SAVE`
 343 command. Any text after either '*' or ';' is treated as a comment.
 344
 345 .. option:: CREATE archive
 346
 347  Begin creation of a regular archive with the specified name. Subsequent
 348  commands act upon this ``archive``.
 349
 350 .. option:: CREATETHIN archive
 351
 352  Begin creation of a thin archive with the specified name. Subsequent
 353  commands act upon this ``archive``.
 354
 355 .. option:: ADDLIB archive
 356
 357  Append the contents of ``archive`` to the current archive.
 358
 359 .. option:: ADDMOD <file>
 360
 361  Append ``<file>`` to the current archive.
 362
 363 .. option:: DELETE <file>
 364
 365  Delete the member of the current archive whose file name, excluding directory
 366  components, matches ``<file>``.
 367
 368 .. option:: SAVE
 369
 370  Write the current archive to the path specified in the previous
 371  :option:`CREATE`/:option:`CREATETHIN` command.
 372
 373 .. option:: END
 374
 375  Ends the MRI script (optional).
 376
 377 EXIT STATUS
 378 -----------
 379
 380 If :program:`llvm-ar` succeeds, it will exit with 0.  Otherwise, if an error occurs, it
 381 will exit with a non-zero value.