Update Files

Kha/Backends/Kinc-hxcpp/khacpp/docs/build_xml/HaxeTarget.md

@@ -0,0 +1,97 @@
+The Haxe Target
+---------------
+
+When compiling from haxe, via hxcpp, a "Build.xml" file is generated in the output directory.  The file lists the generated files and dependencies and ultimately includes the "toolchain/haxe-target.xml" file, which describes how to combine these files.
+
+### Include Order
+There are a few complications when setting the order in which things are configured, since a particular build might want to:
+  - set the compiler
+  - override some compiler settings
+  - make decisions based on the compiler or settings
+  - set or use standard file prefixes/suffixes 
+
+### Example Sequence
+You can see which files are included by setting the HXCPP_VERBOSE define when compiling.  One example is for a hypothetical user 'Hugh' on a windows platform:
+
+```
+Using makefile: Build.xml
+No specified toolchain
+ - Parsing include: C:/Users/Hugh/dev/hxcpp/toolchain/setup.xml
+ - Parsing include: C:\Users\Hugh\.hxcpp_config.xml (section "vars")
+Using Windows compiler: MSVC
+ - Parsing include: C:/Users/Hugh/dev/hxcpp/toolchain/finish-setup.xml
+ - Parsing makefile: C:\Users\Hugh\test\proj\cpp\Build.xml
+ - Parsing include: C:/Users/Hugh/dev/hxcpp/build-tool/BuildCommon.xml
+ - Parsing include: C:/Users/Hugh/dev/hxcpp/toolchain/haxe-target.xml
+ - Parsing include: C:/Users/Hugh/dev/hxcpp/toolchain/msvc-toolchain.xml
+ - Parsing compiler: C:/Users/Hugh/dev/hxcpp/toolchain/common-defines.xml
+ - Parsing include: C:\Users\Hugh\.hxcpp_config.xml (section "exes")
+```
+
+- setup.xml is read because no custom toolchain is specified, and this just include hxcpp_config
+- the 'vars' section of hxcpp_config is read - mainly to setup SDK locations
+- the hxcpp build tool then uses internal logic based on host and defines to work out which compiler/toolchain to use
+- finish-setup then sets a bunch of standard defines for file-extensions and linking flags based on
+   the type of toolchain being used.
+- The provided buildfile (Build.xml) is then processed. It can use the standard defines from finish-setup.
+- Build.xml imports the standard haxe-target buildfile, which adds standard runtime files
+- The toolchain file is then parsed - making use of any settings from the main Build.xml and finish-setup.
+  - This file includes the "common-defines.xml" from the compiler to inject standard haxe compiler flags
+- hxcpp_config "exe" is parsed.  Historically to add libraries or build-paths to targets.
+
+
+### Standard Environment
+finish-setup.xml is where the conventions are set. These variables include:
+  - haxelink = dll|static_link|exe
+  - LIBPREFIX = lib|""
+  - LIBEXTRA =
+     +  .iphonesim-64
+     +  .iphonesim
+     +  .iphoneos
+     +  .iphoneos-v7
+     +  .iphoneos-v7s
+     +  .iphoneos-64
+     +  .appletvsim-64
+     +  .appletvsim
+     +  .watchos
+     +  .watchsimulator
+     +  -x86
+     +  -v7
+     +  -64
+  - HX_LINK_SUFFIX = LIBEXTRA | -19 (msvc 19)
+  - LIBEXT = .a|.lib
+  - DBG = ""|"-debug"
+  - OBJEXT = "-list-of-config-ids" depending on available options
+
+These variables are used by haxe-target - you can use them too.  Haxe then builds the "haxe" target, which uses some code like:
+```xml
+  <set name="HAXE_OUTPUT_FILE" value="${LIBPREFIX}${HAXE_OUTPUT_PART}${DBG}" />
+
+  <target id="haxe" tool="linker" toolid="${haxelink}" output="${HAXE_OUTPUT_FILE}">
+    <ext value="${LIBEXTRA}.a" if="static_link" /> 
+    <!-- ... -->
+    <files id="__main__" unless="static_link" />
+    <files id="__lib__" if="static_link"/>
+    <files id="__resources__" />
+    <files id="__externs__" />
+    <files id="runtime" unless="dll_import" />
+    <files id="cppia" if="scriptable" />
+    <lib name="-lpthread" if="linux" unless="static_link" />
+    <lib name="-ldl" if="linux" unless="static_link" />
+  </target>
+```
+
+Here you can see the various file groups, which are enabled or not depending on the compiler mode, and some standard libraries that are needed for Linux.
+
+### Experimenting With Hxcpp Generated Code/Build.xml
+If you are using external cpp code, or using meta-data to inject xml into the build process, and you are getting a compile or link error, then it can be useful to run the hxcpp build tool without re-running haxe.  This lets you hand-edit the build file or generated c++ code until you get things to work.  Once you have solved the issues using this technique, then you can move the changes back into the injected/external code.
+
+First, compile haxe with '-v' flag.  This gives quite a bit of debug, but will include a line like this:
+```
+haxelib run hxcpp Build.xml haxe -Dhaxe3="1" -Dhaxe_ver="4.000" -Dhxcpp_api_level="332" -Dsource-header="Generated by Haxe 4.0.0" -I"" -I"C:/Users/Hugh/dev/haxe/std/cpp/_std/" -I"C:/Users/Hugh/dev/haxe/std/"
+```
+
+To use this, first change directories to your output directory.  This will be the one you specified with the "-cpp" haxe compiler option.  Then, cut and paste this command into a shell, cmd or batch file.
+
+
+