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 or bsd ``<type>`` to be selected.
 265  When creating an ``archive``, ``<type>`` will default to that of the host
 266  machine.
 267
 268 .. option:: -h, --help
 269
 270  Print a summary of command-line options and their meanings.
 271
 272 .. option:: -M
 273
 274  This option allows for MRI scripts to be read through the standard input
 275  stream. No other options are compatible with this option.
 276
 277 .. option:: --output=<dir>
 278
 279  Specify a directory where archive members should be extracted to. By default the
 280  current working directory is used.
 281
 282 .. option:: --rsp-quoting=<type>
 283  This option selects the quoting style ``<type>`` for response files, either
 284  ``posix`` or ``windows``. The default when on Windows is ``windows``, otherwise the
 285  default is ``posix``.
 286
 287 .. option:: --thin
 288
 289  When creating or modifying an archive, this option specifies that the
 290  ``archive`` will be thin. By default, archives are not created as thin archives
 291  and when modifying a thin archive, it will be converted to a regular archive.
 292
 293 .. option:: --version
 294
 295  Display the version of the :program:`llvm-ar` executable.
 296
 297 .. option:: -X mode
 298
 299  Specifies the type of object file :program:`llvm-ar` will recognise. The mode must be
 300  one of the following:
 301
 302    32
 303          Process only 32-bit object files.
 304    64
 305          Process only 64-bit object files.
 306    32_64
 307          Process both 32-bit and 64-bit object files.
 308    any
 309          Process all object files.
 310
 311  The default is to process 32-bit object files (ignore 64-bit objects). The mode can also
 312  be set with the OBJECT_MODE environment variable. For example, OBJECT_MODE=64 causes ar to
 313  process any 64-bit objects and ignore 32-bit objects. The -X flag overrides the OBJECT_MODE
 314  variable.
 315
 316 .. option:: @<FILE>
 317
 318   Read command-line options and commands from response file ``<FILE>``.
 319
 320 MRI SCRIPTS
 321 -----------
 322
 323 :program:`llvm-ar` understands a subset of the MRI scripting interface commonly
 324 supported by archivers following in the ar tradition. An MRI script contains a
 325 sequence of commands to be executed by the archiver. The :option:`-M` option
 326 allows for an MRI script to be passed to :program:`llvm-ar` through the
 327 standard input stream.
 328
 329 Note that :program:`llvm-ar` has known limitations regarding the use of MRI
 330 scripts:
 331
 332 * Each script can only create one archive.
 333 * Existing archives can not be modified.
 334
 335 MRI Script Commands
 336 ~~~~~~~~~~~~~~~~~~~
 337
 338 Each command begins with the command's name and must appear on its own line.
 339 Some commands have arguments, which must be separated from the name by
 340 whitespace. An MRI script should begin with either a :option:`CREATE` or
 341 :option:`CREATETHIN` command and will typically end with a :option:`SAVE`
 342 command. Any text after either '*' or ';' is treated as a comment.
 343
 344 .. option:: CREATE archive
 345
 346  Begin creation of a regular archive with the specified name. Subsequent
 347  commands act upon this ``archive``.
 348
 349 .. option:: CREATETHIN archive
 350
 351  Begin creation of a thin archive with the specified name. Subsequent
 352  commands act upon this ``archive``.
 353
 354 .. option:: ADDLIB archive
 355
 356  Append the contents of ``archive`` to the current archive.
 357
 358 .. option:: ADDMOD <file>
 359
 360  Append ``<file>`` to the current archive.
 361
 362 .. option:: DELETE <file>
 363
 364  Delete the member of the current archive whose file name, excluding directory
 365  components, matches ``<file>``.
 366
 367 .. option:: SAVE
 368
 369  Write the current archive to the path specified in the previous
 370  :option:`CREATE`/:option:`CREATETHIN` command.
 371
 372 .. option:: END
 373
 374  Ends the MRI script (optional).
 375
 376 EXIT STATUS
 377 -----------
 378
 379 If :program:`llvm-ar` succeeds, it will exit with 0.  Otherwise, if an error occurs, it
 380 will exit with a non-zero value.