12.6.3 Build.xml

The hxcpp build.xml build system is designed to make compiling, cross-compiling and linking easy on a large variety of operating systems and devices. It was originally designed to build the haxe-generated c++ code but has evolved to replace the need for configuration tools in many open source libaries.


The source code for the tool lives in "tools/hxcpp" in this repo. When compiled, it can be run with the haxe 'haxelib' library tool. This is usually done automatically by the haxe compiler after the cpp code has been generated. It can be done maunually like:

haxelib run hxcpp build.xml key=value .... [target]

The hxcpp build tool is configured using key-value pairs, or just using keys, known internally as 'defines'. These can be set in severaly ways: - From system environment variables - From the command-line, with key=value - From haxe. Keys defined in haxe with '-D key[=value]' are passed to the build too, where they can influence the build. Certain defines need to be set on the haxe command line so that they can influence the generated code. - From the the .hxcpp_config.xml file in the users home(profile) directory. This is a good place to set values the apply to the whole machine, like the location of SDKs etc. - The defines can be manipulated logically from within the build files themselves.

See Defines for a list of standard defines.


The compiler specification and target lists all use the same format. - uses xml parser - mostly declarative list of files and flags - order is important

+ overriding values is a valid technique
+ "commands" are run as they are parsed (eg, 'echo')
  • conditions via "if" and "unless" node attributes
  • substitution via '${VAR}' sysntax
  • need to define 'default' target

Most of the xml nodes support 'if' and 'unless' attributes. These will enable or disable the whole node according the existance or non-existance of a define. These can be combined with a space for "and" or two pipes for "or".

Substitution is supported via the dollars-brace syntax, and does simple text substitution. In addition, there are a few dynamic variables that can be used: - "${VAR}" - normal replacement - "${removeQuotes:VAR}" - strips surrounding quotes from VAR, it any - "${dospath:VAR}" - converts VAR to backwards-slash path - "${dir:PathWithFilename}" - just the directory part of filename - "${this_dir}" - the location of the containing build.xml file


The following code is saved as example.xml:

   <echo value="Hello ${WHO}" if="WHO" unless="SILENT" />
   <echo value="You are in ${haxelib:hxcpp}" unless="WHO||SILENT"/>
   <error value="Silent and who both specified" if="WHO SILENT"/>
   <target id="default" />

and some example uses:

 unsetenv SILENT
 haxelib run hxcpp example.xml
 haxelib run hxcpp example.xml WHO=world default
 setenv SILENT 1
 haxelib run hxcpp example.xml
 haxelib run hxcpp example.xml WHO=world

The build.xml file contains configuration, targets, compilers, linkers and files. The details can be found in the subsections: Structure of the top-level Files Tags Targets Compiler Linker Stripper The Haxe Target Xml Injection