LLVM-AR(1)

📦
version 12.0.1 · 4 versions
, in fedora 43, fedora 44

✨ NAME ✨

llvm-ar — LLVM archiver 🎀

🦋 SYNOPSIS 🦋

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

💅 DESCRIPTION 💅

okay bestie, so llvm-ar is literally giving "same vibe as the common Unix utility ar" energy. It archives several files — such as objects and LLVM bitcode files — into a single archive library that can be linked into a program. But plot twist: 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. periodt.

The 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 r (replace), d (delete), m (move), or q (quick update) operations, the archive will be reconstructed in the format defined by --format. no cap.

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

🚫 The following option is not supported 🚫

  • [f] — truncate inserted filenames

🙈 The following options are ignored for compatibility 🙈

  • --plugin=<string> — load a plugin which adds support for other file formats
  • [l] — ignored in ar

🔮 Symbol Table 🔮

Since llvm-ar supports bitcode files, the symbol table it creates includes both native and bitcode symbols. iconic.

⏰ Deterministic Archives ⏰

By default, llvm-ar always uses zero for timestamps and UIDs/GIDs to write archives in a deterministic mode. This is 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.

🪟 Windows Paths 🪟

When on Windows, 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.

👑 OPTIONS 👑

llvm-ar operations are compatible with other ar implementations. However, there are a few modifiers (L) that are not found in other ar implementations. The options for 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 ✨

  • d [NT] — Yeet files out of the archive. The N and T modifiers apply here. The files options tell llvm-ar which members to remove. If a file you name isn't actually in the archive, that's not an error — no drama. If you specify no files at all, the archive stays untouched.
  • 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 wherever the modifiers say. If you use no modifiers, they all get moved to the end of the archive. If you name no files, the archive doesn't change.
  • p [v] — Print files straight to the standard output stream. If you don't name any files, the whole archive gets printed. With the v modifier, llvm-ar also prints the name of the file it's outputting. Printing binary files is ill-advised — they can mess up your terminal settings. The p operation never modifies the archive, periodt.
  • q [LT] — Quickly append files to the end of the archive without removing duplicates. If you name no files, the archive is not modified. When you append one archive to another, the behavior depends on whether the L and T modifiers are used:
    • Regular archive into regular archive: it appends the archive file. If you pass L, it appends the members instead.
    • Regular archive into thin archive: requires the T modifier, and it appends the archive file. The L modifier is not supported here.
    • Thin archive into regular archive: it appends the archive file. If you pass L, it appends the members instead.
    • Thin archive into thin archive: it always quick appends its members.
  • r [abTu] — Replace files that already exist, or insert them at the end of the archive if they don't exist yet. The a, b, T and u modifiers apply. If you name no files, the archive is not modified.
  • t[v] .. option:: t [vO] — Print the table of contents. With no modifiers, it just prints the member names to standard output. With the v modifier, llvm-ar also prints 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, it displays member offsets. If you name any files, the listing is only for those files. If you name no files, the table of contents for the whole archive is printed.
  • V — Just a synonym for the --version option.
  • x [oP] — Extract archive members back into files. The o modifier applies here. This operation grabs the indicated files from the archive and writes them back to the operating system's file system. If you name no files, the whole archive gets extracted.

🌸 Modifiers (operation specific) 🌸

These modifiers are specific to certain operations. Check the Operations section to see which ones apply to which operation.

  • a — When you're inserting or moving member files, this option says the new files go 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 you're inserting or moving member files, this option says the new files go 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 you're quick appending an archive, instead quick append its members. This is a feature for llvm-ar that you won't find in gnu-ar.
  • N — When you're extracting or deleting a member that shares its name with another member, the count parameter lets you supply a positive whole number that selects which instance of that name you mean. "1" means the first instance. If N isn't specified, the first member with that name gets selected. If count is not supplied, the operation fails.count cannot be
  • o — When extracting files, use the modification times of those files as they appear in the archive. By default, files extracted from the archive use the time of extraction.
  • O — Display member offsets inside the archive.
  • T — When you're creating or modifying an archive, this option says the archive will be thin. By default, archives are not created as thin archives, and when you modify a thin archive, it gets converted to a regular archive.
  • v — When printing files or the archive table of contents, this modifier tells llvm-ar to include extra information in the output.

💜 Modifiers (generic) 💜

These modifiers 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 off that warning.
  • D — Use zero for timestamps and UIDs/GIDs. This is set by default.
  • P — Use full paths when matching member names instead of just the file name. This can be useful when you're manipulating an archive generated by another archiver, because some allow paths as member names. This is the default behavior for thin archives.
  • s — This modifier asks for an archive index (or symbol table) to be added to the archive, as if you 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.
  • S — This modifier is the opposite of the s modifier. It tells llvm-ar not to build the symbol table. If both s and S are used, the last modifier to appear in the options wins.
  • 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 you select default, gnu, darwin or bsd as the <type>. When creating an archive, <type> defaults to that of the host machine.
  • -h, --help — Print a summary of command-line options and what they mean.
  • -M — This option lets MRI scripts be read through the standard input stream. No other options are compatible with this option.
  • --version — Display the version of the llvm-ar executable.
  • @<FILE> — Read command-line options and commands from the response file <FILE>.

💖 MRI SCRIPTS 💖

okay bestie so llvm-ar also speaks a little bit of the MRI scripting language — yk, the one all the archivers in the ar tradition keep around like a family heirloom 🎀. An MRI script is just a whole sequence of commands that the archiver runs through one by one. And how do you feed it to llvm-ar? Through the -M option, which lets you pipe an MRI script in over the standard input stream. iconic. 💅

heads up tho, because llvm-ar has some known limitations with MRI scripts and you need to know them: - Each script can only create one archive. one. that's it. no multitasking. 😭 - Existing archives can not be modified. not even a little. 🙈

✨ MRI Script Commands ✨

Every command starts with the command's name, and it must be on its own line — no sharing lines, no sneaking it in at the end of another one. Some commands take arguments, and those arguments have to be separated from the name by whitespace, ok? ✨

An MRI script should begin with either a CREATE or a CREATETHIN command, and it will typically end with a SAVE command. And anything you write after either * or ; is treated as a comment — so go ahead and leave yourself lil notes, you deserve it. 🫶

  • CREATE archive — kick off creation of a regular archive with the name you specify. Every command after this one acts upon this archive. 👑
  • CREATETHIN archive — same vibe, but you're starting a thin archive with the specified name instead. Subsequent commands act upon this archive. 🦋
  • ADDLIB archive — append the whole contents of archive into the current archive. like a group hug but for members. 🌸
  • ADDMOD <file> — append <file> to the current archive. single file, single serve. 🍓
  • DELETE <file> — delete the member of the current archive whose file name, excluding directory components, matches <file>. so it's matching on the bare name, not the whole path, mwah 💜
  • SAVE — write the current archive out to the path specified back in the previous CREATE/CREATETHIN command. this is the moment, the main character moment 🌟
  • END — ends the MRI script. and it's optional, so if you're done you're done, periodt. 💅

🌈 EXIT STATUS 🌈

If llvm-ar succeeds, it will exit with 0. If an error happens instead, it exits with a non-zero value. that's the whole vibe check right there ✨

💜 AUTHOR 💜

Maintained by the LLVM Team (https://llvm.org/). shoutout to the maintainers, fr fr 🫶

2003-2024, LLVM Project

and that's the page bestie!! 🌸 this one's from the LLVM-AR(1) manual, section 12, dated 2024-07-18 — so when you're out here scripting archives like a legend, you'll know exactly who wrote the lore. iykyk 💖✨🦋

📦 where this page comes from