ammer

Terminology

In the context of Haxe and its use with ammer, terms such as "native" or "library" can be ambiguous. Throughout this document, the terms will have the following meaning:

• native library — Native libraries is typically distributed as .dll (on Windows), .dylib (on macOS), or .so (on Linux). Usually such libraries are written in a system language such as C, and compiled into machine code "native" to a particular architecture or operating system.
  • Examples: libPNG, SDL 2, libuv.
• Haxe library — Haxe libraries are packages containing Haxe code, distributed via haxelib, Github, or other means.
  • Examples: HaxeUI, OpenFL, pecan.
• ammer library — A subset of the previous, ammer libraries are Haxe libraries made using ammer.
• library — One the above. Should only be used when the context makes it clear which one is meant!
• ammer library definition — To create an ammer library, a "definition" is needed, consisting of specially annotated Haxe classes and methods, as described in the Definition section.
• extern — Haxe allows marking classes and other types as externs (see the Externs section in the Haxe manual), which allows non-Haxe code (such as functions written in Javascript) to be used safely from within Haxe code.
• target — The Haxe compiler compiles Haxe code into one of its various targets, such as C#, Javascript, or HashLink. However, this is not precise enough: it is also important to know how the resulting code is compiled and how it will be executed. In this document, "target" refers to such a more precise combination of target language + runtime platform.
  • Examples: Javascript on Node.js, HashLink in HL/C mode.
• FFI — Foreign Function Interface. On targets with an interpreter (such as Node.js/V8) or a virtual machine (such as the JVM) this generally refers to a mechanism that allows code to interact with native libraries.

With the above in mind, ammer is a Haxe library which is used to create ammer libraries. Typically, their function is to make a native library usable from Haxe. The author of an ammer library creates a library definition corresponding to the API of a native library. Although ammer uses externs under the hood (on some targets), this is not directly visible; in other words, ammer library definitions aim to be a more general concept than externs.