What Is the Difference Between Source Code and a Binary Interface?
From the earlier reference collection. Read the current software blog.
Source declarations guide compilation, while a binary interface governs how compiled components exchange calls, symbols, and data at runtime.
Source code describes intent to the compiler
A source-level declaration tells a compiler or other tool how a program expects to use a function or type. In a C header, a declaration might say that a function named read_value accepts a pointer and returns an integer. The compiler checks calls against that declaration while translating source code.
This is valuable, but the declaration itself is not the runtime connection. The compiled program must still find a symbol with the expected name, pass arguments in a compatible way, and interpret the return value consistently.
The binary interface is the runtime contract
A binary interface, often called an ABI, covers details used by compiled components: symbol names, calling conventions, register or stack usage, data layout, alignment, and rules for returning values. These details let separately compiled code work together without sharing the original source files.
Imagine a library changes a structure by inserting a field in the middle. A client compiled against the old layout may read the wrong offset if it loads the new library without recompilation. The source-level name of the structure could remain unchanged while the binary expectations no longer match.
Compatibility depends on several details
A library can preserve source compatibility while breaking binary compatibility. For example, it might keep the same public function signature but change how the function is exported or how a type is laid out. Conversely, a binary interface might remain stable even if the source implementation is reorganized internally.
Platform and toolchain conventions matter too. The same source code built for different processor architectures or operating systems will not generally produce interchangeable binaries. Even within one platform, compiler options and language rules can affect layout or symbol handling.
Check both when distributing libraries
When a library is distributed as source, users typically compile it and their application together or against matching declarations. For prebuilt libraries, maintainers need to document supported platforms and ABI expectations, and users need compatible library versions. A package version alone may not reveal every relevant distinction, so release notes should identify intentional interface changes.
When diagnosing a failure, ask separately whether the source declaration matches the intended API and whether the loaded binary implements the ABI expected by the caller. That distinction narrows the search: compile errors point toward source expectations, while unresolved symbols or corrupted arguments can indicate a binary mismatch.