llvm-ar - LLVM archiver ======================= .. program:: llvm-ar SYNOPSIS -------- :program:`llvm-ar` [-]{dmpqrstx}[abcDilLNoOPsSTuUvV] [relpos] [count] archive [files...] DESCRIPTION ----------- The :program:`llvm-ar` command is similar to the common Unix utility, :program:`ar`. It archives several files, such as objects and LLVM bitcode files into a single archive library that can be linked into a program. However, the archive can contain any kind of file. By default, :program:`llvm-ar` generates a symbol table that makes linking faster because only the symbol table needs to be consulted, not each individual file member of the archive. The :program:`llvm-ar` command can be used to *read* archive files in SVR4, GNU, BSD and Darwin format, and *write* in the GNU, BSD, and Darwin style archive files. If an SVR4 format archive is used with the :option:`r` (replace), :option:`d` (delete), :option:`m` (move) or :option:`q` (quick update) operations, the archive will be reconstructed in the format defined by :option:`--format`. Here's where :program:`llvm-ar` departs from previous :program:`ar` implementations: *The following option is not supported* [f] - truncate inserted filenames *The following options are ignored for compatibility* --plugin= - load a plugin which adds support for other file formats [l] - ignored in :program:`ar` *Symbol Table* Since :program:`llvm-ar` supports bitcode files, the symbol table it creates includes both native and bitcode symbols. *Deterministic Archives* By default, :program:`llvm-ar` always uses zero for timestamps and UIDs/GIDs to write archives in a deterministic mode. This is equivalent to the :option:`D` modifier being enabled by default. If you wish to maintain compatibility with other :program:`ar` implementations, you can pass the :option:`U` modifier to write actual timestamps and UIDs/GIDs. *Windows Paths* When on Windows :program:`llvm-ar` treats the names of archived *files* in the same case sensitive manner as the operating system. When on a non-Windows machine :program:`llvm-ar` does not consider character case. OPTIONS ------- :program:`llvm-ar` operations are compatible with other :program:`ar` implementations. However, there are a few modifiers (:option:`L`) that are not found in other :program:`ar` implementations. The options for :program:`llvm-ar` specify a single basic Operation to perform on the archive, a variety of Modifiers for that Operation, the name of the archive file, and an optional list of file names. If the *files* option is not specified, it generally means either "none" or "all" members, depending on the operation. The Options, Operations and Modifiers are explained in the sections below. The minimal set of options is at least one operator and the name of the archive. Operations ~~~~~~~~~~ .. option:: d [NT] Delete files from the ``archive``. The :option:`N` and :option:`T` modifiers apply to this operation. The *files* options specify which members should be removed from the archive. It is not an error if a specified file does not appear in the archive. If no *files* are specified, the archive is not modified. .. option:: m [abi] Move files from one location in the ``archive`` to another. The :option:`a`, :option:`b`, and :option:`i` modifiers apply to this operation. The *files* will all be moved to the location given by the modifiers. If no modifiers are used, the files will be moved to the end of the archive. If no *files* are specified, the archive is not modified. .. option:: p [v] Print *files* to the standard output stream. If no *files* are specified, the entire ``archive`` is printed. With the :option:`v` modifier, :program:`llvm-ar` also prints out the name of the file being output. Printing binary files is ill-advised as they might confuse your terminal settings. The :option:`p` operation never modifies the archive. .. option:: q [LT] Quickly append files to the end of the ``archive`` without removing duplicates. If no *files* are specified, the archive is not modified. The behavior when appending one archive to another depends upon whether the :option:`L` and :option:`T` modifiers are used: * Appending a regular archive to a regular archive will append the archive file. If the :option:`L` modifier is specified the members will be appended instead. * Appending a regular archive to a thin archive requires the :option:`T` modifier and will append the archive file. The :option:`L` modifier is not supported. * Appending a thin archive to a regular archive will append the archive file. If the :option:`L` modifier is specified the members will be appended instead. * Appending a thin archive to a thin archive will always quick append its members. .. option:: r [abTu] Replace existing *files* or insert them at the end of the ``archive`` if they do not exist. The :option:`a`, :option:`b`, :option:`T` and :option:`u` modifiers apply to this operation. If no *files* are specified, the archive is not modified. t[v] .. option:: t [vO] Print the table of contents. Without any modifiers, this operation just prints the names of the members to the standard output stream. With the :option:`v` modifier, :program:`llvm-ar` also prints out the file type (B=bitcode, S=symbol table, blank=regular file), the permission mode, the owner and group, are ignored when extracting *files* and set to placeholder values when adding size, and the date. With the :option:`O` modifier, display member offsets. If any *files* are specified, the listing is only for those files. If no *files* are specified, the table of contents for the whole archive is printed. .. option:: V A synonym for the :option:`--version` option. .. option:: x [oP] Extract ``archive`` members back to files. The :option:`o` modifier applies to this operation. This operation retrieves the indicated *files* from the archive and writes them back to the operating system's file system. If no *files* are specified, the entire archive is extracted. Modifiers (operation specific) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The modifiers below are specific to certain operations. See the Operations section to determine which modifiers are applicable to which operations. .. option:: a When inserting or moving member files, this option specifies the destination of the new files as being after the *relpos* member. If *relpos* is not found, the files are placed at the end of the ``archive``. *relpos* cannot be consumed without either :option:`a`, :option:`b` or :option:`i`. .. option:: b When inserting or moving member files, this option specifies the destination of the new files as being before the *relpos* member. If *relpos* is not found, the files are placed at the end of the ``archive``. *relpos* cannot be consumed without either :option:`a`, :option:`b` or :option:`i`. This modifier is identical to the :option:`i` modifier. .. option:: i A synonym for the :option:`b` option. .. option:: L When quick appending an ``archive``, instead quick append its members. This is a feature for :program:`llvm-ar` that is not found in gnu-ar. .. option:: N When extracting or deleting a member that shares its name with another member, the *count* parameter allows you to supply a positive whole number that selects the instance of the given name, with "1" indicating the first instance. If :option:`N` is not specified the first member of that name will be selected. If *count* is not supplied, the operation fails.*count* cannot be .. option:: o When extracting files, use the modification times of any *files* as they appear in the ``archive``. By default *files* extracted from the archive use the time of extraction. .. option:: O Display member offsets inside the archive. .. option:: T Alias for ``--thin``. In many ar implementations ``T`` has a different meaning, as specified by X/Open System interface. .. option:: v When printing *files* or the ``archive`` table of contents, this modifier instructs :program:`llvm-ar` to include additional information in the output. Modifiers (generic) ~~~~~~~~~~~~~~~~~~~ The modifiers below may be applied to any operation. .. option:: c For the :option:`r` (replace)and :option:`q` (quick update) operations, :program:`llvm-ar` will always create the archive if it doesn't exist. Normally, :program:`llvm-ar` will print a warning message indicating that the ``archive`` is being created. Using this modifier turns off that warning. .. option:: D Use zero for timestamps and UIDs/GIDs. This is set by default. .. option:: P Use full paths when matching member names rather than just the file name. This can be useful when manipulating an ``archive`` generated by another archiver, as some allow paths as member names. This is the default behavior for thin archives. .. option:: s This modifier requests that an archive index (or symbol table) be added to the ``archive``, as if using ranlib. The symbol table will contain all the externally visible functions and global variables defined by all the bitcode files in the archive. By default :program:`llvm-ar` generates symbol tables in archives. This can also be used as an operation. .. option:: S This modifier is the opposite of the :option:`s` modifier. It instructs :program:`llvm-ar` to not build the symbol table. If both :option:`s` and :option:`S` are used, the last modifier to occur in the options will prevail. .. option:: u Only update ``archive`` members with *files* that have more recent timestamps. .. option:: U Use actual timestamps and UIDs/GIDs. Other ~~~~~ .. option:: --format= This option allows for default, gnu, darwin or bsd ```` to be selected. When creating an ``archive``, ```` will default to that of the host machine. .. option:: -h, --help Print a summary of command-line options and their meanings. .. option:: -M This option allows for MRI scripts to be read through the standard input stream. No other options are compatible with this option. .. option:: --rsp-quoting= This option selects the quoting style ```` for response files, either ``posix`` or ``windows``. The default when on Windows is ``windows``, otherwise the default is ``posix``. .. option:: --thin When creating or modifying an archive, this option specifies that the ``archive`` will be thin. By default, archives are not created as thin archives and when modifying a thin archive, it will be converted to a regular archive. .. option:: --version Display the version of the :program:`llvm-ar` executable. .. option:: @ Read command-line options and commands from response file ````. MRI SCRIPTS ----------- :program:`llvm-ar` understands a subset of the MRI scripting interface commonly supported by archivers following in the ar tradition. An MRI script contains a sequence of commands to be executed by the archiver. The :option:`-M` option allows for an MRI script to be passed to :program:`llvm-ar` through the standard input stream. Note that :program:`llvm-ar` has known limitations regarding the use of MRI scripts: * Each script can only create one archive. * Existing archives can not be modified. MRI Script Commands ~~~~~~~~~~~~~~~~~~~ Each command begins with the command's name and must appear on its own line. Some commands have arguments, which must be separated from the name by whitespace. An MRI script should begin with either a :option:`CREATE` or :option:`CREATETHIN` command and will typically end with a :option:`SAVE` command. Any text after either '*' or ';' is treated as a comment. .. option:: CREATE archive Begin creation of a regular archive with the specified name. Subsequent commands act upon this ``archive``. .. option:: CREATETHIN archive Begin creation of a thin archive with the specified name. Subsequent commands act upon this ``archive``. .. option:: ADDLIB archive Append the contents of ``archive`` to the current archive. .. option:: ADDMOD Append ```` to the current archive. .. option:: DELETE Delete the member of the current archive whose file name, excluding directory components, matches ````. .. option:: SAVE Write the current archive to the path specified in the previous :option:`CREATE`/:option:`CREATETHIN` command. .. option:: END Ends the MRI script (optional). EXIT STATUS ----------- If :program:`llvm-ar` succeeds, it will exit with 0. Otherwise, if an error occurs, it will exit with a non-zero value.