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, 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 321MRI SCRIPTS 322----------- 323 324:program:`llvm-ar` understands a subset of the MRI scripting interface commonly 325supported by archivers following in the ar tradition. An MRI script contains a 326sequence of commands to be executed by the archiver. The :option:`-M` option 327allows for an MRI script to be passed to :program:`llvm-ar` through the 328standard input stream. 329 330Note that :program:`llvm-ar` has known limitations regarding the use of MRI 331scripts: 332 333* Each script can only create one archive. 334* Existing archives can not be modified. 335 336MRI Script Commands 337~~~~~~~~~~~~~~~~~~~ 338 339Each command begins with the command's name and must appear on its own line. 340Some commands have arguments, which must be separated from the name by 341whitespace. An MRI script should begin with either a :option:`CREATE` or 342:option:`CREATETHIN` command and will typically end with a :option:`SAVE` 343command. 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 377EXIT STATUS 378----------- 379 380If :program:`llvm-ar` succeeds, it will exit with 0. Otherwise, if an error occurs, it 381will exit with a non-zero value. 382