Merge pull request #267 from p-x9/feature/archive

Support for unix archive (.a) files

Author: p-x9

Package.resolved

@@ -15,6 +15,10 @@ let package = Package(
             name: "MachOKit",
             targets: ["MachOKit"]
         ),
+        .library(
+            name: "MachOArchiveKit",
+            targets: ["MachOArchiveKit"]
+        ),
         .library(
             name: "MachOKitC",
             targets: ["MachOKitC"]
@@ -29,6 +33,10 @@ let package = Package(
             url: "https://github.com/p-x9/swift-fileio-extra.git",
             from: "0.2.2"
         ),
+        .package(
+            url: "https://github.com/p-x9/ObjectArchiveKit.git",
+            from: "0.3.0"
+        ),
     ],
     targets: [
         .target(
@@ -42,13 +50,20 @@ let package = Package(
                 .enableExperimentalFeature("AccessLevelOnImport", .when(configuration: .debug))
             ]
         ),
+        .target(
+            name: "MachOArchiveKit",
+            dependencies: [
+                "MachOKit",
+                .product(name: "ObjectArchiveKit", package: "ObjectArchiveKit"),
+            ]
+        ),
         .target(
             name: "MachOKitC",
             publicHeadersPath: "include"
         ),
         .testTarget(
             name: "MachOKitTests",
-            dependencies: ["MachOKit"]
+            dependencies: ["MachOKit", "MachOArchiveKit"]
         )
     ]
 )

Package.swift

@@ -0,0 +1,32 @@
+//
+//  ArchiveFile+MachOFile.swift
+//  MachOKit
+//
+//  Created by p-x9 on 2026/03/17
+//  
+//
+
+import MachOKit
+import ObjectArchiveKit
+
+extension ArchiveFile {
+    /// Creates `MachOFile` instances for all Mach-O members contained in the archive.
+    ///
+    /// Non-Mach-O members such as symbol tables are skipped automatically.
+    ///
+    /// - Returns: An array of `MachOFile` instances for members whose payload starts with a Mach-O magic.
+    /// - Throws: Any error thrown while initializing a `MachOFile`.
+    public func machOFiles() throws -> [MachOFile] {
+        try members.compactMap { member in
+            guard let dataOffset = member.dataOffset(in: self) else {
+                throw ObjectArchiveKitError.invalidHeader
+            }
+            return try? MachOFile(
+                url: url,
+                imagePath: member.name(in: self),
+                headerStartOffset: dataOffset + headerStartOffset,
+                headerStartOffsetInCache: 0
+            )
+        }
+    }
+}

Sources/MachOArchiveKit/ArchiveFile+MachOFile.swift

@@ -0,0 +1,30 @@
+//
+//  FatFile+Archive.swift
+//  MachOKit
+//
+//  Created by p-x9 on 2026/03/17
+//  
+//
+
+import MachOKit
+import ObjectArchiveKit
+
+extension FatFile {
+    /// Creates `ArchiveFile` instances for all architectures
+    /// whose slice payload is a Unix `ar` archive.
+    ///
+    /// This is useful for fat static libraries where each architecture
+    /// slice contains a separate archive.
+    ///
+    /// - Returns: An array of `ArchiveFile` instances for archive slices.
+    /// - Throws: Any error thrown while initializing an `ArchiveFile`.
+    public func archiveFiles() throws -> [ArchiveFile] {
+        try arches.compactMap { arch in
+            try ArchiveFile(
+                url: url,
+                headerStartOffset: numericCast(arch.offset),
+                size: Int(arch.size)
+            )
+        }
+    }
+}

Sources/MachOArchiveKit/FatFile+Archive.swift

@@ -0,0 +1,10 @@
+//
+//  exported.swift
+//  MachOKit
+//
+//  Created by p-x9 on 2026/03/17
+//  
+//
+
+@_exported import MachOKit
+@_exported import ObjectArchiveKit

Sources/MachOArchiveKit/Util/exported.swift

@@ -20,7 +20,7 @@ import Foundation
 public class FatFile {
 
     /// The file URL of the fat binary.
-    let url: URL
+    public let url: URL
 
     /// File handle used for reading the binary contents.
     let fileHandle: FileHandle

Sources/MachOKit/FatFile.swift

@@ -106,7 +106,7 @@ public class MachOFile: MachORepresentable {
         )
     }
 
-    private init(
+    package init(
         url: URL,
         imagePath: String?,
         headerStartOffset: Int,
@@ -127,7 +127,11 @@ public class MachOFile: MachORepresentable {
             offset: UInt64(headerStartOffset + headerStartOffsetInCache)
         )
 
-        let isSwapped = header.magic.isSwapped
+        guard let magic = header.magic else {
+            throw MachOKitError.invalidMagic
+        }
+
+        let isSwapped = magic.isSwapped
         if isSwapped {
             swap_mach_header(&header.layout, NXHostByteOrder())
         }

Sources/MachOKit/MachOFile.swift

@@ -0,0 +1,119 @@
+//
+//  ArchiveFilePrintTests.swift
+//  MachOKit
+//
+//  Created by p-x9 on 2026/03/16
+//
+//
+
+import Foundation
+import XCTest
+@testable import MachOKit
+import ObjectArchiveKit
+import MachOArchiveKit
+
+final class ArchiveFileTests: XCTestCase {
+    var fat: FatFile!
+    var archive: ArchiveFile!
+
+    override func setUp() async throws {
+        let developerDirectoryURL = try developerDirectoryURL()
+        let url = developerDirectoryURL
+            .appendingPathComponent("Toolchains/XcodeDefault.xctoolchain/usr/lib/clang/17/lib/darwin/libclang_rt.osx.a")
+        let file = try MachOKit.loadFromFile(url: url)
+        switch file {
+        case let .fat(fat):
+            self.fat = fat
+            let archives = try fat.archiveFiles()
+            self.archive = archives[0]
+        case .machO:
+            XCTFail("Expected archive or fat archive file")
+            return
+        }
+    }
+
+    func testDumpFileStructure() throws {
+        func dump(_ machO: MachOFile, level: Int) {
+            let path = machO.imagePath
+            let name = path.split(separator: "/").last ?? ""
+            print(String(repeating: " ", count: level) + name)
+        }
+
+        func dump(_ fat: FatFile, level: Int) {
+            print(String(repeating: " ", count: level) + "Fat", fat.url.lastPathComponent)
+            do {
+                let machOs = try fat.machOFiles()
+                for machO in machOs {
+                    dump(machO, level: level + 1)
+                }
+            } catch {}
+            do {
+                let archives = try fat.archiveFiles()
+                let archs = fat.arches
+                for (archive, arch) in zip(archives, archs) {
+                    dump(archive, level: level + 1, cpu: arch.cpu)
+                }
+            } catch {}
+        }
+
+        func dump(_ archive: ArchiveFile, level: Int, cpu: CPU) {
+            print(String(repeating: " ", count: level) + "Archive", cpu)
+            do {
+                let machOs = try archive.machOFiles()
+                for machO in machOs.prefix(5) {
+                    dump(machO, level: level + 1)
+                }
+                print(String(repeating: " ", count: level + 1) + "...")
+            } catch {}
+        }
+
+        dump(fat, level: 0)
+    }
+}
+
+extension ArchiveFileTests {
+    func testBSDSymbols() throws {
+        guard let symbolTable = archive.bsdSymbolTable else {
+            return
+        }
+        print("count: \(symbolTable.count)")
+        print("isSorted: \(symbolTable.isSorted(in: archive))")
+        for symbol in try symbolTable.entries(in: archive) {
+            let name = try symbolTable.name(for: symbol, in: archive)
+            print(name ?? "unknown", symbol.stringOffset, symbol.headerOffset)
+        }
+    }
+
+    func testDarwin64Symbols() throws {
+        guard let symbolTable = archive.darwin64SymbolTable else {
+            return
+        }
+        print("count: \(symbolTable.count)")
+        print("isSorted: \(symbolTable.isSorted(in: archive))")
+        for symbol in try symbolTable.entries(in: archive) {
+            let name = try symbolTable.name(for: symbol, in: archive)
+            print(name ?? "unknown", symbol.stringOffset, symbol.headerOffset)
+        }
+    }
+}
+
+extension ArchiveFileTests {
+    private func developerDirectoryURL() throws -> URL {
+        let process = Process()
+        process.executableURL = URL(fileURLWithPath: "/usr/bin/xcode-select")
+        process.arguments = ["-p"]
+
+        let pipe = Pipe()
+        process.standardOutput = pipe
+
+        try process.run()
+        process.waitUntilExit()
+
+        let data = pipe.fileHandleForReading.readDataToEndOfFile()
+        if var path = String(data: data, encoding: .utf8) {
+            path.removeLast()
+            return URL(fileURLWithPath: path)
+        }
+        fatalError("Failed to read Xcode install path")
+    }
+}