LLVM-AR(1)

📦
version 11.1.0 · 2 versions
, in fedora 43, fedora 44

💖 NAME 💖

llvm-ar — the LLVM archiver, obviously 💅

🎀 SYNOPSIS 🎀

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

✨ DESCRIPTION ✨

okay so bestie, picture this: llvm-ar is basically the cool cousin of the classic Unix utility ar. What it does is it takes a bunch of files — like object files and LLVM bitcode files — and smooshes them all into one single archive library that you can then link into a program. but lowkey? the archive can hold any kind of file, not just those. by default, llvm-ar generates a symbol table, and that is the moment because it makes linking so much faster — the linker only has to consult that symbol table instead of opening up every single file member of the archive one by one. iconic behavior, fr fr 🦋

llvm-ar can read archive files in SVR4, GNU, BSD and Darwin formats, and it can write in GNU, BSD, and Darwin style archive files. one thing tho: if you hand it an SVR4 format archive and use it with the r (replace), d (delete), m (move) or q (quick update) operations, the archive is gonna get reconstructed in whatever format --format defines. so heads up ✨

and here's where llvm-ar straight up departs from the previous ar implementations, no cap:

The following option is not supported

  • [f] — truncate inserted filenames. nope, not a thing here, we don't do that 💀

The following options are ignored for compatibility

  • --plugin=<string> — load a plugin which adds support for other file formats. (it's ignored, bestie, it's just there so nothing breaks 🙈)
  • [l] — ignored in ar

Symbol Table

since llvm-ar supports bitcode files, the symbol table it creates includes both native and bitcode symbols. yeah. both. we contain multitudes 💜

Deterministic Archives

by default, llvm-ar always uses zero for timestamps and UIDs/GIDs when writing archives — that's the deterministic mode. it's literally equivalent to the D modifier being enabled by default. so if you wanna maintain compatibility with other ar implementations and write out the actual timestamps and UIDs/GIDs, you pass the U modifier. that's the whole vibe check right there 🎀

Windows Paths

when you're on Windows, llvm-ar treats the names of archived files in the same case sensitive manner as the operating system. when you're on a non-Windows machine, llvm-ar does not consider character case at all. so like, know where you are, bestie 🌸

👑 OPTIONS 👑

llvm-ar operations are compatible with other ar implementations. however, there are a few modifiers (L) that you will not find in other ar implementations — that one's our exclusive 🎀

so here's the deal: 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 all explained in the sections below 💅

the minimal set of options is at least one operator and the name of the archive. that's the floor, bestie.

🌈 Operations 🌈

  • d [NT] — Delete files from the archive. The N and 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. And if no files are specified, the archive is not modified. chill.
  • m [abi] — 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.
  • p [v] — Print files to the standard output stream. If no files are specified, the entire archive is printed. With the v modifier, 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. like genuinely, don't do it, your terminal will never recover 💀

The p operation never modifies the archive. periodt.

  • 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 L and T modifiers are used:
    • Appending a regular archive to a regular archive will append the archive file. If the L modifier is specified the members will be 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.
    • Appending a thin archive to a regular archive will append the archive file. If the L modifier is specified the members will be 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 do not exist. The a, b, T and u modifiers apply to this operation. If no files are specified, the archive is not modified.
  • t [vO] — Print the table of contents. (ngl the raw page literally reads t[v] .. option:: t [vO] — a lil doc glitch, but the vibes are immaculate so we keep it 💅) Without any modifiers, this operation 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 is printed.
  • V — a synonym for the --version option. same energy, different letter ✨
  • x [oP] — 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 extracted. get those files back, bestie 🦋

🧚 Modifiers (operation specific) 🧚

the modifiers below are specific to certain operations. See the Operations section to determine which modifiers are applicable to which operations. iykyk 💜

  • 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 a, b or i.
  • 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 a, b or i. This modifier is identical to the i modifier.
  • i — a synonym for the b option. that's it, that's the whole thing 🎀
  • L — When quick appending an archive, instead quick append its members. This is a feature for llvm-ar that is not found in gnu-ar. exclusive behavior, we love to see it ✨
  • 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 N is not specified the first member of that name will be selected.
🙈 okay so the original page's sentence here just... stops. it literally reads: "If count is not supplied, the operation fails.count cannot be" — and then nothing. the sentence is incomplete in the source and we're not gonna invent an ending for it, bestie. that's the whole note as written 💀
  • 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.
  • O — Display member offsets inside the archive.
  • 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. careful with that one 🌸
  • v — When printing files or the archive table of contents, this modifier instructs llvm-ar to include additional information in the output. more info, more better 💅

🌸 Modifiers (generic) 🌸

the modifiers below may be applied to any operation. universal besties 🫶

  • 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 will print a warning message indicating that the archive is being created. Using this modifier turns off that warning. shhh, no more warning ✨
  • D — Use zero for timestamps and UIDs/GIDs. This is set by default. so like, you already have it, no need to ask 💜
  • 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.
  • 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 llvm-ar generates symbol tables in archives. This can also be used as an operation. multitasking queen 👑
  • 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. last one standing wins 💅
  • u — Only update archive members with files that have more recent timestamps.
  • U — Use actual timestamps and UIDs/GIDs. (the non-deterministic option, for when you want the real ones ✨)

🍓 Other 🍓

  • --format=<type> — This option allows for default, gnu, darwin or bsd <type> to be selected. When creating an archive, <type> will default to that of the host machine.
  • -h, --help — Print a summary of command-line options and their meanings. your lil cheat sheet 🎀
  • -M — This option allows for MRI scripts to be read through the standard input stream. No other options are compatible with this option. like, none. it's a solo act, main character energy only 👑
  • --version — Display the version of the llvm-ar executable.
  • @<FILE> — Read command-line options and commands from response file <FILE>. convenient, honestly ✨
🌈 and that's part one, bestie — there's more coming, so stay tuned 💖

✨ MRI SCRIPTS ✨

okay so bestie, llvm-ar gets a subset of the MRI scripting interface that's commonly supported by archivers following in the ar tradition. iykyk 💖 An MRI script is literally just a sequence of commands that the archiver runs one by one. And the -M option? That's your VIP pass to feed an MRI script to llvm-ar through the standard input stream. 🎀

But hold up, there are some known limitations with MRI scripts in llvm-ar, and we gotta talk about them:

  • Each script can only create one archive. One. Singular. No multitasking. 💅
  • Existing archives can not be modified. So no glow-ups for archives that already exist, bestie. 🙈

🧚 MRI Script Commands 🧚

Every command starts with the command's name, and it must appear on its own line. Some commands have arguments, and those arguments have to be separated from the name by whitespace. No arguments glued to the name, okay? ✨

An MRI script should begin with either a CREATE or CREATETHIN command, and it will typically end with a SAVE command. Also, any text after either * or ; is treated as a comment. So go off, leave notes, they're just comments. 📝

  • CREATE archive — Begin creation of a regular archive with the specified name. Subsequent commands act upon this archive. It's giving main character energy 👑
  • CREATETHIN archive — Begin creation of a thin archive with the specified name. Subsequent commands act upon this archive. Thin but iconic 🦋
  • ADDLIB archive — Append the contents of archive to the current archive. Sharing is caring, bestie 💖
  • ADDMOD <file> — Append <file> to the current archive. Just slide it in there 🫶
  • DELETE <file> — Delete the member of the current archive whose file name, excluding directory components, matches <file>. Bye bestie, not you tho 💀
  • SAVE — Write the current archive to the path specified in the previous CREATE/CREATETHIN command. This is the moment. The save. The slay. ✨
  • END — Ends the MRI script (optional). Optional but cute. 🎀

💅 EXIT STATUS 💅

If llvm-ar succeeds, it will exit with 0. Otherwise, if an error occurs, it will exit with a non-zero value. No cap. 😭

👑 AUTHOR 👑

Maintained by the LLVM Team (https://llvm.org/). They're the real ones. 🫶

2003-2024, LLVM Project. Periodt. 💜

This page is from LLVM-AR(1), version 11, dated 2024-07-18. Stay slaying, bestie 💅✨

📦 where this page comes from