ABI Examples
Each example changes one compatibility condition. Its shell scripts check that the
compatible program builds and runs, and that the incompatible case fails for the
expected reason without producing an executable. Each example has a
build-incompatible.sh script; run it to see the compiler error yourself.
Build Sun first, then run the commands below from the repository root. Bash
and the normal native-link toolchain are required. Sources and per-example sun-config.json files live under examples/abi/;
bundles, executables, and diagnostic logs go in tmp/abi-examples/.
These examples exercise the current experimental compiler. They do not establish compatibility across compiler releases.
| Example | Compatible case | Incompatible case |
|---|---|---|
| Target | Host library and consumer | Library for another architecture |
| Exact dependency | Original v1 declaration | v1.1 with the same layout; v2 with a new layout |
Target compatibility
A library contains code for a particular target. The same tiny scalar call works when the library and consumer target match. Importing the library built for the other architecture must fail with a target diagnostic, before an executable is produced.
Source
{
"root": true,
"sun_path": [
"../../../tmp/abi-examples/target"
],
"path_variables": {
"ABI_BUILD": "../../../tmp/abi-examples/target"
},
"entrypoints": [
{
"path": "library.sun",
"type": "library",
"name": "compatible"
},
{
"path": "main.sun",
"type": "binary",
"name": "compatible-app"
}
]
}/** Must reject a library built for another target. */
function main() i32 {
return sample.answer() - 42;
}
manifest {
libraries: [
"incompatible.moon"
]
}/** Supplies one scalar call across a compiled-library boundary. */
public module sample {
/** Returns the value expected by the consumer. */
public function answer() i32 {
return 42;
}
}/** Exits successfully when the imported scalar call works. */
function main() i32 {
return sample.answer() - 42;
}
manifest {
libraries: [
"compatible.moon"
]
}Run
From the repository root:
bash examples/abi/target/build.sh
bash examples/abi/target/build-incompatible.shThe build script builds library.sun twice: once for the host and once for a foreign
architecture. The consumers have the same call but select different libraries in their manifests. No cross linker is needed:
the foreign artifact is a .moon library and is never executed.
sun-config.json declares the successful build products and their library search
path. build-incompatible.sh intentionally fails and prints the compiler error. To check
both cases automatically, run bash examples/abi/target/test.sh.
Exact dependency identity
shapes_user.moon embeds the Point type and implementation from shapes_v1.sun.
An application can list another shapes revision without replacing that embedded
copy. The build script compiles each revision directly with
--id sun.examples/shapes, using distinct output paths. This identifies the
library but does not make its revisions interchangeable. The script then builds
the configured bridge and consumer, whose IDs come from their entrypoint names.
main_v1.1.sun constructs a v1.1 point containing 43 and passes it to
shapes_user.read, compiled against v1. Their recorded ABI contracts match, so
the borrow is accepted. The reader retains its original declarations and code;
its local() function still constructs a v1 point containing 42.
main_v2.sun attempts the same call with a layout-changing v2 point. Type checking
rejects that argument. Both versions may still be used independently.
Source
{
"root": true,
"sun_path": [
"."
],
"entrypoints": [
{
"path": "shapes_user.sun",
"type": "library",
"name": "shapes_user"
},
{
"path": "main_v1.1.sun",
"type": "binary",
"name": "revised",
"requires": [
"shapes_user"
]
}
]
}/** Passes a revised point to the unchanged compiled shapes user. */
function main() i32 {
var point = shapes.Point();
return shapes_user.read(point) - 43;
}
manifest {
libraries: [
"shapes_v1.1.moon",
"shapes_user.moon"
]
}/** Attempts to pass a different revision's type to the compiled shapes user. */
function main() i32 {
var point = shapes.Point();
return shapes_user.read(point) - 42;
}
manifest {
libraries: [
"shapes_v2.moon",
"shapes_user.moon"
]
}/** Exposes a signature referring to the v1 library's type. */
public module shapes_user {
/** Reads a point from the exact embedded revision. */
public function read(point: ref shapes.Point) i32 {
return point.x;
}
/** Constructs and reads a point using the embedded implementation. */
public function local() i32 {
var point = shapes.Point();
return read(point);
}
}
manifest {
libraries: [
"shapes_v1.moon"
]
}/** Revises the implementation while preserving the library and type contract. */
public module shapes {
/** Stores one integer, just like the v1 type. */
public class Point {
public var x: i32;
/** Uses a different implementation without changing the field layout. */
init() {
this.x = 43;
}
}
}/** Defines the exact nominal type used by the bridge library. */
public module shapes {
/** Stores one integer. */
public class Point {
public var x: i32;
/** Initializes the field. */
init() {
this.x = 42;
}
}
}/** Defines a new Point layout with an additional coordinate. */
public module shapes {
/** Stores two integers instead of v1's single field. */
public class Point {
public var x: i32;
public var y: i32;
/** Initializes both coordinates. */
init() {
this.x = 42;
this.y = 0;
}
}
}Run
From the repository root:
bash examples/abi/identity/build.sh
bash examples/abi/identity/test.shThe scripts build libraries and executables under the example's .sun/build/
directory and use sun describe --config to resolve their paths. test.sh
runs the compatible-borrow example and checks the cross-revision rejection.
Use build-incompatible.sh to inspect the rejected call separately, and
clean.sh to remove generated outputs.
The source blocks above are generated directly from the runnable examples.
Each example has its own sun-config.json declaring its libraries, successful
consumer, and output paths. Expected failures are tested separately.
Run the complete set from the repository root:
bash examples/abi/build.sh
bash examples/abi/test.shThese suite scripts are also discovered by the existing examples CI job.