LLVM-IFS(1)

💅 LLVM-IFS(1) — like, the llvm-ifs page, but make it make sense

okay bestie, buckle up, because llvm-ifs is genuinely one of those tools that sounds scary and then turns out to be iconic. it's the local llvm-ifs manual, and we're gonna go through the whole thing together, no skipped sections, no skipped flags, periodt. 🎀

---

✨ NAME ✨

llvm-ifs — shared object stubbing tool 🫶

like, the whole job is stubs. that's the vibe.

---

✨ SYNOPSIS ✨

llvm-ifs [options] inputs

that's it. options first, then your inputs. slay.

---

✨ DESCRIPTION ✨

so here's the tea: llvm-ifs is a tool that jointly produces two things for shared objects — and by "jointly" i mean it does both, together, in one go:

• human readable, text-based stubs (.ifs files) for shared objects 💖
• linkable shared object stubs (.so files) 🔥

and it makes them from either ELF shared objects or text-based stubs. either direction, she's flexible.

ngl the text-based stubs are the main character here — they're useful for monitoring ABI changes of the shared object. like a little watchdog for your ABI. 👑

and the linkable shared object stubs? those are for avoiding unnecessary relinks when the ABI of shared libraries does not change. no ABI change = no relink = we stay unbothered. ✨

---

🌈 IFS FORMATS 🌈

here's an example of the text representation (IFS) of a shared object, produced by llvm-ifs. look at her. gorgeous:

--- !ifs-v1
IFSVersion: 3.0
SoName: libtest.so /* Optional */
Target: x86_64-unknown-linux-gnu   /* Optional, format 1, same format as llvm target triple */
Target: { Arch: x86_64, Endianness: little, Bitwidth: 64 } /* Optional, format 2 */
NeededLibs:
  - libc.so.6
Symbols:
  - { Name: sym0, Type: Notype }
  - { Name: sym1, Type: Object, Size: 0 }
  - { Name: sym2, Type: Func, Weak: false }
  - { Name: sym3, Type: TLS }
  - { Name: sym4, Type: Unknown, Warning: foo }
...

now let's break down every field, because iykyk:

• IFSVersion: the version of the IFS file, for reader compatibility. so the reader knows what it's dealing with. 💅
• SoName (optional): the name of the shared object file that is being stubbed.
• Target (optional): the architecture, endianness and bitwise information of this shared object. it can be either in explicit format or in implicit LLVM triple format. it can be optional, and it can be overridden from command line options. flexible queen. 🦋
• NeededLibs: the list of the external shared objects that this library depends on.
• Symbols: a collection of all data needed to link objects for each symbol, sorted by name in ascending order. and inside Symbols we got the little sub-fields:
  • Name: symbol name.
  • Type: whether the symbol is an object, function, no-type, thread local storage, or unknown. and here's the cute part — symbol types that aren't explicitly supported are mapped as unknown to improve signal-to-noise ratio. she's keeping it clean. ✨
  • Size: the size of the symbol in question. it doesn't apply to functions, and it's optional for NoType symbols.
  • Undefined: whether or not the symbol is defined in this shared object file.
  • Weak: whether or not the symbol should be treated as weak.
  • Warning (optional): warning text to output when this symbol is linked against. ⚠️

and now the big picture, because this matters: this YAML based text format contains everything that is needed to generate a linkable ELF shared object as well as an Apple TAPI format file. everything. all of it. 🫶

the ordering of symbols is sorted, so these files can be easily compared using diff tools. and if the content of the file changes, it indicates a potentially ABI breaking change. 🔥 that's the whole point — diff it, spot the break, save your build.

---

🦋 ELF STUB FORMAT 🦋

a minimum ELF file that can be used by a linker should have the following sections properly populated. every single one, bestie, no skipping:

• ELF header.
• Section headers.
• Dynamic symbol table (.dynsym section).
• Dynamic string table (.dynstr section).
• Dynamic table (.dynamic section), which contains:
  • DT_SYMTAB entry.
  • DT_STRTAB entry.
  • DT_STRSZ entry.
  • DT_NEEDED entries. (optional)
  • DT_SONAME entry. (optional)
• Section header string table (.shstrtab section)

⚠️ heads up: this ELF file may have compatibility issues with ELF analysis tools that rely on the program headers. but linkers like LLD work fine with such a minimum ELF file, without errors. so like, know your audience. 💀

---

✨ OPTIONS ✨

okay here's every single flag, we're not leaving a single one behind 💖

• --input-format=[IFS|ELF|OtherObjectFileFormats] — specify the input file format. currently, only text IFS files and ELF shared object files are supported. this flag is optional, since the input format can be inferred anyway. 🧚
• --output-elf=<output-filename> — specify the output file for the ELF shared object stub.
• --output-ifs=<output-filename> — specify the output file for the text IFS.
• --output-tbd=<output-filename> — specify the output file for the Apple TAPI tbd.
• --arch=[x86_64|AArch64|...] — optional, and it should only be used when reading an IFS file which does not define the Arch (architecture). this flag defines the architecture of the output file, and can be any string supported by the ELF e_machine field. if the value conflicts with the IFS file, an error will be reported and the program will stop. 😭
• --endianness=[little|big] — optional, and it should only be used when reading an IFS file which does not define the Endianness. this flag defines the endianness of the output file. if the value conflicts with the IFS file, an error will be reported and the program will stop.
• --bitwidth=[32|64] — optional, and it should only be used when reading an IFS file which does not define the BitWidth. this flag defines the bit width of the output file. if the value conflicts with the input IFS file, an error will be reported and the program will stop.
• --target=<target triple> — optional, and should only be used when reading an IFS file which does not define any target information. this flag defines the architecture, endianness and bit width of the output file using an llvm target triple. 🎯 this flag cannot be used simultaneously with other target related flags. pick a lane.
• --hint-ifs-target=<target triple> — optional, and should only be used when reading an ELF shared object and generating an IFS file. by default, llvm-ifs will use the Arch, Endianness and BitWidth fields to reflect the target information from the input object file. using this flag tells llvm-ifs the expected target triple in the output IFS file. if the value matches the target information from the object file, this value will be used in the Target: field in the generated IFS. if it conflicts with the input object file, an error will be reported and the program will stop. 💅
• --hint-ifs-target — optional, and should only be used when outputting an IFS file. this flag strips the Arch field from the IFS file so it can be overridden later. 🌸
• --strip-ifs-endianness — optional, and should only be used when outputting an IFS file. this flag strips the Endianness field from the IFS file so it can be overridden later.
• --strip-ifs-bitwidth — optional, and should only be used when outputting an IFS file. this flag strips the BitWidth field from the IFS file so it can be overridden later.
• --strip-ifs-target — optional, and should only be used when outputting an IFS file. this flag strips the Target field from the IFS file so it can be overridden later.
• --write-if-changed — when this flag is set, llvm-ifs will only write the output file if it does not already exist, or if the content will be different from the existing file. no pointless writes, we respect the filesystem. 💜
• --strip-size — when this flag is set, llvm-ifs will remove the size field from the output IFS file. this is useful for shared objects that only intend to be linked against position independent code, which doesn't need copy relocations — or where the size of an object is not a useful part of the ABI to track. 🔥

---

💀 EXIT STATUS 💀

if llvm-ifs succeeds, it will exit with 0. 🎉 otherwise, if an error occurs, it will exit with a non-zero value. that's it, that's the whole drama.

---

👑 AUTHOR 👑

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

---

🎀 COPYRIGHT 🎀

2003-2023, LLVM Project. periodt.

---

and that's the whole page, bestie!! 💖 no cap, you now know llvm-ifs better than most people who use it daily. mwah. 🫶

sign-off szn: this page is page 15, dated 2023-01-14, from the LLVM manual collection — so like, when you cite her, cite her right. go forth and stub. 💅✨