12.5.3 build.xml File Format

The build.xml file format is designed to address the very specific goal of generating compiled output as fast as possible on a wide variety of compilers. Therefore, at its core, it is simply a list of files to compile, and their dependencies, and a list of compiler exes and flags required to get the job done. Conditional variable setting is added to support the great variety of compilers and use cases encountered by hxcpp. However, much of the logic required to orchestrate the compiler sequences, such as precompiling headers, is defined in Haxe and implemented in the build tool itself, rather than being scriptable.

A hxcpp build file consists of a series of commands and data structures in xml format. The commands are executed immediately as they are encountered, while the data structures are accumulated and used after all the build files have been parsed.

Running a build.xml File With Hxcpp

When you compile a Haxe program with hxcpp, the Haxe compiler will normally run the hxcpp build tool on the generated build.xml file automatically. You can, however, prevent this by adding -D no-compilation to the Haxe command line.

You can run the hxcpp build tool on your own build files using

haxelib run hxcpp myfile.xml [-Ddefine] [-Dkey=value]

Note the lack of space between the "-D" and the variable name.

A minimal build.xml file consists of an xml container and a dummy default target, like:

   <echo value="Hello!" />
   <target id="default" />
Conditions, Substitutions and Sections

Most elements in the hxcpp xml file allow a common syntax for dynamic configuration.

Xml elements can contain conditional "if" and/or "unless" values. These conditions are evaluated at parse time and the entire element will be skipped if the condition fails. For example adding this lines:

  <echo value="Hello A" if="A" />
  <echo value="Hello A && B" if="A B" />
  <echo value="Hello A || B" if="A || B" />
  <echo value="Hello !A" unless="A" />
  <echo value="Hello !(A && B)" unless="A B" />
  <echo value="Hello !(A || B)" unless="A || B" />
  <echo value="Never Never" if="A" unless="A" />
  <target id="default" />

and running:

haxelib run hxcpp myfile.xml -DA

shows how the logic depends on whether or not A or B has been defined.

Sections can be used to group commands together based on a common condition. They can also be used to include only part of another xml file, but this technique is currently only used when parsing the .hxcpp_config.xml file. For example:

  <section if="C" >
    <echo value="I See" />
    <echo value="You" />

The xml attribute values can be substituted with variable values using dollars-brace syntax. Using a colon allows a function-call to be substituted, e.g.:

  <echo value="some var = ${SOME_VAR}" />
  <echo value="${haxelib:hxcpp}/include" />