ammer

Implementing new platforms

About type representation

Instances of TypeMarshal (obtained from a Marshal instance) define how any given type is to be passed between Haxe and C. This marshalling is performed in up to three steps in C code (depending on the concrete platform and type), named L1 (closest to Haxe and the concrete Haxe target), L2, and L3 (unified C representation).

• haxeType — the ComplexType used for this type in calls from Haxe.
• mangled — a short representation of the type, used in identifiers and mangled function signatures.
• l1Type, l2Type, l3Type — the C type at each step.
• l1l2, l2l3, l3l2, l2l1 — functions which output the C code that transforms the value from one level to another. For example, l1l2 is given as first argument an expression representing the L1 representation, as second argument an identifier to which the L2 representation will be written, and returns the code that performs e.g. (l2) = transform((l1));. The generated code may span multiple lines and may require multiple method calls interacting with the current platform's FFI mechanism.

Implementing the platform file

To create a new Platform, it is best to follow examples of existing platforms, whose implementations are in the ammer.core.plat package. There is also a None platform which performs no-ops or raises exceptions for all of its operations; it can also serve as a good template file for new platform implementations.

Types such as ammer.core.Platform and ammer.core.PlatformId should also be adapted to make ammer-core aware of the new platform.

When developing the actual implementation, a rough guideline is as follow:

• Start with outputting any C glue code.
• Implement addNamedFunction (with dummy arguments at first).
• Implement types in Marshal, enabling tests one at a time.
  • The simplest test is probably TestBools, requiring only the Bool type marshalling to work.
• Implement the finalise steps to get a dynamic library that actually compiles and links against the target's FFI mechanism.
• Enable and pass the other tests:
  • integers, TestIntegers.hx
  • floats, TestFloats.hx
  • opaques, part of TestStructs.hx
  • structs, rest of TestStructs.hx
  • bytes, TestBytes.hx
  • arrays, Haxe values, callbacks ...
• Platform configuration, polish.