Examples

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.

ExampleCompatible caseIncompatible case
TargetHost library and consumerLibrary for another architecture
Exact dependencyOriginal v1 declarationv1.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

sun-config.json
{
  "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"
    }
  ]
}
incompatible.sun
/** Must reject a library built for another target. */
function main() i32 {
  return sample.answer() - 42;
}
 
manifest {
  libraries: [
    "incompatible.moon"
  ]
}
library.sun
/** 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;
  }
}
main.sun
/** 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.sh

The 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

sun-config.json
{
  "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"
      ]
    }
  ]
}
main_v1.1.sun
/** 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"
  ]
}
main_v2.sun
/** 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"
  ]
}
shapes_user.sun
/** 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"
  ]
}
shapes_v1.1.sun
/** 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;
    }
  }
}
shapes_v1.sun
/** 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;
    }
  }
}
shapes_v2.sun
/** 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.sh

The 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.sh

These suite scripts are also discovered by the existing examples CI job.