Sun ABI — Draft
This is a design draft. Current Sun releases do not provide these compatibility guarantees, and existing Moon bundles have no stable ABI revision assigned by this draft.
Start with a program importing a library:
geometry.moon: compiled by an older Sun compiler, provides area(Rectangle)
app: compiled today, calls that functionThe ABI is the agreement that lets the call work: where rectangle fields live,
how the argument is passed, who owns its resources, and how the result returns.
If one side reads a different field offset, the call can return the wrong value
even though both sides use the name Rectangle.
The pages below change one part of this example at a time. Text diagrams are schematic, not executable Sun syntax or chosen machine layouts. For runnable examples, use ABI Examples.
Requirements appear beside their examples. Their levels mean:
| Level | Meaning |
|---|---|
| MUST | Required for conformance with the proposed ABI. |
| MUST NOT | Prohibited by the proposed ABI. |
| SHOULD | Recommended, but not required. |
Try the minimal ABI examples for paired compatible and incompatible cases using the current compiler.
Purpose and scope
The goal is for a newer compiler to import an unchanged library built by an older supported compiler on a compatible target, without rebuilding its compiled code. The consumer may still specialize exported generic bodies. Each bundle has one compatibility contract and hash covering its code and all embedded dependencies. A bundle may also embed complete source inputs so consumers can optionally rebuild it with their own compiler. This is a separate path from importing compiled code.
The draft covers Sun functions, types, globals, callbacks, and compiler runtime services across compiled boundaries. C interoperability follows the platform C ABI; a stable Sun ABI does not make arbitrary C calls safe.
| Scenario | Proposed behavior |
|---|---|
Today’s compiler imports the saved geometry.moon. | Warn and continue when contract checks pass. |
| An older compiler reads a newly built geometry library using only familiar rules. | Accept only if it supports the required formats, semantics, ABI, and capabilities. |
| Geometry is rebuilt after its constructor changes. | Treat it as a distinct artifact; replacement compatibility is not promised. |
| Someone swaps a library without rebuilding the installed application. | Outside the initial guarantee. |
| An x86-64 app tries to import an AArch64 library. | Use a compatible payload, or rebuild from complete source when selected and supported; otherwise reject. |
| The caller selects a rebuild of geometry for its own target. | Build a new artifact and validate its contract; source and build requirements still apply. |
| A future compiler reads a geometry bundle saved today. | Support is limited to published supported revisions. |
Keeping the same geometry bundle while upgrading the compiler tests compiler compatibility. Changing geometry while keeping an already compiled application tests library evolution. The latter needs additional guarantees.
| Subject | Level | Requirement |
|---|---|---|
| Stabilization | MUST | Resolve open decisions and test the specified behavior before declaring an ABI revision stable. |
| Support policy | MUST | Publish which revisions are supported. |
The evolution rules keep unused features and optional metadata out of the compiled compatibility hash. Newer and older compilers can exchange bundles when they support the required rules. Unknown semantics and retired contracts still need rejection or a supported rebuild path.
Topics
- Compatibility Model: Automatic contract checks, compiler-age warnings, and rejection of incompatible artifacts.
- Experimental Implementation: Current compatibility checks, supported profiles, and implementation limitations.
- Declarations & Symbols: Exact artifact identity, nominal types, exported symbols, and specializations.
- Data Layout: Sizes, alignment, field offsets, enums, arrays, and value representations.
- Function Calls: Arguments, returns, hidden parameters, and target calling conventions.
- Ownership & Allocation: Moves, borrows, destruction, allocation, and failure cleanup.
- Interfaces & Closures: Method tables, environments, captures, and indirect invocation.
- Generic Specialization: Serialized bodies, semantic revisions, and concrete type specialization.
- Runtime & Errors: Runtime entry points, unwinding, initialization, and shared state.
- Moon Library Format: The current container, metadata, bitcode, native archives, optional complete source, and proposed format requirements.
- Conformance & Implementation: Implementation baseline, release criteria, compatibility tests, and delivery sequence.
Status
The design keeps compile-time specialization and exact dependency identity. Machine calling conventions and runtime contracts still need specifications. The conformance page defines the work required before a stable revision can be published.