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, 22GNU, BSD and Darwin format, and *write* in the GNU, BSD, and Darwin style 23archive 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 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 214Modifiers (generic) 215~~~~~~~~~~~~~~~~~~~ 216 217The 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 261Other 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:: --rsp-quoting=<type> 280 This option selects the quoting style ``<type>`` for response files, either 281 ``posix`` or ``windows``. The default when on Windows is ``windows``, otherwise the 282 default is ``posix``. 283 284.. option:: --version 285 286 Display the version of the :program:`llvm-ar` executable. 287 288.. option:: @<FILE> 289 290 Read command-line options and commands from response file ``<FILE>``. 291 292MRI SCRIPTS 293----------- 294 295:program:`llvm-ar` understands a subset of the MRI scripting interface commonly 296supported by archivers following in the ar tradition. An MRI script contains a 297sequence of commands to be executed by the archiver. The :option:`-M` option 298allows for an MRI script to be passed to :program:`llvm-ar` through the 299standard input stream. 300 301Note that :program:`llvm-ar` has known limitations regarding the use of MRI 302scripts: 303 304* Each script can only create one archive. 305* Existing archives can not be modified. 306 307MRI Script Commands 308~~~~~~~~~~~~~~~~~~~ 309 310Each command begins with the command's name and must appear on its own line. 311Some commands have arguments, which must be separated from the name by 312whitespace. An MRI script should begin with either a :option:`CREATE` or 313:option:`CREATETHIN` command and will typically end with a :option:`SAVE` 314command. Any text after either '*' or ';' is treated as a comment. 315 316.. option:: CREATE archive 317 318 Begin creation of a regular archive with the specified name. Subsequent 319 commands act upon this ``archive``. 320 321.. option:: CREATETHIN archive 322 323 Begin creation of a thin archive with the specified name. Subsequent 324 commands act upon this ``archive``. 325 326.. option:: ADDLIB archive 327 328 Append the contents of ``archive`` to the current archive. 329 330.. option:: ADDMOD <file> 331 332 Append ``<file>`` to the current archive. 333 334.. option:: DELETE <file> 335 336 Delete the member of the current archive whose file name, excluding directory 337 components, matches ``<file>``. 338 339.. option:: SAVE 340 341 Write the current archive to the path specified in the previous 342 :option:`CREATE`/:option:`CREATETHIN` command. 343 344.. option:: END 345 346 Ends the MRI script (optional). 347 348EXIT STATUS 349----------- 350 351If :program:`llvm-ar` succeeds, it will exit with 0. Otherwise, if an error occurs, it 352will exit with a non-zero value. 353