1llvm-ar - LLVM archiver 2======================= 3 4.. program:: llvm-ar 5 6SYNOPSIS 7-------- 8 9:program:`llvm-ar` [-]{dmpqrstx}[abcDilLNoOPsSTuUvV] [relpos] [count] archive [files...] 10 11DESCRIPTION 12----------- 13 14The :program:`llvm-ar` command is similar to the common Unix utility, 15:program:`ar`. It archives several files, such as objects and LLVM bitcode 16files into a single archive library that can be linked into a program. However, 17the archive can contain any kind of file. By default, :program:`llvm-ar` 18generates a symbol table that makes linking faster because only the symbol 19table needs to be consulted, not each individual file member of the archive. 20 21The :program:`llvm-ar` command can be used to *read* archive files in SVR4, GNU, 22BSD , Big Archive, and Darwin format, and *write* in the GNU, BSD, Big Archive, and 23Darwin 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 26defined by :option:`--format`. 27 28Here's where :program:`llvm-ar` departs from previous :program:`ar` 29implementations: 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 60OPTIONS 61------- 62 63:program:`llvm-ar` operations are compatible with other :program:`ar` 64implementations. However, there are a few modifiers (:option:`L`) that are not 65found in other :program:`ar` implementations. The options for 66:program:`llvm-ar` specify a single basic Operation to perform on the archive, 67a variety of Modifiers for that Operation, the name of the archive file, and an 68optional list of file names. If the *files* option is not specified, it 69generally means either "none" or "all" members, depending on the operation. The 70Options, Operations and Modifiers are explained in the sections below. 71 72The minimal set of options is at least one operator and the name of the 73archive. 74 75Operations 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 131t[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 154Modifiers (operation specific) 155~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 156 157The modifiers below are specific to certain operations. See the Operations 158section 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 212Modifiers (generic) 213~~~~~~~~~~~~~~~~~~~ 214 215The 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 259Other 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 320MRI SCRIPTS 321----------- 322 323:program:`llvm-ar` understands a subset of the MRI scripting interface commonly 324supported by archivers following in the ar tradition. An MRI script contains a 325sequence of commands to be executed by the archiver. The :option:`-M` option 326allows for an MRI script to be passed to :program:`llvm-ar` through the 327standard input stream. 328 329Note that :program:`llvm-ar` has known limitations regarding the use of MRI 330scripts: 331 332* Each script can only create one archive. 333* Existing archives can not be modified. 334 335MRI Script Commands 336~~~~~~~~~~~~~~~~~~~ 337 338Each command begins with the command's name and must appear on its own line. 339Some commands have arguments, which must be separated from the name by 340whitespace. An MRI script should begin with either a :option:`CREATE` or 341:option:`CREATETHIN` command and will typically end with a :option:`SAVE` 342command. 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 376EXIT STATUS 377----------- 378 379If :program:`llvm-ar` succeeds, it will exit with 0. Otherwise, if an error occurs, it 380will exit with a non-zero value. 381