Library configuration

Configuration flags specific to a library are typically provided by annotating the library definition with metadata, although they can be overridden on a per-project basis using defines (see providing flags).

Includes

The API of C libraries, consisting of function signatures and types, is typically made available by including a header file.

Example: including a header file

@:ammer.lib.headers.include("png.h")
class LibPng extends ammer.def.Library<"png"> {
  // ...
}

In this example, the LibPng library is configured to include the png.h header file during compilation using metadata. This corresponds to the C code:

#include "png.h"

There are different styles of includes, see @:ammer.lib.headers.includes.

Link names

The @:ammer.lib.linkName metadata configures the name(s) of the dynamic library that ammer should link against such that native functions are available. This corresponds to the GCC flag -l.

Example: setting the link name

@:ammer.lib.linkName("png")
class LibPng extends ammer.def.Library<"png"> {
  // ...
}

In this example, the LibPng library is configured to link against the png dynamic library. The C compiler will receive the argument -lpng.

Unless configured otherwise, an ammer library uses its identifier as the link name. Some libraries (e.g. "header-only" libraries where the implementation is enabled with a preprocessor define) have no dynamic library to link against: in this case, @:ammer.lib.linkNames([]) can be used to clear the list of link names.

On macOS, "frameworks" are packages of headers and dynamic libraries. The @:ammer.lib.framework metadata can be used to declare that an ammer library uses a particular framework.

Defines

C preprocessor defines can be enabled for a library using the @:ammer.lib.define metadata.

Paths

When resolving header includes and when linking, the compiler needs to know where to look. ammer libraries can be configured with include paths and library paths. These paths correspond to the GCC flags -I and -L, respectively.

Include paths can be configured using the @:ammer.lib.includePath metadata, library paths can be configured using the @:ammer.lib.libraryPath metadata.

Both include paths and library paths are set relative to the file they are declared in.

Example: setting the include path

@:ammer.lib.includePath("../../native")
@:ammer.lib.headers.include("png.h")
class LibPng extends ammer.def.Library<"png"> {
  // ...
}

Assuming the directory hierarchy is as follows:

native/
  png.h
haxe/
  src/
    LibPng.hx

The compiler will look for the png.h header file in the directory native.

Language

By default, ammer generates glue code in the C language. For libraries requiring the use of another language, the language can be changed using the @:ammer.lib.language metadata. Currently supported languages are:

C - C
Cpp - C++
ObjC - Objective-C
ObjCpp - Objective-C++