Swift build diagnostics

Swift modules come in two forms: a text interface meant for sharing across compiler versions, and a binary blob meant for the exact compiler that produced it. In current Swift tooling, developers say a broken text interface can still force builds onto the binary path instead. (swift.org) (forums.swift.org 1) (forums.swift.org 2) Swift’s own module-stability design says `.swiftinterface` files are used when the compiled `.swiftmodule` is absent or unusable. Swift core contributors have also said `.swiftmodule` files are “not meant to be distributed” and are designed for the exact compiler, SDK details, and dependent modules that created them. (forums.swift.org 1) (forums.swift.org 2) That distinction matters in Apple-platform builds because Xcode’s `BUILD_LIBRARY_FOR_DISTRIBUTION` setting turns on both library evolution and module stability for binary frameworks. Apple’s Swift team says that setup is for frameworks updated separately from their clients, not packages and app-internal code shipped together. (swift.org) When the compiler falls back to a binary `.swiftmodule`, teams can lose the main benefit of the text interface: mixing artifacts across compiler releases. Allan Shortlidge, a Swift compiler engineer, wrote on Swift Forums in February 2025 that `.swiftmodule` files are “incredibly fragile” and “only designed to be read by the exact compiler binary” that produced them. (forums.swift.org) That leaves iOS and macOS dependency managers in a bind. A malformed interface file can turn what should be a portable framework into one that is effectively locked to one toolchain or SDK combination, producing the kind of “cannot load module” errors developers reported in forum threads and GitHub issues. (forums.swift.org) (github.com 1) (github.com 2) The file formats differ for a reason. Jordan Rose, then on the Swift team, said in 2019 that `.swiftinterface` files contain the public surface of a module, while compiled modules still carry extra serialized information used for debugging and non-public details. (forums.swift.org) The same split shows up in newer forum guidance. Slava Pestov wrote in February 2025 that `.swiftmodule` files work better with the debugger because they include private declarations and stored properties, while `.swiftinterface` files omit those implementation details and require library evolution support. (forums.swift.org) For engineers debugging these failures, one low-level check is to ask the compiler for LLVM intermediate representation, the assembly-like form it emits before machine code. The open-source Swift compiler repository documents compiler debugging workflows, and Swift developers commonly use `swiftc -emit-ir` to inspect calling conventions, symbol references, and optimization output around Application Binary Interface and runtime problems. (github.com) (github.com) (forums.swift.org) Swift’s official guidance has not changed on the core point: distribute stable interfaces when binaries must survive compiler changes, and avoid library evolution for code that is always built with the app. The current complaints show how quickly that boundary breaks down when the interface file itself is the part that fails. (swift.org)