dylex 3.0.0

A high-performance dyld shared cache and kernelcache extractor for macOS and iOS
Documentation
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
# dylex

[![Crates.io](https://img.shields.io/crates/v/dylex.svg)](https://crates.io/crates/dylex)
[![Documentation](https://docs.rs/dylex/badge.svg)](https://docs.rs/dylex)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Rust](https://img.shields.io/badge/rust-1.85%2B-blue.svg)](https://www.rust-lang.org)

A high-performance dyld shared cache and kernelcache extractor for macOS and iOS, written in Rust.

dylex extracts Mach-O files for static analysis from Apple's dyld shared cache, with symbol table reconstruction, pointer decoding, and LINKEDIT rebuilding. Extraction does not reconstruct a runnable OS loader environment.

## Features

- **Fast Extraction** - Memory-mapped I/O and parallel processing for maximum speed
- **Automatic Cache Discovery** - Finds system caches automatically on macOS
- **Architecture Selection** - Support for 32-bit ARM (armv6, armv7, armv7s, armv7k), arm64, arm64e, and x86_64 caches
- **Symbol Table Reconstruction** - Rebuilds standalone LINKEDIT with proper symbol tables
- **Pointer Rebasing** - Handles slide info v3/v5 for correct pointer values
- **ObjC Metadata Restoration** - Reconstructs coalesced strings and absolute method entries before clearing encoding flags
- **Cache Islands** - Retains referenced sectionless ARM64 stubs and `libobjcMsgSend*` dispatcher code
- **Rosetta Cache Products** - Discovers native, full Rosetta, and reduced `x86Support` trees separately
- **Directory Structure Preservation** - Optionally preserves full framework paths
- **Batch Extraction** - Extract multiple images with filters and parallel processing
- **String Search** - Find a literal string or hex byte sequence in cache images, with an optional image filter, in one architecture or every discovered cache. `extract --search` writes every image that contains the match
- **Kernelcaches** - List, search, locate, and extract fileset kernel collections and legacy prelinked kexts, including IMG4/IM4P, LZFSE, and complzss inputs

See [cache compatibility and validation](docs/cache-compatibility.md) for the tested macOS 27 build, older-format fixtures, source provenance, assumptions, and mode limitations.

## Kernelcaches

Kernelcaches have their own command group, `dylex kernel` (alias `kc`), which
mirrors the dyld commands. Each command takes an optional kernelcache path; on
macOS, omitting it uses the running system's boot kernelcache, verified against
the running kernel's UUID.

```bash
# The running system's boot kernelcache
dylex kernel info
dylex kernel list -A -f sandbox
dylex kernel extract -i com.apple.security.sandbox -o sandbox.macho
dylex kernel extract --all -o ./kernelcache-images
dylex kernel strings -f sandbox Seatbelt
dylex kernel lookup 0xfffffe0007d342aa

# Any kernelcache file: raw Mach-O, IMG4/IM4P, LZFSE, or complzss
cache=/path/to/kernelcache.release.mac16j
dylex kernel extract -i com.apple.kernel -o kernel.macho "$cache"
dylex kernel extract --search Seatbelt -o ./matching-images "$cache"
```

`dylex kernel locate` shows which boot kernelcaches match the running kernel,
and with `--target BUNDLE_ID` also the loaded version of that kext. It reports
the collection, kernel, and target UUIDs separately, keeps rejected candidates
and their reasons, and searches bounded fallback locations only when the
KernelManagement selection does not verify. `--paths-only` prints just the
verified paths for scripts.

Extraction preserves unslid code addresses, decodes supported chained pointers,
and builds private symbol/string tables for each image. Outputs are for static
analysis. Nonzero kernel-collection cache levels, unresolved chained binds,
legacy section-based pointer chains, encrypted payloads, and universal/fat files
are unsupported. Merge and dependency modes apply to dyld caches only. See
[kernelcache formats, library API, assumptions, and validation](docs/kernelcache.md).

## Installation

### From crates.io

```bash
cargo install dylex
```

### From Source

```bash
git clone https://github.com/19h/dylex
cd dylex
cargo install --path .
```

### GitHub Actions binaries

The [macOS build workflow](.github/workflows/build-macos.yml) tests and builds
Intel (`x86_64`) and Apple Silicon (`arm64`) binaries on pushes, pull requests,
and manual runs. Download `dylex-x86_64-apple-darwin` or
`dylex-aarch64-apple-darwin` from the run's artifacts. Each contains a `.tar.gz`
with the executable and license, plus a SHA-256 checksum file.

See [CI build details](docs/ci.md) for runner selection and validation scope.

## Quick Start

```bash
# List available architectures in the system cache
dylex arches

# Show cache information
dylex info -a arm64e

# List all images containing "UIKit"
dylex list -a arm64e -f UIKit

# Locate a file across every cache, including DriverKit and staged updates
dylex find libobjc.A.dylib --exact

# Find images that contain a literal string
dylex strings -a arm64e -f IOHID com.apple.hid.manager.user-access-device

# Find images that contain a hex byte sequence
dylex strings -a arm64e -x '63 6f 6d 2e 61 70 70 6c 65'

# Search every image in every discovered architecture cache
dylex strings --all-arches com.apple.hid.manager.user-access-device

# Extract a single library
dylex extract -a arm64e -i libobjc.A.dylib -o libobjc.A.dylib

# Extract all MapKit-related frameworks with preserved paths
dylex extract -a arm64e -f MapKit -o ./extracted

# Extract every image that contains a literal string
dylex extract -a arm64e --search com.apple.hid.manager.user-access-device -o ./hid

# Extract every image that contains a hex byte sequence
dylex extract -a arm64e --hex --search '63 6f 6d 2e 61 70 70 6c 65' -o ./hid
```

For an exact x86_64 cache, pass its path as the positional `[CACHE]` argument.
`-a/--arch` accepts architecture names such as `x86_64`:

```bash
# Select the reduced Rosetta x86Support cache
cache=/System/Volumes/Preboot/Cryptexes/Rosetta/System/x86Support/System/Library/dyld/dyld_shared_cache_x86_64
dylex list "$cache" -f dyld
dylex extract "$cache" -f dyld -o ./x86_64-dyld

# Extract every image in that cache
dylex extract "$cache" -f '' -o ./x86_64-all
```

To select the full Rosetta cache, use
`/System/Volumes/Preboot/Cryptexes/Rosetta/System/Library/dyld/dyld_shared_cache_x86_64`
instead. When both caches are discovered, `-a x86_64` alone is ambiguous.

## Commands

### `dylex extract`

Extract images from the dyld shared cache.

```
Usage: dylex extract [OPTIONS] [CACHE]

Arguments:
  [CACHE]  Path to the dyld shared cache (file or directory).
           If not specified, searches default system locations.

Options:
  -i, --image <IMAGE>           Image to extract (e.g., "UIKit" or full path)
  -f, --filter <FILTER>         Filter images by substring match
      --search <STRING>         Extract every image that contains this string or hex bytes
  -x, --hex                     Interpret --search as hex bytes
      --ignore-case             ASCII case-insensitive --search
  -a, --arch <ARCH>             Architecture (arm64e, arm64, x86_64)
  -o, --output <OUTPUT>         Output path (file or directory)
      --merge-image <IMAGE>    Merge a selected additional image (repeatable)
      --merge-runtime          Merge directly referenced runtime libraries
      --merge-plan             Preview merge selection and reference evidence
      --merge-deps             Experimental automatic dependency merge
      --merge-depth <N>        Depth for --merge-deps [default: 1]
      --preserve-paths <BOOL>   Preserve directory structure [default: auto]
  -v, --verbosity <LEVEL>       Verbosity (0=quiet, 1=warn, 2=info, 3=debug)
  -j, --jobs <N>                Parallel jobs (default: CPU count)
  -h, --help                    Print help
```

#### Examples

```bash
# Extract single image to specific file
dylex extract -a arm64e -i libobjc.A.dylib -o /tmp/libobjc.dylib

# Extract by full path
dylex extract -a arm64e -i /System/Library/Frameworks/UIKit.framework/UIKit

# Extract all Foundation-related images
dylex extract -a arm64e -f Foundation -o ./foundation_libs

# Extract every image whose bytes contain the string.
# --filter limits which images are searched. Output is always a directory.
dylex extract -a arm64e --search com.apple.hid.manager.user-access-device -o ./hid
dylex extract -a arm64e -f IOHID --search user-access-device --ignore-case -o ./hid
dylex extract -a arm64e --hex --search '63 6f 6d 2e 61 70 70 6c 65' -o ./hid

# Extract everything (warning: large!)
dylex extract -a arm64e -f "" -o ./all_binaries

# Extract with verbose output
dylex extract -a arm64e -i CoreFoundation -v 2

# Use custom cache path
dylex extract -a arm64e -i libobjc.A.dylib /path/to/dyld_shared_cache_arm64e
```

### Merge referenced runtime libraries

```bash
# Inspect which runtime images are referenced and where
dylex extract -i GeoServicesCore --merge-runtime --merge-plan

# Merge the inferred runtime set
dylex extract -i GeoServicesCore --merge-runtime

# Add an explicit framework to the roots used for runtime inference
dylex extract -i GeoServicesCore --merge-runtime --merge-image GeoServices
```

`--merge-runtime` selects directly referenced libraries in `/usr/lib/system/`,
Objective-C, libc++, libc++abi, libSystem, and `/usr/lib/swift/libswift*.dylib`.
It scans ARM64 direct branches and declared pointer sections, resolves recognized
stubs, and reports reference counts with an example source/target chain for each
inferred image. The primary and explicit additions are scan roots. Inferred
libraries are not scanned recursively; dependency lists do not drive selection.
Frameworks and other libraries remain explicit additions.

`--merge-plan` writes no output. Computed calls without static pointer evidence
are unknown; x86 inference uses pointer sections rather than instruction decoding.
On the tested cache, GeoServicesCore selects ten runtime libraries. Empty section
markers left by cache optimization are omitted unless a symbol references them.
All populated sections are retained regardless of count. Because nlist `n_sect`
is 8 bits, a symbol in a section past ordinal 255 carries the ordinal of an
earlier section of the same kind; its address stays exact. Adding GeoServices
as a root infers 29 runtime images and merges 31 images into 724 sections.

### Merge selected images

Use `--merge-image` once per additional image. This selects the primary image
and the listed images without traversing their dependency lists:

```bash
dylex extract -i GeoServicesCore \
  --merge-image libdispatch.dylib \
  --merge-image libobjc.A.dylib \
  -o GeoServicesCore.selected
```

Image selection prefers a full path, then an exact basename, then a unique
substring. Ambiguous names produce an error listing candidate paths. Repeated
images are included once, and the command prints the canonical selection.
`--merge-image` and `--merge-runtime` cannot be combined with `--merge-deps`, `--merge-depth`,
`--with-deps`, or `--filter`.

The output keeps source virtual addresses and instruction bytes. It combines
sections, symbols, indirect-symbol tables, and function-start labels; referenced
cache trampolines/dispatchers and Objective-C metadata are restored for the
combined image. Those support regions can make output substantially larger than
the selected images' own segments. External targets outside the selection can
remain unmapped. These outputs are for static analysis; runtime loading is not
supported. Open the newly extracted file in a fresh IDA database.

See [selected-merge validation](docs/selected-merge.md) for tested behavior and
format limits. The automatic `--merge-deps` mode retains its older experimental
relocation pipeline.

### `dylex list`

List images in the cache.

```
Usage: dylex list [OPTIONS] [CACHE]

Options:
  -a, --arch <ARCH>       Architecture to use
  -f, --filter <FILTER>   Filter images by name
  -A, --addresses         Show virtual addresses
  -b, --basenames         Show only basenames (not full paths)
  -h, --help              Print help
```

#### Examples

```bash
# List all images
dylex list -a arm64e

# List with addresses
dylex list -a arm64e -A

# Filter and show basenames
dylex list -a arm64e -f Swift -b

# Count images matching filter
dylex list -a arm64e -f Framework | wc -l
```

### `dylex strings`

Search file-backed bytes of cache images for a literal string. `--hex` reads
the needle as bytes instead: `deadbeef`, `de ad be ef`, `0xde:ad`, and
`\xde\xad` are the same four bytes. Quote a needle that contains spaces.
Omit `--filter` to search every image. `--arch` selects one architecture and
can be repeated.
`--all-arches` searches every discovered cache, including both Rosetta products.
With no architecture flag and no cache path, the command uses the same native
cache default as the other commands.

A segment range mapped by more than one image is skipped. On current caches
that range is the shared `__LINKEDIT`. Objective-C strings coalesced into a
single image are reported on that image.

Each match is one line:

```text
arm64e  /System/Library/Extensions/IOHIDFamily.kext/IOHIDFamily  __TEXT,__cstring  0x180abc000  com.apple.hid.manager.user-access-device
```

When more than one cache is searched, the cache file name is included after the
architecture. The address is the start of the enclosing C string when the match
is an ASCII printable run ending in NUL. A summary is written to stderr.

```
Usage: dylex strings [OPTIONS] <NEEDLE> [CACHE]

Arguments:
  <NEEDLE>  Literal string to find, or hex bytes with --hex
  [CACHE]   Path to the dyld shared cache (file or directory)

Options:
  -x, --hex               Interpret the needle as hex bytes
  -f, --filter <FILTER>   Only search images whose path contains this substring
  -a, --arch <ARCH>       Architecture to search, repeatable
      --all-arches        Search every discovered architecture cache
  -i, --ignore-case       Compare ASCII letters without regard to case
  -j, --jobs <N>          Parallel jobs (default: number of CPUs)
  -h, --help              Print help
```

#### Examples

```bash
# One architecture, every image
dylex strings -a arm64e com.apple.hid.manager.user-access-device

# Only images whose path contains IOHID
dylex strings -a arm64e -f IOHID com.apple.hid.manager.user-access-device

# Every discovered architecture cache
dylex strings --all-arches com.apple.hid.manager.user-access-device

# Hex bytes. Spaces, colons, dashes, and 0x prefixes are optional
dylex strings -a arm64e -x '63 6f 6d 2e 61 70 70 6c 65'
dylex strings -a arm64e --hex 0xdeadbeef

# One exact cache file
dylex strings com.apple.hid.manager.user-access-device /path/to/dyld_shared_cache_arm64e
```

### `dylex info`

Display detailed cache information.

```
Usage: dylex info [OPTIONS] [CACHE]

Options:
  -a, --arch <ARCH>   Architecture to use
  -h, --help          Print help
```

#### Example Output

```
Dyld Shared Cache Information
==============================
Path:         /System/Volumes/Preboot/Cryptexes/OS/System/Library/dyld/dyld_shared_cache_arm64e
Architecture: arm64e
Images:       3554
Mappings:     22
Subcaches:    2
Total size:   5307.38 MB

Mappings:
  [ 0] 0x0000000180000000 - 0x00000001e6660000 (    1.6G) r-x
  [ 1] 0x00000001e6660000 - 0x00000001e8874000 (   34.1M) r-- [slide]
  ...

Subcaches:
  [ 1] dyld_shared_cache_arm64e.01 (2543.53 MB)
  [ 2] dyld_shared_cache_arm64e.02 (196.12 MB)
```

### `dylex arches`

List available cache architectures.

```
Usage: dylex arches [PATH]

Arguments:
  [PATH]  Directory to search. If not specified, uses system default.
```

#### Example Output

```
Available architectures in /System/Volumes/Preboot/Cryptexes/OS/System/Library/dyld:
  arm64e - dyld_shared_cache_arm64e
  x86_64 - dyld_shared_cache_x86_64
```

### `dylex lookup`

Find which image contains a specific unslid cache address. Cache-owned ARM64
stub islands are followed to their target image (up to 64 hops, with cycle
detection). Output includes the image path, segment, exact symbol or nearest
preceding symbol, an extraction command using the same cache, and a
`--merge-image` option. A nearest symbol does not establish function extent.

For the cache used in this validation:

```text
0x2480895f0 → 0x1806cf570 → /usr/lib/system/libdispatch.dylib
Symbol: _dispatch_once

0x2480896b0 → 0x180410d48 → /usr/lib/libobjc.A.dylib
Symbol: _objc_retainAutoreleaseReturnValue
```

Addresses vary between cache builds.

```
Usage: dylex lookup [OPTIONS] <ADDRESS> [CACHE]

Arguments:
  <ADDRESS>   Address to lookup (hex, e.g., 0x180000000)

Options:
  -a, --arch <ARCH>   Architecture to use
  -h, --help          Print help
```

## Find files across caches

`find` searches image paths in every cache from all default locations, including
OS, DriverKit, Incoming updates, and both Rosetta products. It does not apply the
single-cache preference used by `info`, `list`, and `extract`. Each output row
contains the architecture, main cache path, and image path, separated by tabs.

```bash
# Exact filename across all caches
dylex find libobjc.A.dylib --exact

# Image path substring; optional architecture filter and ASCII case folding
dylex find UIKit -a arm -i

# Exact full image path, limited to a supplied cache directory
dylex find /usr/lib/libobjc.A.dylib --exact /path/to/caches

# Search the disk for additional caches, then find the file in all results
dylex find libobjc.A.dylib --exact --scan-disk

# Limit the recursive scan to selected directories; --scan-disk is implied
dylex find libobjc.A.dylib --exact --scan-root /Volumes/Research --scan-root ~/Downloads

# Discover additional caches without searching their image tables
dylex arches --scan-disk
dylex arches --scan-root /Volumes/Research
```

By default, queries are case-sensitive substrings of the complete image path.
`--exact` matches the basename when the query contains no `/`, and the full image
path otherwise. Repeat `-a` to include multiple architecture filters. No matches
returns success; an empty query or no eligible caches returns an error. If a cache
cannot be opened, other caches are still searched and the command exits with an
error identifying the incomplete search.

Disk scanning is opt-in and adds to the normal cache locations (or positional
cache file/directory). `--scan-disk` scans recursively from `/`; repeatable
`--scan-root` replaces that disk-scan root and can also be used alone. Unlike the
normal discovery depth limit, disk scans have no depth limit. They skip symlinks,
recognize main cache filenames and magic, exclude numbered subcaches and symbol
files, and deduplicate overlapping roots and filesystem aliases. Unreadable
directories/entries are skipped with an incompleteness count. Disk-wide scans can
take time and visit mounted volumes; use `--scan-root` to constrain traversal.
Discovery validates cache magic; `find` additionally opens each cache and reads
its image table. It searches files represented by cache images, rather than
arbitrary non-image files on disk.

## Default Cache Locations

When no cache path is specified, dylex searches these locations in order:

1. `/System/Volumes/Preboot/Cryptexes` (OS, DriverKit, staged updates, and Rosetta products)
2. `/System/Volumes/Preboot/Cryptexes/OS/System/Library/dyld`
3. `/System/Volumes/Preboot/Cryptexes/OS/System/DriverKit/System/Library/dyld`
4. `/System/Volumes/Preboot/Cryptexes/Incoming/OS/System/Library/dyld`
5. `/System/Volumes/Preboot/Cryptexes/Incoming/OS/System/DriverKit/System/Library/dyld`
6. `/System/Library/dyld`
7. `/var/db/dyld`

Commands without `--arch` retain the native system-cache default. `dylex arches`
lists each product separately. `dylex strings --all-arches` searches every
discovered product. Single-cache selection, including `--arch arm`, prefers
matching primary caches over `Incoming` and DriverKit products. An explicit
cache file or directory selects those products directly. When `--arch x86`
matches both Rosetta caches, an
exact main-file path selects the product:

```bash
dylex info /System/Volumes/Preboot/Cryptexes/Rosetta/System/Library/dyld/dyld_shared_cache_x86_64
dylex info /System/Volumes/Preboot/Cryptexes/Rosetta/System/x86Support/System/Library/dyld/dyld_shared_cache_x86_64
```

These Rosetta paths were observed on macOS 27 build `26A5425a`. Discovery also
includes staged `Incoming` updates and DriverKit subtrees. If multiple products
remain after applying the preference, select the exact main cache file using
positional `[CACHE]`.

## 32-bit ARM caches

Legacy little-endian ARM caches use `MH_MAGIC` (`0xfeedface`), a 28-byte
header, `LC_SEGMENT`, 68-byte sections, 12-byte symbol entries, and 4-byte
pointers. Dylex preserves this ABI throughout extraction, including Thumb
symbol descriptors and pointer state bits. It supports slide formats v1
(bitmap), v2 (32-bit chains), and v4 (chains with small integer entries),
cache-local symbols, indirect symbol tables, ARM lazy stubs, and Objective-C
classes, categories, protocols, methods, ivars, properties, and selectors.
Pointer fields absent from a slide chain retain their original absolute values.

Pass the cache path positionally; no architecture override is necessary:

```bash
cargo build --release
cache=/path/to/dyld_shared_cache_armv7s
./target/release/dylex extract "$cache" -f dylib -o ./armv7s-dylibs
./target/release/dylex extract "$cache" -f '' -o ./armv7s-all
./target/release/dylex extract "$cache" -i /usr/lib/libobjc.A.dylib \
    --merge-image /usr/lib/libSystem.B.dylib -o ./objc-system.dylib
```

Selected-image and dependency merges retain original ARM/Thumb code addresses.
Install-name aliases sharing an image address are merged once. Runtime inference
uses declared 4-byte pointer sections, recognized ARM stubs, and direct ARM/Thumb
branches where mapped or cache-local symbols establish instruction mode.
Instruction regions with unknown mode and register-only targets remain unknown. As with other
architectures, outputs are for static analysis; loading them on an iOS device
is not a validation criterion.

`MachOContext` exposes widened segment, section, symbol, and header fields in
its existing Rust types. Use `header_size()`, `pointer_size()`, `nlist_size()`,
`write_segment()`, `write_section()`, and `sync_header()` rather than serializing
those widened structures directly into a 32-bit image.

Validation includes synthetic armv6/armv7/armv7s/armv7k fixtures, slide v1/v2/v4,
Objective-C graphs, cache-local symbols, aliases, dependencies, runtime inference,
and both merge paths. A separate standard-library Python verifier checks an
archived ARM32 v2 cache and its extraction directory without using Dylex's parser:

```bash
cargo test --all-targets
python3 scripts/verify_arm32_cache.py "$cache" ./armv7s-all --report verification.json
```

The verifier checks every image path, code byte preservation, complete and
partial slide words, symbol and indirect-symbol bounds, dyld-info extents, and
Objective-C class/method/selector references. It currently targets monolithic
ARM32 v2 caches; synthetic Rust tests cover v1 and v4.

Format references: Apple's [Mach-O loader definitions](https://github.com/apple-oss-distributions/cctools/blob/main/include/mach-o/loader.h),
[slide format definitions](https://github.com/apple-oss-distributions/dyld/blob/main/include/mach-o/dyld_cache_format.h),
[ARM stub/Thumb branch optimizer](https://github.com/apple-oss-distributions/dyld/blob/dyld-433.5/interlinked-dylibs/OptimizerBranches.cpp),
and [Objective-C runtime layouts](https://github.com/apple-oss-distributions/objc4/blob/objc4-706/runtime/objc-runtime-new.h).

## Architecture Selection

The `--arch` flag uses substring matching:

| Flag | Matches |
|------|---------|
| `-a arm64e` | `arm64e` only |
| `-a arm64` | `arm64` and `arm64e` |
| `-a x86` | `x86_64` and `x86_64h` |

If multiple architectures match, you'll be prompted to be more specific.

## Output Structure

### Single Image Extraction

By default, single images are extracted to the current directory with their basename:

```bash
dylex extract -a arm64e -i libobjc.A.dylib
# Creates: ./libobjc.A.dylib
```

### Batch Extraction with Filter

When using `-f/--filter`, directory structure is preserved by default:

```bash
dylex extract -a arm64e -f MapKit -o ./extracted

# Creates:
# ./extracted/System/Library/Frameworks/MapKit.framework/Versions/A/MapKit
# ./extracted/System/Library/Frameworks/_MapKit_SwiftUI.framework/Versions/A/_MapKit_SwiftUI
# ./extracted/usr/lib/swift/libswiftMapKit.dylib
# ...
```

Use `--preserve-paths false` to flatten:

```bash
dylex extract -a arm64e -f MapKit -o ./flat --preserve-paths false

# Creates:
# ./flat/MapKit
# ./flat/_MapKit_SwiftUI
# ./flat/libswiftMapKit.dylib
```

## What dylex Does

When extracting an image, dylex performs these operations:

1. **Copies Segment Data** - Extracts __TEXT, __DATA, __LINKEDIT, etc.
2. **Rebases Pointers** - Applies slide info to fix pointer values
3. **Rebuilds LINKEDIT** - Creates standalone symbol table, string table, and other metadata (replaces ~600MB shared LINKEDIT)
4. **Fixes ObjC Metadata** - Clears `OBJC_IMAGE_OPTIMIZED_BY_DYLD` flag
5. **Updates Load Commands** - Adjusts offsets for standalone operation
6. **Optimizes File Layout** - Removes unnecessary padding

## Library Usage

dylex can be used as a library:

```rust
use dylex::{DyldContext, extract_image_with_options, ExtractionOptions};

fn main() -> anyhow::Result<()> {
    // Open the cache
    let cache = DyldContext::open("/path/to/dyld_shared_cache_arm64e")?;
    
    // List images
    for image in cache.iter_images() {
        println!("{}: {:#x}", image.path, image.address);
    }
    
    // Extract an image
    let options = ExtractionOptions::default();
    extract_image_with_options(
        &cache,
        "/usr/lib/libobjc.A.dylib",
        "libobjc.A.dylib",
        options,
    )?;
    
    Ok(())
}
```

## Performance

dylex is designed for speed:

- **Memory-mapped I/O** - No unnecessary copying
- **Parallel extraction** - Uses all CPU cores for batch operations
- **Efficient data structures** - FxHashMap for fast lookups
- **LTO-optimized release builds** - Maximum binary performance

Typical extraction times on Apple M1:
- Single library: ~0.3s
- 100 libraries: ~5s
- Full cache (~3500 images): ~3-5 minutes

## Limitations

- **macOS/iOS only** - dyld caches are Apple-specific
- **Read-only** - Cannot modify or repack caches
- **No code signing** - Extracted binaries need re-signing for execution
- **External references** - Ordinary inter-library targets can remain external
- **Analysis layout** - Images with insufficient header padding use a separate `__DYLEX_HDR` segment; original code addresses remain unchanged
- **Unknown extensions** - Version-4 ObjC optimization fields after the common prefix are not interpreted as version-2 buffer sizes
- **Merged extraction** - `--merge-image` supports explicit selection at cache addresses, with at most 255 retained symbol sections after removing unused empty markers. `--merge-deps` retains its separate experimental relocation pipeline

## Comparison with Other Tools

| Feature | dylex | dsc_extractor | DyldExtractor |
|---------|-------|---------------|---------------|
| Language | Rust | C++ | Python |
| Speed | Fast | Medium | Slow |
| LINKEDIT rebuild | Yes | Partial | Yes |
| Slide info v5 | Yes | Yes | Yes |
| Parallel extraction | Yes | No | No |
| Library API | Yes | No | Yes |

## Troubleshooting

### "No dyld shared caches found"

The default cache locations may not exist on your system. Specify the path explicitly:

```bash
dylex info /path/to/cache/directory
```

### "Multiple caches match"

If different architectures match, use a more specific architecture:

```bash
# Instead of -a arm64 (matches arm64 and arm64e)
dylex info -a arm64e
```

If both caches have the same architecture (e.g., the full and reduced Rosetta
products), select the exact cache with its positional path:

```bash
dylex info /System/Volumes/Preboot/Cryptexes/Rosetta/System/Library/dyld/dyld_shared_cache_x86_64
```

### Cache path passed to `-a/--arch`

Move the cache path out of the architecture option:

```bash
dylex list /path/to/dyld_shared_cache_x86_64 -f dyld
dylex extract /path/to/dyld_shared_cache_x86_64 -f dyld -o ./x86_64-dyld
```

### Extracted binary won't run

Extraction produces files for static analysis. Code signing alone does not restore
bind/rebase metadata, cache-wide runtime state, or unresolved external references.

### Large extracted file sizes

Some libraries (like libobjc) include large shared ObjC metadata segments. This is expected behavior.

## Contributing

Contributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.

## License

MIT License - see [LICENSE](LICENSE) for details.

## Acknowledgments

- Inspired by [DyldExtractor]https://github.com/arandomdev/DyldExtractor
- Apple's dyld source code for format documentation
- The reverse engineering community