Providing flags

A "configuration flag" in this document refers to a string key, such as ammer.buildPath associated to a value of a given type, such as String. Most configuration flags can be set using two ways:

Either by annotating a library definition with metadata; or
by providing a compile-time define when invoking the Haxe compiler.

For configuration flags associated to a particular library (for example: "which header files should be included when compiling this library"), using metadata is the more natural option. The relevant metadata are written in the same file as the definition of the library itself, which means information is not spread across too many places. Nevertheless, defines can be used to override the library behaviour on a per-project basis.

Configuration flags which are not associated to any library can only be provided using defines.

Example: providing flags

@: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. Alternatively, the metadata can be omitted, and the flag provided using a compile-time define:

-D ammer.lib.png.headers.include=png.h

Note the naming convention: in the metadata case, the metadata is attached directly to the LibPng class, so providing the png identifier as part of the metadata name would be redundant. On the other hand, the compile-time define must specify which library it is referring to by using the png identifier as part of the define name.