From d00dbb86c0f3d60eb4db569f9b15c8b3bf48c3db Mon Sep 17 00:00:00 2001 From: Owen Reynolds Date: Mon, 21 Oct 2019 13:13:31 +0000 Subject: [PATCH] [docs][llvm-ar] Update llvm-ar command guide The llvm-ar command guide had not been updated in some time, it was missing current functionality and contained information that was out of date. This change: - Updates the use of reStructuredText directives, as seen in other tools command guides. - Updates the command synopsis. - Updates the descriptions of the tool behaviour. - Updates the options section. - Adds details of MRI script functionality. - Removes the sections "Standards" and "File Format" Differential Revision: https://reviews.llvm.org/D68998 git-svn-id: https://llvm.org/svn/llvm-project/llvm/trunk@375412 91177308-0d34-0410-b5e6-96231b3b80d8 --- docs/CommandGuide/llvm-ar.rst | 431 +++++++++++++++++++--------------- 1 file changed, 238 insertions(+), 193 deletions(-) diff --git a/docs/CommandGuide/llvm-ar.rst b/docs/CommandGuide/llvm-ar.rst index 8a36a407e39..60187d8e444 100644 --- a/docs/CommandGuide/llvm-ar.rst +++ b/docs/CommandGuide/llvm-ar.rst @@ -6,297 +6,342 @@ llvm-ar - LLVM archiver SYNOPSIS -------- -**llvm-ar** [-]{dmpqrtx}[Rabfikou] [relpos] [count] [files...] +:program:`llvm-ar` [-]{dmpqrstx}[abcDilLNoOPsSTuUvV] [relpos] [count] archive [files...] DESCRIPTION ----------- -The **llvm-ar** command is similar to the common Unix utility, ``ar``. It -archives several files together into a single file. The intent for this is -to produce archive libraries by LLVM bitcode that can be linked into an -LLVM program. However, the archive can contain any kind of file. By default, -**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 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 **llvm-ar** command can be used to *read* SVR4, GNU and BSD style archive -files. However, right now it can only write in the GNU format. If an -SVR4 or BSD style archive is used with the ``r`` (replace) or ``q`` (quick -update) operations, the archive will be reconstructed in GNU format. +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 **llvm-ar** departs from previous ``ar`` implementations: +Here's where :program:`llvm-ar` departs from previous :program:`ar` +implementations: -*Symbol Table* +*The following option is not supported* + + [f] - truncate inserted filenames + +*The following options are ignored for compatibility* - Since **llvm-ar** supports bitcode files. The symbol table it creates - is in GNU format and includes both native and bitcode files. + --plugin= - load a plugin which adds support for other file formats + + [l] - ignored in :program:`ar` -*Long Paths* +*Symbol Table* - Currently **llvm-ar** can read GNU and BSD long file names, but only writes - archives with the GNU format. + 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 **llvm-ar** treats the names of archived *files* in the same + 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 - **llvm-ar** does not consider character case. + :program:`llvm-ar` does not consider character case. OPTIONS ------- -The options to **llvm-ar** are compatible with other ``ar`` implementations. -However, there are a few modifiers (*R*) that are not found in other ``ar`` -implementations. The options to **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. These options are used to -determine how **llvm-ar** should process the archive file. +: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 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. Typically -archive files end with a ``.a`` suffix, but this is not required. Following -the *archive-name* comes a list of *files* that indicate the specific members -of the archive to operate on. If the *files* option is not specified, it -generally means either "none" or "all" members, depending on the operation. +The minimal set of options is at least one operator and the name of the +archive. Operations ~~~~~~~~~~ -d +.. 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] - Delete files from the archive. No modifiers are applicable 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. + 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. -m[abi] +.. option:: p [v] - Move files from one location in the archive to another. The *a*, *b*, and - *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. + 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. -p +.. option:: q [LT] - Print files to the standard output. This operation simply prints the - *files* indicated to the standard output. If no *files* are - specified, the entire archive is printed. Printing bitcode files is - ill-advised as they might confuse your terminal settings. The *p* - operation never modifies the archive. + 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: -q + * 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. - Quickly append files to the end of the archive. This operation quickly adds the - *files* to the archive without checking for duplicates that should be - removed first. If no *files* are specified, the archive is not modified. - Because of the way that **llvm-ar** constructs the archive file, its dubious - whether the *q* operation is any faster than the *r* operation. + * 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. -r[abu] + * 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. - Replace or insert file members. The *a*, *b*, and *u* - modifiers apply to this operation. This operation will replace existing - *files* or insert them at the end of the archive if they do not exist. If no - *files* are specified, the archive is not modified. + * Appending a thin archive to a thin archive will always quick append its + members. -t[vO] +.. 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. With the *v* modifier, - **llvm-ar** also prints out the file type (B=bitcode, S=symbol - table, blank=regular file), the permission mode, the owner and group, the - 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. + 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 -x[oP] + A synonym for the :option:`--version` option. - Extract archive members back to files. The *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 extract. +.. 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 (above) to determine which modifiers are applicable to which operations. +section to determine which modifiers are applicable to which operations. + +.. option:: a -[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`. - 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. +.. option:: b -[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. - 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. This modifier is - identical to the *i* modifier. +.. option:: i -[i] + A synonym for the :option:`b` option. - A synonym for the *b* option. +.. option:: L -[o] + 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. - When extracting files, this option will cause **llvm-ar** to preserve the - original modification times of the files it writes. +.. 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. -[u] +.. option:: T + + 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. - When replacing existing files in the archive, only replace those files that have - a time stamp than the time stamp of the member in the archive. +.. 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. -[c] +.. 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 - For all operations, **llvm-ar** will always create the archive if it doesn't - exist. Normally, **llvm-ar** will print a warning message indicating that the - archive is being created. Using this modifier turns off that warning. + Use zero for timestamps and UIDs/GIDs. This is set by default. +.. option:: P -[s] + 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. This is the default mode of operation. The symbol table will contain - all the externally visible functions and global variables defined by all the - bitcode files in the archive. + ``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. -[S] +.. option:: S - This modifier is the opposite of the *s* modifier. It instructs **llvm-ar** to - not build the symbol table. If both *s* and *S* are used, the last modifier to - occur in the options will prevail. + 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 -[v] + Only update ``archive`` members with *files* that have more recent + timestamps. + +.. option:: U - This modifier instructs **llvm-ar** to be verbose about what it is doing. Each - editing operation taken against the archive will produce a line of output saying - what is being done. + Use actual timestamps and UIDs/GIDs. -STANDARDS ---------- +Other +~~~~~ -The **llvm-ar** utility is intended to provide a superset of the IEEE Std 1003.2 -(POSIX.2) functionality for ``ar``. **llvm-ar** can read both SVR4 and BSD4.4 (or -macOS) archives. If the ``f`` modifier is given to the ``x`` or ``r`` operations -then **llvm-ar** will write SVR4 compatible archives. Without this modifier, -**llvm-ar** will write BSD4.4 compatible archives that have long names -immediately after the header and indicated using the "#1/ddd" notation for the -name in the header. +.. option:: --format= -FILE 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. -The file format for LLVM Archive files is similar to that of BSD 4.4 or macOS -archive files. In fact, except for the symbol table, the ``ar`` commands on those -operating systems should be able to read LLVM archive files. The details of the -file format follow. +.. option:: -h, --help -Each archive begins with the archive magic number which is the eight printable -characters "!\n" where \n represents the newline character (0x0A). -Following the magic number, the file is composed of even length members that -begin with an archive header and end with a \n padding character if necessary -(to make the length even). Each file member is composed of a header (defined -below), an optional newline-terminated "long file name" and the contents of -the file. + Print a summary of command-line options and their meanings. -The fields of the header are described in the items below. All fields of the -header contain only ASCII characters, are left justified and are right padded -with space characters. +.. option:: -M -name - char[16] + This option allows for MRI scripts to be read through the standard input + stream. No other options are compatible with this option. - This field of the header provides the name of the archive member. If the name is - longer than 15 characters or contains a slash (/) character, then this field - contains ``#1/nnn`` where ``nnn`` provides the length of the name and the ``#1/`` - is literal. In this case, the actual name of the file is provided in the ``nnn`` - bytes immediately following the header. If the name is 15 characters or less, it - is contained directly in this field and terminated with a slash (/) character. +.. option:: --version -date - char[12] + Display the version of the :program:`llvm-ar` executable. - This field provides the date of modification of the file in the form of a - decimal encoded number that provides the number of seconds since the epoch - (since 00:00:00 Jan 1, 1970) per Posix specifications. +.. option:: @ -uid - char[6] + Read command-line options and commands from response file ````. - This field provides the user id of the file encoded as a decimal ASCII string. - This field might not make much sense on non-Unix systems. On Unix, it is the - same value as the st_uid field of the stat structure returned by the stat(2) - operating system call. +MRI SCRIPTS +----------- -gid - char[6] +: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. - This field provides the group id of the file encoded as a decimal ASCII string. - This field might not make much sense on non-Unix systems. On Unix, it is the - same value as the st_gid field of the stat structure returned by the stat(2) - operating system call. +MRI Script Commands +~~~~~~~~~~~~~~~~~~~ -mode - char[8] +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. - This field provides the access mode of the file encoded as an octal ASCII - string. This field might not make much sense on non-Unix systems. On Unix, it - is the same value as the st_mode field of the stat structure returned by the - stat(2) operating system call. +.. option:: CREATE archive -size - char[10] + Begin creation of a regular archive with the specified name. Subsequent + commands act upon this ``archive``. - This field provides the size of the file, in bytes, encoded as a decimal ASCII - string. +.. option:: CREATETHIN archive -fmag - char[2] + Begin creation of a thin archive with the specified name. Subsequent + commands act upon this ``archive``. - This field is the archive file member magic number. Its content is always the - two characters back tick (0x60) and newline (0x0A). This provides some measure - utility in identifying archive files that have been corrupted. +.. option:: ADDLIB archive -offset - vbr encoded 32-bit integer + Append the contents of ``archive`` to the current archive. - The offset item provides the offset into the archive file where the bitcode - member is stored that is associated with the symbol. The offset value is 0 - based at the start of the first "normal" file member. To derive the actual - file offset of the member, you must add the number of bytes occupied by the file - signature (8 bytes) and the symbol tables. The value of this item is encoded - using variable bit rate encoding to reduce the size of the symbol table. - Variable bit rate encoding uses the high bit (0x80) of each byte to indicate - if there are more bytes to follow. The remaining 7 bits in each byte carry bits - from the value. The final byte does not have the high bit set. +.. option:: ADDMOD -length - vbr encoded 32-bit integer + Append ```` to the current archive. - The length item provides the length of the symbol that follows. Like this - *offset* item, the length is variable bit rate encoded. +.. option:: DELETE -symbol - character array + Delete the member of the current archive whose file name, excluding directory + components, matches ````. - The symbol item provides the text of the symbol that is associated with the - *offset*. The symbol is not terminated by any character. Its length is provided - by the *length* field. Note that is allowed (but unwise) to use non-printing - characters (even 0x00) in the symbol. This allows for multiple encodings of - symbol names. +.. option:: SAVE -EXIT STATUS ------------ + Write the current archive to the path specified in the previous + :option:`CREATE`/:option:`CREATETHIN` command. -If **llvm-ar** succeeds, it will exit with 0. A usage error, results -in an exit code of 1. A hard (file system typically) error results in an -exit code of 2. Miscellaneous or unknown errors result in an -exit code of 3. +.. option:: END -SEE ALSO --------- + Ends the MRI script (optional). + +EXIT STATUS +----------- -ar(1) +If :program:`llvm-ar` succeeds, it will exit with 0. Otherwise, if an error occurs, it +will exit with a non-zero value. -- 2.40.0