LLVM-AR(1)

📦
version 16.0.6 · 3 versions
, in ubuntu noble

llvm-ar 💖 welcome to the LLVM manual, section 1 — yes bestie, the archiver page, and we're doing the whole thing, no skipping. 🎀

✨ NAME ✨

llvm-ar — the LLVM archiver. Short name, big job. 💅

🦋 SYNOPSIS 🦋

llvm-ar [-]{dmpqrstx}[abcDilLNoOPsSTuUvV] [relpos] [count] archive
[files…]

🌸 DESCRIPTION 🌸

okay so llvm-ar is basically the cooler cousin of the classic Unix utility ar. 👑 It takes a bunch of files — object files, LLVM bitcode files, whatever — and archives them into one single archive library that you can then link into a program. The way that it can hold literally any kind of file too, not just the object-file girlies. 🙈

And by default it generates a symbol table, which is the slay part, because it makes linking so much faster — the linker only has to consult that symbol table instead of digging through each individual file member of the archive. Efficiency queen. ✨

The llvm-ar command can read archive files in SVR4, GNU, BSD, Big Archive, and Darwin format, and it can write in GNU, BSD, Big Archive, and Darwin style archive files. But here's the tea 🍓: if you use an SVR4 format archive with the r (replace), d (delete), m (move) or q (quick update) operations, the archive gets reconstructed in whatever format --format defines. Not a choice, it just happens. 💫

Here's where llvm-ar departs from previous ar implementations:

🚫 The following option is not supported

  • [f] — truncate inserted filenames. Nope. Not supported. Not happening. 💀

🙈 The following options are ignored for compatibility

  • --plugin=<string> — load a plugin which adds support for other file formats. Ignored, bestie, it's just there so old scripts don't cry. 😭
  • [l] — ignored in ar. Also just vibing there for compatibility. 🌈

⭐ Symbol Table

Since llvm-ar supports bitcode files, the symbol table it creates includes both native and bitcode symbols. Both. At once. Iconic behavior. 👑

🧚 Deterministic Archives

By default, llvm-ar always uses zero for timestamps and UIDs/GIDs so it writes archives in a deterministic mode. This is literally equivalent to the D modifier being enabled by default. 🎀

If you wish to maintain compatibility with other ar implementations, you can pass the U modifier to write actual timestamps and UIDs/GIDs. That's the tradeoff, bestie — determinism or legacy, pick your fighter. 💅

🦋 Windows Paths

When on Windows, llvm-ar treats the names of archived files in the same case sensitive manner as the operating system. But when on a non-Windows machine, llvm-ar does not consider character case. So yeah — case sensitivity is giving "depends on the OS, iykyk". 🌸

💅 OPTIONS 💅

okay bestie, so here's the tea: llvm-ar's operations play nice with other ar implementations — they're compatible, fr fr. but there are a few modifiers (L) that you literally won't find in any other ar out there. exclusive behavior, we love that. ✨

the options for llvm-ar do a few jobs: they pick a single basic Operation to perform on the archive, a whole buffet of Modifiers for that Operation, the name of the archive file, and optionally a list of file names. and here's the vibe: if the files option isn't specified, it generally means either "none" or "all" members — depends on which operation you're running. Options, Operations and Modifiers all get explained in the sections below, no cap.

the absolute minimum you can get away with? at least one operator plus the name of the archive. that's the bar. 🫶

🦋 Operations 🦋

  • d [NT] — delete files from the archive. the N and T modifiers apply here. the files options tell it which members to remove. and it is not an error if a file you named doesn't actually appear in the archive, so don't panic. if you specify no files at all, the archive is not modified. 💀
  • m [abi] — move files from one spot in the archive to another. the a, b and i modifiers apply. all the files get moved to the location the modifiers give. no modifiers used? they go to the end of the archive. no files specified? archive is not modified, periodt.
  • p [v] — print files to the standard output stream. no files specified = the entire archive gets printed. with the v modifier, llvm-ar also prints out the name of the file it's outputting. ⚠️ printing binary files is ill-advised, bestie, because they might confuse your terminal settings. the p operation never modifies the archive, so at least there's that.
  • q [LT] — quickly append files to the end of the archive without removing duplicates. no files specified? the archive is not modified. the behavior when you append one archive to another depends on whether L and T are in play:
    • appending a regular archive to a regular archive will append the archive file. if the L modifier is specified, the members get appended instead.
    • appending a regular archive to a thin archive requires the T modifier and will append the archive file. the L modifier is not supported here.
    • appending a thin archive to a regular archive will append the archive file. if the L modifier is specified, the members get appended instead.
    • appending a thin archive to a thin archive will always quick append its members.
  • r [abTu] — replace existing files, or insert them at the end of the archive if they don't exist yet. the a, b, T and u modifiers apply. no files specified = archive is not modified.
  • t[v] .. option:: t [vO] — print the table of contents. with no modifiers, it just prints the names of the members to the standard output stream. 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, are ignored when extracting files and set to placeholder values when adding size, and the date. with the 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 gets printed. 👑
  • V — a synonym for the --version option.
  • x [oP] — extract archive members back to files. the o modifier applies here. this retrieves the indicated files from the archive and writes them back to the operating system's file system. no files specified = the entire archive gets extracted. 🎀

🌸 Modifiers (operation specific) 🌸

these ones are specific to certain operations. peek at the Operations section above to figure out which modifiers go with which operations, iykyk.

  • a — when inserting or moving member files, this specifies the destination of the new files as being after the relpos member. if relpos isn't found, the files get placed at the end of the archive. relpos cannot be consumed without either a, b or i.
  • b — when inserting or moving member files, this specifies the destination of the new files as being before the relpos member. if relpos isn't found, the files get placed at the end of the archive. relpos cannot be consumed without either a, b or i. this modifier is identical to the i modifier.
  • i — a synonym for the b option.
  • L — when quick appending an archive, quick append its members instead. this is a feature for llvm-ar that is not found in gnu-ar. special. iconic. ✨
  • N — when extracting or deleting a member that shares its name with another member, the count parameter lets you supply a positive whole number that selects the instance of the given name, with "1" indicating the first instance. if N isn't specified, the first member of that name will be selected. if count isn't supplied, the operation fails.count cannot be
  • 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 instead.
  • O — display member offsets inside the archive.
  • T — alias for --thin. in many ar implementations, T has a different meaning, as specified by X/Open System interface. 🙈
  • v — when printing files or the archive table of contents, this modifier tells llvm-ar to include additional information in the output.

💜 Modifiers (generic) 💜

these ones can be applied to any operation.

  • c — for the r (replace) and q (quick update) operations, llvm-ar will always create the archive if it doesn't exist. normally, llvm-ar prints a warning message saying the archive is being created — using this modifier turns that warning off.
  • D — use zero for timestamps and UIDs/GIDs. this is set by default.
  • P — use full paths when matching member names rather than just the file name. super useful when you're manipulating an archive generated by another archiver, since some of them allow paths as member names. this is the default behavior for thin archives.
  • s — this modifier requests that an archive index (or symbol table) be added to the archive, as if you'd used 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 llvm-ar generates symbol tables in archives. this can also be used as an operation, fun fact.
  • S — the opposite of the s modifier. it tells 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. periodt.
  • u — only update archive members with files that have more recent timestamps.
  • U — use actual timestamps and UIDs/GIDs.

🧚 Other 🧚

  • --format=<type> — this option lets default, gnu, darwin or bsd <type> be selected. when creating an archive, <type> defaults to that of the host machine.
  • -h, --help — print a summary of command-line options and their meanings. 🫶
  • -M — this option lets MRI scripts be read through the standard input stream. no other options are compatible with this option. don't even try it.
  • --output=<dir> — specify a directory where archive members should be extracted to. by default the current working directory is used.
  • --rsp-quoting=<type> — this option selects the quoting style <type> for response files, either posix or windows. the default when on Windows is windows, otherwise the default is posix.
  • --thin — when creating or modifying an archive, this option specifies that the archive will be thin. by default, archives aren't created as thin archives, and when modifying a thin archive, it gets converted to a regular archive. 👀
  • --version — display the version of the llvm-ar executable.
  • -X mode — specifies the type of object file llvm-ar will recognise. mode must be one of these:
    • 32 — process only 32-bit object files.
    • 64 — process only 64-bit object files.
    • 32_64 — process both 32-bit and 64-bit object files.
    • any — process all object files.

the default is to process 32-bit object files (ignore 64-bit objects). the mode can also be set with the OBJECT_MODE environment variable. for example, OBJECT_MODE=64 causes ar to process any 64-bit objects and ignore 32-bit objects. the -X flag overrides the OBJECT_MODE variable. 💅

  • @<FILE> — read command-line options and commands from response file <FILE>.

🌈 MRI SCRIPTS 🌈

llvm-ar understands a subset of the MRI scripting interface that archivers following in the ar tradition commonly support. an MRI script contains a sequence of commands for the archiver to execute. the -M option lets you pass an MRI script to llvm-ar through the standard input stream.

heads up bestie, llvm-ar has known limitations when it comes to MRI scripts: 💀 - each script can only create one archive. - existing archives can not be modified.

⭐ MRI Script Commands ⭐

every command begins with the command's name and must appear on its own line. some commands take arguments, and those must be separated from the name by whitespace. an MRI script should begin with either a CREATE or CREATETHIN command, and will typically end with a SAVE command. any text after either * or ; is treated as a comment.

  • CREATE archive — begin creation of a regular archive with the specified name. subsequent commands act upon this archive.
  • CREATETHIN archive — begin creation of a thin archive with the specified name. subsequent commands act upon this archive.
  • ADDLIB archive — append the contents of archive to the current archive.
  • ADDMOD <file> — append <file> to the current archive.
  • DELETE <file> — delete the member of the current archive whose file name, excluding directory components, matches <file>.
  • SAVE — write the current archive to the path specified in the previous CREATE/CREATETHIN command.
  • END — ends the MRI script (optional).

🎀 EXIT STATUS 🎀

if llvm-ar succeeds, it will exit with 0. otherwise, if an error occurs, it will exit with a non-zero value. simple as. ✨

💖 AUTHOR 💖

maintained by the LLVM Team (https://llvm.org/).

okay so this whole thing? the entire manual page you just read, every flag, every script, every little byte of it — it's all wrapped up in one copyright line and here it is, bestie, exactly as it is:

2003-2024, LLVM Project

that's it, that's the whole vibe. twenty-one whole years of the LLVM Project holding it down from 2003 all the way through 2024, and we are obsessed with the longevity. main character energy for two decades straight, no cap. 👑

and that's a wrap on the whole page, bestie!! 🎀 this was LLVM-AR(1), version</ purple> 15, dated 2024-04-14 — so if you're quoting it in a bug report or an essay or a group chat, now you know exactly which one you're holding. ✨

go archive something iconic, you absolute legend. 💅🦋🌸 bye bestie!! 🫶

📦 where this page comes from