swift-section-cli
/swift-section-cli
Recovering Swift and Objective-C declarations and ABI facts from a Mach-O binary or a dyld shared cache with the `swift-section` CLI — dumping types / protocols / conformances, generating a .swiftinterface offline, Objective-C headers with IMP addresses, diffing the API of two builds, tracking it across OS versions, and the static field-offset / type-layout / enum-layout comments. Read before running swift-section, and whenever a task needs type information out of a binary without loading it into a process. Triggers on swift-section, swift-section objc, objc-section, MachOSwiftSection, __swift
- Repository
- machoswiftsection ↗
- Licence
- MIT
- Last repository change
- 26.10.2026
Assessment and security
- Files in this package
- 2
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 2
No signals detected. Repository changed on 26.10.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
What it does and when to use it
Recovering Swift and Objective-C declarations and ABI facts from a Mach-O binary or a dyld shared cache with the `swift-section` CLI — dumping types / protocols / conformances, generating a .swiftinterface offline, Objective-C headers with IMP addresses, diffing the API of two builds, tracking it across OS versions, and the static field-offset / type-layout / enum-layout comments. Read before running swift-section, and whenever a task needs type information out of a binary without loading it into a process. Triggers on swift-section, swift-section objc, objc-section, MachOSwiftSection, __swift
Original author description
Recovering Swift and Objective-C declarations and ABI facts from a Mach-O binary or a dyld shared cache with the `swift-section` CLI — dumping types / protocols / conformances, generating a .swiftinterface offline, Objective-C headers with IMP addresses, diffing the API of two builds, tracking it across OS versions, and the static field-offset / type-layout / enum-layout comments. Read before running swift-section, and whenever a task needs type information out of a binary without loading it into a process. Triggers on swift-section, swift-section objc, objc-section, MachOSwiftSection, __swift
How it works
- 0. Confirm the version before trusting a flag
- 1. Pick the subcommand
- 2. Pointing it at the binary
- 3. Never redirect interface's stdout — pass -o
- 4. dump and interface do not share flag spellings
- 5. interface is expensive; dump is not
- 6. Comment templates
- 7. diff / snapshot / evolution
- 8. --resolve-c-module-names (interface, macOS only)
- 9. Reading the output: things that look like bugs and are not
SKILL.md preview
---
name: swift-section-cli
description: >-
Recovering Swift and Objective-C declarations and ABI facts from a Mach-O binary or a dyld
shared cache with the `swift-section` CLI — dumping types / protocols / conformances,
generating a .swiftinterface offline, Objective-C headers with IMP addresses, diffing the API
of two builds, tracking it across OS versions, and the static field-offset / type-layout /
enum-layout comments. Read before running swift-section, and whenever a task needs type
information out of a binary without loading it into a process. Triggers on swift-section,
swift-section objc, objc-section, MachOSwiftSection, __swift5_types, swiftinterface,
ABI diff, ABI baseline.
---
# swift-section
A CLI that reads Swift metadata straight out of a Mach-O file — the compiler-emitted
`__swift5_*` sections plus the symbol table — and reconstructs source-level declarations from
it. Nothing is loaded into a process and no source or `.swiftmodule` is needed, so it works on
a stripped OS framework, a third-party app binary, or an image inside a dyld shared cache. Its
`objc` subcommand does the same for the Objective-C metadata (§1).
**Where it sits next to other reverse-engineering tools.** It is the offline, scriptable form
of the library [RuntimeViewer](https://github.com/MxIris-Reverse-Engineering/RuntimeViewer)
uses. Reach for it when the target is a file rather than something loadable, when the build is
not the one running on this machine (an archived cache, another OS version, another platform),
or when the answer must be diffed or committed. swift-section recovers *declarations, layout
and addresses*, never instruction-level behaviour: for what a method actually does, take its
address from here (`--emit-member-addresses`, or the IMP comments of `objc`) and hand that
address to a disassembler or decompiler opened on **the same build**. An address from one build
means nothing in another.
## 0. Confirm the version before trusting a flag
The installed binary (`brew install swift-section`, on `PATH`) is often older than the
repository, and flags are added frequently. Confirm before building a command line on one:
```bash
swift-section --version
swift-section interface --help | grep -- --exported-only # empty ⇒ this build lacks it
```
Flags added comparatively late, and therefore worth checking: `--emit-header`,
`--emit-export-status`, `--exported-only`, `--jobs`, `evolution --interface`,
`--supplementary-apinotes`, from 0.20.0 `--dependency-search-path`,
`--infer-objc-overrides` and the whole `objc` subcommand group, from 0.22.0
`evolution --emit-available` / `--platform`, from 0.23.0 `interface --module-selectors`
/ `dump --enable-module-selectors`, and from 0.24.0
`interface --requirements-on-associated-types` and `--emit-private-source-files`. When one is
missing, say so rather than silently producing a weaker answer — the alternative is usually
"upgrade (`brew upgrade swift-section`), or do without that annotation".
## 1. Pick the subcommand
| The question | Subcommand |
|---|---|
| What Swift types / protocols / conformances does this binary contain? | `dump` |
| Give me something that reads like Swift source (or pastes into an editor) | `interface` |
| What changed in the ABI between these two builds? | `diff` |
| Freeze today's ABI so a future build can be compared without keeping the binary | `snapshot` |
| How did this API evolve across N OS versions? | `evolution` |
| Reformat the memory-layout comments the two above emit | `transformer` |
| Objective-C headers, IMP addresses, or an Objective-C API diff (0.20.0+, formerly the separate `objc-section` executable) | `objc` — read `references/objc.md` first |
`dump` is the default subcommand: `swift-section <path>` is `swift-section dump <path>`.
**`dump` versus `interface` is not a cosmetic choice.** `dump` walks the sections one by one
and prints what each record literally says — descriptors, witness-table entries, associated
types — in binary order if asked. `interface` builds a whole declaration model first: it
indexes every symbol in the image, merges extensions, joins accessors to their vtable entries,
recovers `final` / `class` keywords, and only then prints. That model is what makes the output
readable, and it is also why `interface` costs orders of magnitude more (see §5). Start with
`dump` to find out whether the type is even there; escalate to `interface` when you need to
read it.
## 2. Pointing it at the binary
Three input shapes, and the option that selects each:
```bash
# 1. A file on disk. A fat (universal) binary REQUIRES an architecture — the tool
# refuses to pick a slice and lists what it found.
swift-section dump /path/to/Foo.framework/Foo --architecture arm64e
# 2. An image inside the running system's shared cache (frameworks are not on disk
# as separate files on modern macOS/iOS).
swift-section dump --uses-system-dyld-shared-cache --cache-image-name SwiftUICore
# 3. An image inside a specific cache file (an archived one, a simulator runtime's).
swift-section dump --dyld-shared-cache --cache-image-path /System/Library/.../SwiftUI /path/to/dyld_shared_cache
```
- `-n` / `--cache-image-name` takes a **bare image name** (`SwiftUICore`); `-p` /
`--cache-image-path` takes the **install path**. Pass exactly one — both together is an
error. Prefer `-p` when a leaf name is ambiguous inside the cache (a macOS cache carries
Mac Catalyst builds under `/System/iOSSupport` with the same leaf names).
- `diff` and `evolution` read `--dyld-shared-cache` differently: it means "every input path is
a cache, extract the same `-n` image from each". They have no
`--uses-system-dyld-shared-cache`, and `snapshot` rejects it on purpose (a baseline needs a
stable recorded path).
- Neither `-n` nor `-p` does anything without one of the cache flags.
- **A standalone file's dependencies are looked for, not given.** Some facts live in another
image: a type behind a metadata accessor (an availability-conditional `some View`), a
cross-module type's layout, an Objective-C superclass (`override`, explicit selectors). By
default the tool infers paths from where the binary sits and falls back to the running
system's cache — which never offers an image of another platform. So an iOS binary read on a
macOS host needs `--dependency-search-path` (`dump`, `interface`, `snapshot`; repeatable)
naming its runtime: a Mach-O file, a cache file (`dyld_shared_cache_*` /
`dyld_sim_shared_cache_*`), or a directory used as a system root such as a simulator
runtime's `RuntimeRoot`. Named paths are consulted before the running system's cache. An
image read out of a cache (`--dyld-shared-cache`) needs none: it resolves in that same cache
first, so an archived macOS 15 cache is laid out against its own Foundation, not the host's.
When those facts are missing from an iOS binary's output, suspect this flag before the binary.
## 3. Never redirect `interface`'s stdout — pass `-o`
`interface` writes its progress lines to **stdout**, mixed into the product:
```
$ swift-section interface -a arm64e /bin/ls > out.txt # WRONG
$ head -3 out.txt
Preparing to build Swift interface...
[INFO] Extracted 0 symbol index
[INFO] Types: 0 successful, 0 failed, ...
```
Use `--output-path` / `-o` for anything that will be read back, diffed, or committed. The same
holds for `dump`, whose per-declaration error lines also land on stdout — a `dump` redirect
silently mixes `Error: …` lines into the product.
`diff` / `snapshot` / `evolution` are the well-behaved ones: progress and degradation
diagnostics go to stderr, the report to stdout, so `>` is safe there. Their stderr chatter
(dropped declarations, unresolved dependencies) is **normal reporting, not failure** — judge
those runs by the exit code.
## 4. `dump` and `interface` do not share flag spellings
The single most common mistake. Same underlying comment, different name:
| Comment | `dump` | `interface` |
|---|---|---|
| Field offsets | `--emit-field-offsets` | `--emit-offset-comments` (field **and** PWT offsets) |
| PWT addresses | `--emit-pwt-addresses` | folded into the above |
Spelled the same on both: `--emit-type-layout`, `--emit-enum-layout`, `--emit-member-addresses`,
`--emit-vtable-offsets`, `--emit-expanded-field-offsets` (implies the field-offset flag),
`--emit-header`, `--emit-export-status`, `--emit-private-source-files`, `--color-scheme`,
`--output-path`, `--dependency-search-path` (§2).
`--emit-private-source-files` puts a comment above each declaration whose name carries a
private discriminator, naming the source file the discriminator was derived from:
`// CodingKeys is declared in Codable.swift` above `enum Outer.(CodingKeys in _B89E…)`. The file
is recovered by hashing candidate file names, so a named file is certain, but not every one is
found; the rest read `… could not be recovered (private discriminator _…)`. `interface` prints
no discriminator anywhere else, so there this comment is what tells two same-named private types
from different files apart. A member or nested type of a private type repeats nothing, since it
is declared in that type's file. A private member of a public type names its own file, usually
the file of the extension that declares it.
SE-0491 module selectors — `Swift::Int` instead of `Swift.Int`, the spelling a Swift 6.4
`.swiftinterface` uses, with every nested level naming the module that declared it
(`Swift::Duration.Foundation::TimeFormatStyle`) — are off by default and spelled differently
too: `interface --module-selectors`, `dump --enable-module-selectors` (one of the demangler
switches below).
Only `dump` has: `--sections`, `--preferred-binary-order`, and the demangler option group
(`--demangle-options default|simplified|interface` plus ~22 `--enable-…` / `--disable-…`
switches).
Only `interface` has: `--exported-only`, `--sort-members-by-offset`,
`--parse-opaque-return-type`, `--show-c-imported-types`, `--resolve-c-module-names`,
`--supplementary-apinotes`, `--infer-objc-overrides`, `--requirements-on-associated-types`.
`--requirements-on-associated-types` changes where a protocol's requirements print, never which:
`associatedtype Body: SwiftUI.View` instead of `protocol View where Self.Body: SwiftUI.View`,
the way the compiler writes a `.swiftinterface`. The binary keeps only the canonical
requirement signature, so neither form says where the source wrote a requirement. One about
an associated type of a refined protocol (`Self.Element` of a `Sequence` refinement) stays in
the protocol's `where` clause either way, and `diff` / `evolution` always print that form.
`--infer-objc-overrides` is off by default for a reason. An override whose body the optimizer
inlined into its thunk (`viewDidHide`, `encodeWithCoder:` in an OS framework) ties to no Swift
symbol; the flag attributes it anyway, to the one member whose name is the importer's spelling
of the selector. `dump` always shows such ties, marked `(selector name, no symbol evidence)`;
an interface has nowhere to say a keyword rests on a name, so it adds `override` only when
asked.
### `--sections` has two traps
```bash
swift-section dump --sections types,protocols /path/to/binary # ERROR: comma is not a separator
swift-section dump --sections types protocols /path/to/binary # ERROR: the path is eaten as a section
swift-section dump /path/to/binary --sections types protocols # correct — path first
swift-section dump --sections types protocols -- /path/to/binary # correct — `--` ends the list
```
It consumes values up to the next option, so the positional file path must not follow it.
Both wrong forms above are the ones a comma-separated habit produces, and neither fails in an
obvious way if you are skimming — read the error text. The habit is easy to pick up in this
very executable: `swift-section objc dump --sections` **is** comma-separated
(`--sections classes,protocols`).
Also: **with no `--sections`, a section that is missing or unreadable is skipped silently** —
a binary with no Swift content produces zero output and exit status 0. Pass the section
explicitly to get the diagnosis (`Swift section __swift5_assocty not found …`). So "empty
output" never by itself means "no Swift in there"; confirm with an explicit `--sections`.
## 5. `interface` is expensive; `dump` is not
`interface` builds the whole image's demangled symbol index before printing anything. On a
large system framework (SwiftUI, SwiftUICore) that is tens of seconds to minutes and a lot of
resident memory. Budget for it:
- Explore with `dump` (optionally `--sections types`) first; run `interface` once you know the
target is there.
- Never run `interface` over a whole dyld shared cache image set casually.
- `diff` and `evolution` index **every** input, so cost multiplies by the number of versions.
`--jobs N` bounds how many index at once (default: processor count); each in-flight input
holds its indexed image in memory, so lower it when memory is the constraint, not `1` for
speed's sake.
- `--emit-private-source-files` searches every discriminator of the image once before the
first declaration prints, and on `dump` it first indexes the image too, which `dump` otherwise
never does. Measured on macOS 27.2 with a release build: SwiftUI's `dump` goes from 12 s to
58 s and its `interface` from 20 s to 61 s; Foundation's `interface` barely moves.
- Anything long-running belongs in a background run written to a file with `-o`, not in a
foreground command that will be waited on.
## 6. Comment templates
The five layout comment kinds (field offset, vtable offset, member address, type layout, enum
layout) render from `${token}` templates, and `dump` / `interface` accept the template options
directly.
```bash
swift-section transformer templates --module field-offset # names accepted by the options
swift-section transformer tokens --module enum-layout # placeholders those templates take
```
- A value containing `${` is a literal template; anything else must **name** a built-in
template (matched case / space / hyphen / underscore insensitively). A name that matches
nothing is a hard error, never a silently constant comment.
- Passing any template option turns on the comment kind it formats — no separate `--emit-…`
needed. The reverse does not hold.
- `--enum-layout-style` is a whole-module preset: `detailed` (default) / `explained` (bit
ranges in words) / `standard` / `inline` / `compact`.
- `swift-section transformer config … -o comments.json` freezes a command line for reuse via
`--transformer-config`; it is the same JSON shape RuntimeViewer persists.
## 7. `diff` / `snapshot` / `evolution`
```bash
swift-section diff old/Foo new/Foo # change list + verdict
swift-section diff old/Foo new/Foo --interface --format unified # annotated interface
swift-section snapshot /path/Foo --label 26.0 -o foo-26.0.json # freeze a baseline
swift-section evolution 17.0.json 18.0.json /path/Foo --labels 17.0,18.0,26.0
```
- `--json`, `--summary-only` and `--interface` are mutually exclusive, and `--format` only
applies with `--interface`.
- `--interface` renders from live models, so **every input must be a binary or cache** —
snapshot JSON is rejected there, though it is fine for the change-list / lineage reports.
- `evolution` needs ≥ 2 inputs **in version order, oldest first**; `--labels` is comma-separated
and must have exactly one label per input.
- `evolution --interface --emit-available` adds a genuine `@available(<platform>, introduced: …, obsoleted: …)` line above each declaration whose whole lifecycle one attribute can express. **No attribute is not "no lifecycle"**: a declaration that disappeared and came back, one that was only `modified`, or any involved label that is not a numeric version (the file-name fallback!) gets none — pass numeric `--labels` and read the `// [●○●]` comment, which is always there. The versions are axis points, not exact release versions. The platform is inferred from every input's `LC_BUILD_VERSION` (a simulator counts as its device); an input whose platform `@available` has no name for (DriverKit), or inputs of different platforms, fail with exit code 64 — name it with `--platform` (only valid with `--emit-available`, which is only valid with `--interface`).
- `--fail-on-breaking` makes a breaking change a nonzero exit — that, not the report text, is
the CI signal.
- Compare binaries in **similar strip states**. A symbol-rich build against a stripped one
reports the same protocol requirement as a member swap, because a stripped protocol diffs by
witness-table slot rather than by symbol.
- **A snapshot does not cross format versions.** The JSON carries a `formatVersion`; any other
version is rejected with a typed error, and the fix is to regenerate the baseline with the
current tool. Format 6 (0.21.0 and later) rejects every format-5 baseline: in an image stripped
of its local symbols the newer tool also records the class members that only their method
descriptor names (see §9), which an old baseline would report as added wholesale. Format 7 (0.23.0
and later) rejects every format-6 baseline: a type declared in a function or closure body is recorded
under its own full name now (see §9), and an old baseline would report each one as removed —
a breaking change — and added again.
## 8. `--resolve-c-module-names` (interface, macOS only)
Turns `__C.NSString` into `Foundation.NSString`. Needs macOS 13+ and an Xcode installation, and
the first run per SDK generates module interfaces through sourcekitd — slow once, cached after.
Attribution against a non-macOS binary is limited (it warns and degrades rather than failing).
`--supplementary-apinotes` only does anything alongside it.
## 9. Reading the output: things that look like bugs and are not
- **`// not exported`** is an export-trie fact, not an access-level claim. A missing entry
means "not statically callable from outside this image", which is not the same as `internal`.
- **`… is declared in Enabled.swift of module SwiftUICore`** above a SwiftUI declaration is not a
wrong module: the discriminator was hashed with the framework's own name, while its
declarations print under their ABI module name (`SwiftUI`). **`could not be recovered`** means
no candidate file name produced the digest; it says nothing about the declaration.
- **A type member printed `static`** may have been `class` in the source: the four
descriptor-less `class` spellings are ABI-identical to `static`, so the printer picks the
spelling that is always legal.
- **`Field offset: unknown (<reason>)`** is the layout engine declining to guess, and the
reason names what it could not resolve. It is distinct from the flag being off (which emits
nothing at all).
- **A generic type printed with unresolved fields** is expected when no arguments were
supplied: an unconstrained `T` has no layout until it is bound. Class-bound parameters and
parameter metatypes do resolve unspecialized.
- **`pwtslot:` records in a protocol diff** are the fallback view used when requirement symbols
are stripped — see the strip-state warning in §7.
- **A class's members print in vtable slot order**, not grouped by kind: for the class's own
members that is the source's declaration order, so an `init` can sit between two methods.
Only the members that own no slot (`final`, `static`, `@objc dynamic`, an ObjC-inherited
`init`) follow, grouped by kind.
- **In an image stripped of its local symbols (AppKit in the OS dyld shared cache), a public
class method may print without `@objc` or `override`.** Its implementation symbol is gone
(a library-evolution image exports only the dispatch thunk `Tj` and method descriptor `Tq`),
so the member is rebuilt from the `Tq` symbol — the name and signature are exact, but the
`@objc` / ObjC-override facts are joined through the implementation's symbol and are
missing. A vtable slot nothing names (an internal member in a stripped image) is
left out; `dump` lists it as `sub_…` or `<unnamed vtable slot>`.
- **`associatedtype Element` without `: ~Copyable` / `: ~Escapable`** does not prove the
associated type is Copyable. The binary does not record that suppression (SE-0503); it is
printed only when an extension of the protocol in the same image proves it
(`extension P where Element: ~Copyable`), which only a primary associated type
(`protocol P<Element>`) can.
- **Enum-layout patterns marked "not resolved offline"** mean only the extra-inhabitant *index*
is derivable statically; the concrete bytes need the live metadata.
- **`@objc(Name)` above a class** is the name the Objective-C runtime knows it by, and matters
even when it equals the Swift name (`@objc(NSScrollPocket) class NSScrollPocket`): without it
the runtime name would be the `_TtC…` mangling. That is also the class name `objc` headers
and `-[Class selector]` comments use. **`@_objcRuntimeName(Name)`** is the same fact on a
class with no Objective-C ancestor, where `@objc` would not be legal Swift (mostly the
standard library) — not a typo.
- **A declaration under a comment like `// Visitor #1 in Holder.countValues()`** is a type
declared in a function or closure body. `interface` keeps it nested in the enclosing type
and prints its bare name wherever it is referenced (nothing outside the body can spell it),
so two methods' `Visitor`s are two declarations that only the comment tells apart; their
conformance extensions carry the compiler's full name
(`extension Visitor #1 in M.Holder.countValues() -> Any: P`), and `dump` declares the type
under that full name. **`(Visitor in $1a2b3c)`** is such a type in a binary stripped of every
record of its function: the `$` number is the address of the anonymous context descriptor
that wraps it — the runtime's own spelling — not a private discriminator.
## 10. Where the details live
The repository is [MachOSwiftSection](https://github.com/MxIris-Reverse-Engineering/MachOSwiftSection).
| Need | Read |
|---|---|
| Worked examples of every subcommand and flag | its `README.md`, section "swift-section CLI Tool" |
| How to read an enum-layout comment | `Documentations/SwiftEnumLayout.md` (`_zh` companion) |
| Writing supplementary `.apinotes` for a private framework | `Documentations/SupplementaryTypeMappings.md` |
| The `objc` subcommands in full, including the snapshot / diff / evolution workflow | `Documentations/ObjCCommandLine.md` (`_zh` companion); the traps are in `references/objc.md` beside this file |
| What each flag does, authoritatively | `swift-section <subcommand> --help` (and `swift-section objc <subcommand> --help`) — generated from the code, so it cannot drift |
Files in this package (2)
- SKILL.md 22 KB
- references/objc.md 5 KB
Versions
The database has no other skills named swift-section-cli.
Database snapshot: 13.11.2026 · package version 976bcd102bfd (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 90inspect-dyld-shared-cache
Inspect, map, extract from, or compare Apple dyld shared caches and subcaches while preserving cache-native identity and addresses. Use when Codex must identify a cache by platform, architecture, UUID, and OS build; inventory images, mappings, slide information, local symbols,… - 100xmake-swift
Use when building Swift projects with xmake — binary/library targets with `.swift` sources, Swift ↔ C++/Objective-C interop (`swift.interop` value), Swift module name configuration, and iOS/macOS builds. - 86swift
Always use when creating and editing Swift files (*.swift) - 90swift-language
Comprehensive modern Swift (6.x) language expertise — concurrency, generics, ownership/performance, macros, API design, error handling, SwiftPM, C/C++/ObjC interop, cross-platform (Linux/Android/embedded/server), and Swift Testing. Use this skill whenever writing, reviewing,… - 90recover-apple-runtime-metadata
Recover and validate Objective-C and Swift runtime structure from Apple binaries and generated analysis output. Use when Codex must inspect classes, categories, protocols, selectors, methods, properties, ivars, mangled Swift names, metadata, conformances, witness tables, generic… - 96swift-protocol-di-testing
基于协议的依赖注入,用于可测试的 Swift 代码 — 使用聚焦协议和 Swift Testing 模拟文件系统、网络和外部 API。