GlueGen Struct [5]: Revised Struct Mapping + Documentation

GlueGen Revised Struct Mapping (esp pointer to array or single element), Struct String Charset, .. and Documentation

- Documentation:
    - Added README.md
      Let's have a proper face for the git repo

    - Added doc/GlueGen_Mapping.md (and its html conversion doc/GlueGen_Mapping.html)
      Created a new document covering application and implementation details suitable for users/devs.

    - Added doc/JogAmpMacOSVersions.md conversion to doc/JogAmpMacOSVersions.html

    - Updated www/index.html

- Use *CodeUnit instead of PrintWriter, representing a Java or C code unit covering a set of functions and structs.
    The CCodeUnit also handles common code shared by its unit across functions etc.

- Dropping 'static initializer', as its no more required
    due to simplified `JVMUtil_NewDirectByteBufferCopy()` variant.

- Revised Struct Mapping:
  - Pure Java implementation to map primitive and struct fields within a struct
    by utilizing ElementBuffer.

    Only 'Function Pointer' fields within a struct require native code.

    Exposes `static boolean usesNativeCode()` to query whether native code is used/required.

  - Transparent native memory address API

    Expose `long getDirectBufferAddress()` and `static TK_Struct derefPointer(long addr)`,
    allowing to
    - pass the native struct-pointer with native code
    - reconstruct the struct from a native struct-pointer
    - have a fully functional `TK_Struct.derefPointer(struct.getDirectBufferAddress())` cycle.

  - Add 'boolean is<Val>Null() to query whether a pointer (array) is NULL

  - *Changed* array get/set method for more flexibility alike `System.arraycopy(src, srcPos, dest, destPos, len)`,
    where 'src' is being dropped for the getter and 'dest' is being dropped for the setter
    as both objects are reflected by the struct instance.

  - *Changed* `get<Val>ArrayLength()` -> `get<Val>ElemCount()` for clarity

  - Considering all ConstElemCount values with config 'ReturnedArrayLength <int>'
    to be owned by native code -> NativeOwnership -> Not changing the underlying memory region!
    JavaOwnership is considered for all pointer-arrays not of NativeOwnership.
    Hence any setter on a NativeOwnership pointer-array will fail with non-matching elem-count.

  - Add 'release<Val>()' for JavaOwnership pointer-arrays,
    allowing to release the Java owned native memory incl. null-ing pointer and set<Val>ElemCount(0).

  - Support setter for 'const <type>*' w/ JavaOwnership, i.e. pointer to const value of a primitive or struct,
    setter and getter using pointer to array or single element in general.

  - Added Config `ImmutableAccess symbol` to disable all setter for whole struct or a field

  - Added Config `MaxOneElement symbol` to restrict a pointer to maximum one element and unset
    initial value (zero elements)

  - Added Config `ReturnsStringOnly symbol` to restrict mapping only to a Java String,
    dropping the ByteBuffer variant for 'char'

  - String mapping default is UTF-8 and can be read and set via [get|set]Charset(..) per class.

  - Dynamic string length retrieval in case no `ReturnedArrayLength` has been configured
    has changed from `strlen()` to `strnlen(aptr, max_len)` to be on the safe site.

    The maximum length default is 8192 bytes and can be read and set via [get|set]MaxStrnlen(..) per class.

    FIXME: strnlen(..) using EOS byte non-functional for non 8-bit codecs like UTF-8, US-ASCII.
           This is due to e.g. UTF-16 doesn't use an EOS byte, but interprets it as part of a code point.

  - TODO: Perhaps a few more unit tests

  - TODO: Allow plain 'int' to be mapped in structs IFF their size is same for all MachineDescriptions used.
          Currently this is the case -> 4 bytes like int32_t.

1 files changed, 64 insertions, 5 deletions

diff --git a/make/build-test.xml b/make/build-test.xml
index 85437f6..3a72ebd 100644
--- a/make/build-test.xml
+++ b/make/build-test.xml
@@ -165,6 +165,7 @@
         <javac destdir="${build_t.java}" 
                fork="yes"
                includeAntRuntime="false"
+               nativeheaderdir="${build_t.gen}/native/"
                memoryMaximumSize="${javac.memorymax}"
                encoding="UTF-8"
                source="${target.sourcelevel}" 
@@ -522,9 +523,9 @@ chmod 644 ${results}/* \${line.separator}
 
       -->
 
-    <target name="java.generate" depends="junit.test1.java.generate"/>
+    <target name="java.generate" depends="junit.test1.java.generate, junit.test2.java.generate"/>
 
-    <target name="native.build" depends="c.configure, junit.test1.c.build" unless="build.javaonly">
+    <target name="native.build" depends="c.configure, junit.test1.c.build, junit.test2.c.build" unless="build.javaonly">
       <antcall target="gluegen.cpptasks.striplibs" inheritRefs="true">
           <param name="libdir" value="${build_t.lib}"/>
       </antcall>
@@ -562,8 +563,8 @@ chmod 644 ${results}/* \${line.separator}
                  includeRefid="stub.includes.fileset.test"
                  emitter="com.jogamp.gluegen.JavaEmitter"
                  dumpCPP="false"
-                 debug="false"
-                 logLevel="WARNING">
+                 debug="true"
+                 logLevel="INFO">
             <classpath refid="gluegen.classpath" />
         </gluegen>
         <antcall target="java.generate.copy2temp" inheritRefs="true" />
@@ -588,7 +589,7 @@ chmod 644 ${results}/* \${line.separator}
                  emitter="com.jogamp.gluegen.procaddress.ProcAddressEmitter"
                  dumpCPP="false"
                  debug="false"
-                 logLevel="INFO">
+                 logLevel="WARNING">
             <classpath refid="gluegen.classpath" />
         </gluegen>
     </target>
@@ -657,6 +658,64 @@ chmod 644 ${results}/* \${line.separator}
 
       -->
 
+    <target name="junit.test2.java.generate">
+        <echo message=" - - - junit.test2.java.generate" />
+
+        <dirset id="stub.includes.fileset.test" dir=".">
+            <include name="${test.junit.generation.dir}/**"/>
+            <include name="${stub.includes.dir}/gluegen" />
+            <include name="${stub.includes.dir}/macosx" />
+            <include name="${stub.includes.dir}/unix" />
+            <include name="${stub.includes.dir}/windows" />
+        </dirset>
+
+        <gluegen src="${test.junit.generation.dir}/test2.h"
+                 outputRootDir="${build_t.gen}"
+                 config="${test.junit.generation.dir}/test2.cfg"
+                 literalInclude="${test.junit.generation.dir}"
+                 includeRefid="stub.includes.fileset.test"
+                 emitter="com.jogamp.gluegen.procaddress.ProcAddressEmitter"
+                 dumpCPP="false"
+                 debug="false"
+                 logLevel="WARNING">
+            <classpath refid="gluegen.classpath" />
+        </gluegen>
+        <antcall target="java.generate.copy2temp" inheritRefs="true" />
+    </target>
+
+    <target name="junit.test2.c.build">
+        <!-- this is the test2 implementation -->
+        <patternset id="junit.test2.implc.src.files">
+          <include name="src/junit/${test.junit.generation.rel}/test2.c"/>
+        </patternset>
+
+        <!-- Windows hacks ro make a proper DLL -->
+        <linker id="linker.test2.dll.cfg.id" extends="${linker.cfg.id}">
+        </linker>
+
+        <c.build c.compiler.src.files="junit.test2.implc.src.files"
+                 output.lib.name="test2"
+                 compiler.cfg.id="${compiler.cfg.id}"
+                 linker.cfg.id="linker.test2.dll.cfg.id"/>
+
+        <!-- this is a dynamic lookup binding to the test1 implementation -->
+        <linker id="linker.test2.runtime.cfg.id" extends="${linker.cfg.id}">
+        </linker>
+
+        <patternset id="junit.test2.jnic.src.files">
+          <include name="${build_t.gen.rootrel}/native/BindingtestT2Impl_JNI.c"/>
+          <!-- include name="${build_t.gen.rootrel}/native/TK_Surface_JNI.c"/ -->
+          <!-- include name="${build_t.gen.rootrel}/native/TK_ModelConst_JNI.c"/ -->
+          <!-- include name="${build_t.gen.rootrel}/native/TK_ModelMutable_JNI.c"/ -->
+        </patternset>
+
+        <c.build c.compiler.src.files="junit.test2.jnic.src.files"
+                 output.lib.name="Bindingtest2"
+                 compiler.cfg.id="${compiler.cfg.id}"
+                 linker.cfg.id="linker.test1.runtime.cfg.id"/>
+    </target>
+
+
     <!-- updates / create the test results zip file -->
     <target name="test-zip-archive" depends="init">
         <archive.7z destfile="${build}/${test.archive.name}.7z"