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,
  22 GNU, BSD and Darwin format, and *write* in the GNU, BSD, and Darwin style
  23 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  When creating or modifying an archive, this option specifies that the
 205  ``archive`` will be thin. By default, archives are not created as thin
 206  archives and when modifying a thin archive, it will be converted to a regular
 207  archive.
 208
 209 .. option:: v
 210
 211  When printing *files* or the ``archive`` table of contents, this modifier
 212  instructs :program:`llvm-ar` to include additional information in the output.
 213
 214 Modifiers (generic)
 215 ~~~~~~~~~~~~~~~~~~~
 216
 217 The modifiers below may be applied to any operation.
 218
 219 .. option:: c
 220
 221  For the :option:`r` (replace)and :option:`q` (quick update) operations,
 222  :program:`llvm-ar` will always create the archive if it doesn't exist.
 223  Normally, :program:`llvm-ar` will print a warning message indicating that the
 224  ``archive`` is being created. Using this modifier turns off
 225  that warning.
 226
 227 .. option:: D
 228
 229  Use zero for timestamps and UIDs/GIDs. This is set by default.
 230
 231 .. option:: P
 232
 233  Use full paths when matching member names rather than just the file name.
 234  This can be useful when manipulating an ``archive`` generated by another
 235  archiver, as some allow paths as member names. This is the default behavior
 236  for thin archives.
 237
 238 .. option:: s
 239
 240  This modifier requests that an archive index (or symbol table) be added to the
 241  ``archive``, as if using ranlib. The symbol table will contain all the
 242  externally visible functions and global variables defined by all the bitcode
 243  files in the archive. By default :program:`llvm-ar` generates symbol tables in
 244  archives. This can also be used as an operation.
 245
 246 .. option:: S
 247
 248  This modifier is the opposite of the :option:`s` modifier. It instructs
 249  :program:`llvm-ar` to not build the symbol table. If both :option:`s` and
 250  :option:`S` are used, the last modifier to occur in the options will prevail.
 251
 252 .. option:: u
 253
 254  Only update ``archive`` members with *files* that have more recent
 255  timestamps.
 256
 257 .. option:: U
 258
 259  Use actual timestamps and UIDs/GIDs.
 260
 261 Other
 262 ~~~~~
 263
 264 .. option:: --format=<type>
 265
 266  This option allows for default, gnu, darwin or bsd ``<type>`` to be selected.
 267  When creating an ``archive``, ``<type>`` will default to that of the host
 268  machine.
 269
 270 .. option:: -h, --help
 271
 272  Print a summary of command-line options and their meanings.
 273
 274 .. option:: -M
 275
 276  This option allows for MRI scripts to be read through the standard input
 277  stream. No other options are compatible with this option.
 278
 279 .. option:: --version
 280
 281  Display the version of the :program:`llvm-ar` executable.
 282
 283 .. option:: @<FILE>
 284
 285   Read command-line options and commands from response file ``<FILE>``.
 286
 287 MRI SCRIPTS
 288 -----------
 289
 290 :program:`llvm-ar` understands a subset of the MRI scripting interface commonly
 291 supported by archivers following in the ar tradition. An MRI script contains a
 292 sequence of commands to be executed by the archiver. The :option:`-M` option
 293 allows for an MRI script to be passed to :program:`llvm-ar` through the
 294 standard input stream.
 295
 296 Note that :program:`llvm-ar` has known limitations regarding the use of MRI
 297 scripts:
 298
 299 * Each script can only create one archive.
 300 * Existing archives can not be modified.
 301
 302 MRI Script Commands
 303 ~~~~~~~~~~~~~~~~~~~
 304
 305 Each command begins with the command's name and must appear on its own line.
 306 Some commands have arguments, which must be separated from the name by
 307 whitespace. An MRI script should begin with either a :option:`CREATE` or
 308 :option:`CREATETHIN` command and will typically end with a :option:`SAVE`
 309 command. Any text after either '*' or ';' is treated as a comment.
 310
 311 .. option:: CREATE archive
 312
 313  Begin creation of a regular archive with the specified name. Subsequent
 314  commands act upon this ``archive``.
 315
 316 .. option:: CREATETHIN archive
 317
 318  Begin creation of a thin archive with the specified name. Subsequent
 319  commands act upon this ``archive``.
 320
 321 .. option:: ADDLIB archive
 322
 323  Append the contents of ``archive`` to the current archive.
 324
 325 .. option:: ADDMOD <file>
 326
 327  Append ``<file>`` to the current archive.
 328
 329 .. option:: DELETE <file>
 330
 331  Delete the member of the current archive whose file name, excluding directory
 332  components, matches ``<file>``.
 333
 334 .. option:: SAVE
 335
 336  Write the current archive to the path specified in the previous
 337  :option:`CREATE`/:option:`CREATETHIN` command.
 338
 339 .. option:: END
 340
 341  Ends the MRI script (optional).
 342
 343 EXIT STATUS
 344 -----------
 345
 346 If :program:`llvm-ar` succeeds, it will exit with 0.  Otherwise, if an error occurs, it
 347 will exit with a non-zero value.