diff --git a/docs/CommandGuide/llvm-ar.pod b/docs/CommandGuide/llvm-ar.pod new file mode 100644 index 00000000000..aff72fd3721 --- /dev/null +++ b/docs/CommandGuide/llvm-ar.pod @@ -0,0 +1,238 @@ +=pod + +=head1 NAME + +llvm-ar - LLVM archiver + +=head1 SYNOPSIS + +B [-X32_64] [-]{dmpqrtx}[Rabfouz] [relpos] [count] [files...] + + +=head1 DESCRIPTION + +The B command is similar to the common Unix utility, C. It +archives several files together into a single file. The intent for this is +to produce archive libraries by LLVM bytecode that can be linked into an +LLVM program. However, the archive can contain any kind of file. If requested, +B can generate a symbol table that makes linking faster because +only the symbol table needs to be consulted, not each individual file member +of the archive. + +While the B command produces files that are similar to the format +used by older C implementations, it has several significant departures +in order to make the archive appropriate for LLVM. Consequently, archives +produced with B probably won't be readable or editable with any +C implementation unless the archive content is very simple. + +Here's where B departs from previous C implementations: + +=over + +=item I + +Since B is intended to archive bytecode files, the symbol table +won't make much sense to anything but LLVM. Consequently, the symbol table's +format has been simplified. It consists simply of a sequence of pairs +of a file member index number as an LSB 4byte integer and a null-terminated +string. + +=item I + +Some C implementations (SVR4) use a separate file member to record long +path names (> 15 characters). B takes the BSD 4.4 and Mac OS X +approach which is to simply store the full path name immediately preceding +the data for the file. The path name is null terminated and may contain the +slash (/) character. + +=item I + +B can compress the members of an archive to save space. The +compression used depends on what's available on the platform but favors +bzip2 and then zlib. Note that for very small files, bzip2 may increase +the file size but generally does about 10% better than zlib on LLVM +bytecode files. + +=item I + +Most C implementations do not recurse through directories but simply +ignore directories if they are presented to the program in the F +option. B, however, can recurse through directory structures and +add all the files under a directory, if requested. + +=item I + +When B prints out the verbose table of contents (C option), it +precedes the usual output with a character indicating the basic kind of +content in the file. A blank means the file is a regular file. A 'Z' means +the file is compressed. A 'B' means the file is an LLVM bytecode file. An +'S' means the file is the symbol table. + +=back + +=head1 OPTIONS + +The options to B are compatible with other C implementations. +However, there are a few modifiers (F) that are not found in other +Cs. The options to B 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 B should process the archive file. + +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 C<.a> suffix, but this is not required. Following +the F comes a list of F that indicate the specific members +of the archive to operate on. If the F option is not specified, it +generally means either "none" or "all" members, depending on the operation. + +=head2 Operations + +=over + +=item d + +Delete files from the archive. No modifiers are applicable to this operation. +The F 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 F are specified, the archive is not modified. + +=item m[abi] + +Move files from one location in the archive to another. The F, F, and +F modifiers apply to this operation. The F 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 F are specified, the +archive is not modified. + +=item p + +Print files to the standard output. No modifiers are applicable to this +operation. This operation simply prints the F indicated to the +standard output. If no F are specified, the entire archive is printed. +Printing bytecode files is ill-advised as they might confuse your terminal +settings. The F

operation never modifies the archive. + +=item q[Rfz] + +Quickly append files to the end of the archive. The F, F, and F +modifiers apply to this operation. This operation quickly adds the +F to the archive without checking for duplicates that shoud be +removed first. If no F are specified, the archive is not modified. +Becasue of the way that B constructs the archive file, its dubious +whether the F operation is any faster than the F operation. + +=item r[Rabfuz] + +Replace or insert file members. The F, F, F, F, F, and F +modifiers apply to this operation. This operation will replace existing +F or insert them at the end of the archive if they do not exist. If no +F are specified, the archive is not modified. + +=item t[v] + +Print the table of contents. Without any modifiers, this operation just prints +the names of the members to the standard output. With the F modifier, +B also prints out the file type (B=bytecode, Z=compressed, S=symbol +table, blank=regular file), the permission mode, the owner and group, the +size, and the date. If any F are specified, the listing is only for +those files. If no F are specified, the table of contents for the +whole archive is printed. + +=item x[o] + +Extract archive members back to files. The F modifier applies to this +operation. This operation retrieves the indicated F from the archive +and writes them back to the operating system's file system. If no +F are specified, the entire archive is extract. + +=back + +=head2 Modifiers (operation specific) + +=over + +=item [a] + +put F after [relpos] + +=item [b] + +put F before [relpos] (same as [i]) + +=item [f] + +truncate inserted file names + +=item [i] + +put file(s) before [relpos] (same as [b]) + +=item [N] + +use instance [count] of name + +=item [o] + +preserve original dates + +=item [P] + +use full path names when matching + +=item [R] + +recurse through directories when inserting + +=item [u] + +update only files newer than archive contents + +=item [z] + +compress/uncompress files before inserting/extracting + +=back + +=head2 Modifiers (generic) + +=over + +=item [c] + +do not warn if the library had to be created + +=item [s] + +create an archive index (cf. ranlib) + +=item [S] + +do not build a symbol table + +=item [R] + +recursively process directories + +=item [v] + +be verbose + +=back + +=head1 EXIT STATUS + +If B 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. + +=head1 SEE ALSO + +L + +=head1 AUTHORS + +Maintained by the LLVM Team (L). + +=cut