Changes

Add support for riscv64 architecture

glibc-compat-symbols.h: skip versioning on PPC64/PPC64LE

GlueGen Struct [1]: Enhance com.jogamp.common.nio.* to serve a most native-free-code Struct-Code generation

Recfactored all NIO buffer utils to Buffers, i.e. buffer <-> address, memcpy, strnlen, etc

Buffers:
- Added copyNativeToDirectByteBuffer(..), allowing to copy a native memory slice into a direct buffer.
- Added typeNameToBufferClass(String) and sizeOfBufferElem(Class<? extends Buffer>)
- Completed slize2<Type>(..) buffer-mapping methods
- Exposure of safe getDirectByteBuffer(..) w/ null-check (package private)

Added NativeBuffer.storeDirectAddress(..), allowing to write the array address into a native buffer (struct, etc),
allowing to referencing the ElementBuffer (linear array of elements) and PointerBuffer (array of pointer).
Hint: This can be read via PointerBuffer.wrap(..).get(0)

Added ElementBuffer (a NativeBuffer) mapping an array of elements,
completing native abstraction next to PointerBuffer (array of pointer).

ElementBuffer can dereference an existing element-array by native address via ElementBuffer.derefPointer(..).
Views of its content can be directly accessed via ElementBuffer.slice(..).

+++

These utilities and buffer abstractions will allow to reuse code and simplify the GlueGen struct get/set implementations
and help to reduce native code injection.

GlueGen Struct [2]: Add CodeUnit: Representing a generated C or Java file, covering multiple FunctionEmitter allowing to unify output, decoration and dynamic helper code injection per unit

- Handles file open and have public ctor emitAutogeneratedWarning(..), being self-contained

- Includes `JVMUtil_NewDirectByteBufferCopy(..)` implementation in CCodeUnit,
  may be injected if required in customCode via emitHeader(..)

GlueGen Struct [3]: Adopt to CodeUnit Abstraction (replacing plain PrintWriter...)

GlueGen Struct [4]: JavaConfiguration Change: Drop 'ManualStaticInitCall', 'ForceStaticInitCode'; Add 'ReturnsStringOnly', 'MaxOneElement' and 'ImmutableAccess'

Drop 'ManualStaticInitCall', 'ForceStaticInitCode':
  With new CCodeUnit's `JVMUtil_NewDirectByteBufferCopy(..)` implementation
  and generalized Buffers' methods, no specific init code is required anymore.

Add 'ReturnsStringOnly', 'MaxOneElement' and 'ImmutableAccess':
- 'ReturnsStringOnly' only String getter, drop ByteBuffer/byte[]
- 'MaxOneElement' only one element maximum for pointer reference
- 'ImmutableAccess' strict read-only, also reduces generated code a lot

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.

Buffers.copyNativeToDirectByteBuffer(): Remove unused var

GlueGen Struct [6]: Simplify adding 'private ElementBuffer _eb*' memory buffer cache once @ 'releaseVal(..)' code creation

feat(cli): Add --preserveGeneratedCPP option inside GlueGen

feat(feature): Enable pragma once management

feat(CompoundType): Improve error log on CompoundType.addField and CompoundType.setBodyParsed when body is already parsed

feat(translationUnit): Improve logs in case of failure inside translationUnit

feat(constants): Add supports of ~ inside ConstantDefinition

feat(jni): Add directive for dedicated JNI Code with CustomJNICode

GlueGen Struct [7]: Keep struct class non-final (revert), but ensure methods are final. Drop useless 'final' of 'static final'.

ElementBuffer: Add absolute get/put multi-element with full srcElemPos, destElemPos, elementCount argument set and use it for the single absolute get/put methods.

GlueGen Struct [8]: Revised setter (resolved shrinking array, using 'subset' flag), added (detailed) JavaDoc in generated code

Revised setter:

A) int32_t val[10] -> setter for a subset change only, as-is with args[src, srcPos, destPos, length]
                     - no new memory, reuse only
                     - no special action to be performed

B) int32_t* val -> setter with toggle 'subset' with args[subset, src, srcPos, destPos, length],
                - replace memory w/ 'subset==false' where it also may copy 'destPos' gap from old -> new
                - reuse memory w/ 'subset==true', where destPos+length <= elementCount

C) const int32_t* val -> setter to replace referenced memory only args[src, srcPos, length]
                     - always replaces memory, no copy of a gap (no destPos)

Hence:
- case (A) stays as is
- case (B) will be revised and argument 'boolean subset' added
- case (C) will be revised (simplified) and argument 'destPos' removed

doc/JogAmpMacOSVersions.html: Replaced w/ standalone html5 w/ header (utf8)

doc/GlueGen_Mapping.md: Remove note regarding shrinking array, resolved

Drop .md -> .html generated docs (ugly), use our cgit md -> html via refined pandoc styles

Would need to fix my standalone pandoc setup to produce proper standalone docs.

JavaType: Add getSignature(..) like Type

Type: Add hasSize(), change getSignature(..) for const: isConstTypedef() -> "typedef", isConstRaw() -> "native"

GlueGen Struct [9]: Fix regression which added a pointer referencing type 'void', i.e. exclude if !baseCElemType.hasSize() // like 'void*' -> 'void'

GlueGen Struct [10]: Don't skip primitive w/ platform dependent sized type in struct (like 'int') ..

We already support platform dependent sizes like pointer etc, no reason to drop e.g. 'int'.

Note: 'int' is also always 32bit of size within our current set of supported platforms, e.g. MachineDataInfo.

Further fix and clarify primCElemFixedSize and primElemSizeExpr, only to be true and set if isPrimitive.

GlueGen Struct [11]: Formalize Ownership (enum) and elaborate generated Java API-Doc

GlueGen Struct [12]: Throw InternalError(..) for produced code-path where Ownership.Native _and_ native memory potentially gets replaced

GlueGen Struct [9b]: Add unit test for fixed 'void*' regression commit eec3f21c3597ff9bf9760a06e00dd341214ea90d

See impact to T2_InitializeOptions struct fields:
- 'void* Reserved1' shall be ignored (*this is the regression fix*)
- 'void* Reserved2' will be taked due to config 'Opaque long T2_InitializeOptions.Reserved2'
- 'T2_CustomFunc CustomFunc2' will produce a member function call as previously

GlueGen Struct [13]: Adopt GlueGen_Mapping.md to changes, added `Struct Java Signature Examples` w/ Java API Doc snippets

Bring back produced html5 standalone files, having fixed pandoc usage.

See my pandoc-buttondown git repo <https://jausoft.com/cgit/users/sgothel/pandoc-buttondown-cgit.git/about/>

Latest config <https://jausoft.com/cgit/users/sgothel/pandoc-buttondown-cgit.git/commit/?id=fb38ada0c8d71a2b26bd3ee9d075acce84d76b2c>
fixed creation of standalone html5 files.

CPP Enable Pragma Once: Use default jcpp branch as its merged now

CPP Enable Pragma Once: Add GlueGen.run(..) debug output w/ all paramter

CPP Enable Pragma Once: Default is 'true', since usually all compiler and APIs do support this feature

CustomJNICode: Fix/complete commit d7bc10d7ff0e3a30d74c4e4c439230f3983bcfb4: Add emitCustomJNICode(..) for JavaEmitter.endFunctions() not just structs and fix the JNI-c stub code

CustomJNICode: Add missing (separated) test1p1-CustomJNICode.c.stub

fix(cli): Fix disablePragmaOnce option

Option set enablePragmaOnce to true instead false

CPP Enable Pragma Once: Remove cli '--enablePragmaOnce' option as it is enabled by default

GlueGen Struct [14]: Update doc/GlueGen_Mapping.md

Completing a few cases and fix some signatures in table

www/index.html: Copy Documentation section into main text for visibility

Doc: Manual: Adding disclaimer being slightly outdated and hint to GlueGen_Mapping document

GlueGen Type: Use virt getTargetType() for ArrayType dropping getElementType(); Rename getBase{Elem ->}Type() to align with getTargetType()

doc/GlueGen_Mapping.md: Place `Struct Setter Pseudo-Code` above 'Signature Table' and add a brief signature to mapping description to the former

GlueGen Struct [15]: Add FunctionPointer getter and setter support w/ documentation

GlueGen Struct [15b]: FunctionPointer: Drop is<FuncName>Null() -> use get<FuncName>()

GlueGen junit test2.h: Add an anonymous struct pointer w/ opaque long config

JavaEmitter.typeToJavaTypeImpl(): Add targetType in GlueGenException and remove '"' in message

GlueGen Test: Test2 -> Test2FuncPtr

NIO NativeBuffer, {Element,Pointer}Buffer: Add limit, clear and flip; Arrange wrap/deref arguments equal; Add equal set of absolute get/set methods

Completing API to simplify usage by generated code.

All absolute get/set method check arguments itself and against limit(), allow to drop checks in generated code (size).

GlueGen: Type, JavaType: Align getSignature(..) output

GlueGen: Type: Have get{Base,Target}Type() stop at isFunctionPointer(), enhance API doc; Add getArrayBaseOrPointerTargetType() and getTargetFunction()

Added getArrayBaseOrPointerTargetType() returns getBaseType() for arrays or getTargetType() for pointer,
i.e. stops traversing if an elementType is a pointer and returns the elementType as target-type.
This resolves 'int* intPtrArray[10]', but also simplifies all cases of 'int** intPtrPtr' and 'int intPtr[10]' etc.

Since get{Base,Target}Type() returns the functionPointer, getTargetFunction() allows to retrieve the actual target function type.

GlueGen: JavaConfiguration.typeInfo(..): Clarify DEBUG_TYPE_INFO output

GlueGen: JavaConfiguration.promoteTypeInfo(): Fix primitive pointerDepth, i.e. only pass numPointersStripped w/o adding info.pointerDepth()

GlueGen Struct [16]: Add support for pointer-pointer and function-pointer values

See documentation and unit test test2.h, Test2FuncPtr.java and Test3PtrStorage.java

GlueGen: Expose CMethodBindingEmitter.getJNIMangledArgs() as a public static to be reusable

GlueGen: Rename GlueEmitter.getConfig{uration->}() and drop JavaEmitter.getConfig(), cleaning up API usage

GlueGen Fix ProcAddressCMethodBindingEmitter.jniMangle(..) override: Use renamed {jniMangle->getJNIMangledArg}(..)

GlueGen: Add JavaEmitter(JavaConfiguration) ctor

JavaEmitter.generateArrayGetterSetterCode(): Place elemCountExpr null check where it could occur -> non-opaque, non-primitive array case

GlueGen: Fix Type.getSignature(..): Test for isFunctionPointer() to elaborate on FunctionType as getTargetType() only retruns a function-ptr and no more a function-type.

GlueGen FunctionType: Expose toString(..) w/ 'isPointer' argument

GlueGen Add JavaType.forObjectClass()

GlueGen FunctionSymbol: Simplify ctor reusing main-ctor; Be always reachable via type(def)name, ctor: addAliasedName( type.getCName() )

GlueGen JavaConfiguration: Add 'JavaCallbackDef <funcion-pointer-typedef-name> [user-param-idx]'

Define a JavaCallback, enacted on a function-pointer argument `T2_CallbackFunc` and a user-param `void*` for Java Object mapping

Example:
  JavaCallbackDef  T2_CallbackFunc 2

GlueGen JavaConfiguration: Add List<Integer> stringArguments(final AliasedSymbol symbol)

GlueGen JavaCallback: Add preliminary implementation (WIP): Produces proper interfaces, TODO implementation

Note: JavaCallbackDef is commented out on test2.cfg example, since implementation is missing.

GlueGen JavaCallback: Add more related documentation

GlueGen JavaType: Add new nature 'String clazzName': Future (not yet generated or existing) Class objects (existing at runtime)

New nature can be queried via isNamedClass().

Cleaned up equals() and completed hashValue() etc.

Ctor validation ensures exactly one nature is set!

GlueGen JavaCallback: Use new JavaType nature 'named-class', denoting the generated callback interface mapping the callback function.

This passes the jobject for the callback function/interface and the userParam (from 'void*')
down to the native implementation.

TODO: Add specific native implementation for JavaCallback,
wrapping the jobject's into a native struct as user-param
and a universal C-function as the native callback to dispatch
the call to the java method with known arguments.

GlueGen JavaCallback: Expose getJNIMethodDescriptor() for JNI mangled method names, used in CMethodBindingEmitter; Use JavaCallback's function-pointer-type capital-name as simple-class-name and its FQN for JNI resolution.

GlueGen JavaCallback: Move JavaCallback into JavaConfiguration, accessible across *Emitter (needed for CMethodEmitter as well); Add JavaCallback.methodSignature to be passed to native function later on to find the callback jmethodID

GlueGen JavaCallback: Add JavaCallback.methodSignature to JNI arg-list and pass value at invocation, allowing to find the jmethodID of callback

GlueGen Struct [17]: Handle void pointers, i.e. `void*`, within a struct as `Opaque` configured pointer-types

.. includes cross-ref'ed doc and unit test

GlueGen doc/GlueGen_Mapping.md: Mentiond OO-Style API mapping and add section for it

GlueGen LibraryOnLoad Config: Generate `JNI_OnLoad(..)` for dynamic and `JNI_OnLoad_<LibraryBasename>(..)` for static libraries and `JVMUtil_GetJNIEnv(..)` to resolve the `JNIEnv*` as used by JavaCallback

GlueGen: Move [de]captializeString(..) JavaEmitter -> static in CodeGenUtils

GlueGen CMethodBindingEmitter: Refactor emitBodyReturnResult() -> emitBodyMapCToJNIType(): Reuse to converting any C-type argument to java JNI type (i.e. native callback to JavaCallback)

GlueGen FunctionType: Factor out getParameterList(..) from toString(..) and drop 'void' and use typedef-name; MethodBinding: Add getCParameterList(..) and getJavaParameterList(..) for general usage similar to FunctionType.getParameterList()

GlueGen ProcAddressCMethodBindingEmitter.jniMangle() override: Only add additional params if produced name containes '__', i.e. JNI mangled parameter

GlueGen JavaCallback: 1st Working Draft: Changed 'JavaCallbackDef' config, added code generation incl. native to Java dispatch and resource management

Tested via Test4JavaCallback.java (using test2.[hc]).

Please read the GlueGen_Mapping.md as well as Test4JavaCallback.java .

+++

Some implementation details:

JavaConfiguration maps JavaCallbackDef to JavaCallback set-function and maintains a list.
JavaCallbackDef itself holds all configured details.

JavaConfiguration also maps JavaCallbackInfo to JavaCallback set-function.
JavaCallbackInfo itself holds all compile time information, as produced by JavaEmitter.beginFunctions(..).
This extends JavaCallbackDef and avoid repetetive computation for the callback-function-type and its MethodBinding,
parameter indices for the callback interface and userParam, etc.

CMethodBindingEmitter: Native callback to Java dispatch
- The JavaCallback setter function creates a native 'UserParam' struct instance,
  which holds the callback-interface-jobject, its callback-jmethodID and
  the userParam-jobject for invocation of the actual JavaCallback interface method.

- To produce the C-Type -> JNI-Type conversion, An internal CMethodBindingEmitter instance
  for the native-callback function binding is created inside the CMethodBindingEmitter of the callback setter method.

  It is being used to map the types to JNI within the generated native callback function,
  passed to the actual JavaCallback method.

JavaMethodBindingEmitter: Native callback to Java dispatch
- The JavaCallbacl setter passes the callback-interface-object, the userParam-object and the
  callback-method-signature (to have the native method retrieve the jmethodID).

- It receives the native pointer of the native `UserParam` struct instance,
  which gets mapped to the userParam-object. (*TODO: Refine ownership + release*).

Doc: Align GlueGen_Mapping.md intro w/ README.md and www/index.html

Doc: www/index.html: Fix JOGL UML link

Doc intro: Fix LibraryOnLoad using generic LibraryBasename

README.md: Fix links

GlueGen JavaCallback: Set-Callback: Ensure a previously mapped 'userParam' instance is released before binding new one; Add test changing callback function.

Test4JavaCallback: Just rename myUserParam -> myUserParam01 for future tests..

Eclipse classpath

GlueGen FunctionType/MethodBinding: get*ParameterList(): Use a more flexible way via a ParameterConsumer visitor, also usable for other iterative parameter generator

GlueGen JavaCallback: Resolve key mapping of callback and associated resources via 'JavaCallbackKey' config and custom `SetCallback-KeyClass`

Updated unit test and doc accordingly.
Unit tests handle OpenAL's AL_SOFT_callback_buffer and AL_SOFT_events.

Tested global scope (no key, default) and 1 key (default) and 1 key (custom class).

Added more query functions, which all only take the `SetCallbackFunction` key arguments as specified.

Cleaned up JavaCallback* config class field naminig scheme.

Added 'synchronized (..Map) { }' block in crucial `SetCallbackFunction`,
rendering implementation thread safe.

GlueGen Intro: Add section about its comprehensive runtime library, shorten the JNI_OnLoad section

GlueGen JavaCallback: Release the associated data (natively) only after the actual toolkit setCallback call

.. to avoid a potential race condition

GlueGen JavaCallback: Only produce default 'Key' class if keys are used, expose 'Key' to public and use it. Expose release*() and get*Keys() methods

Further we use a dedicated lock Object used in the Java implementation.

TODO: Native static callback dispatch code shall
- (also) acquire the lock
- handle case where the data has been released already
to render this solution thread-safe and data-race free

GlueGen JavaCallback: Use `SetCallback-KeyClass` if manually specified, even if no keys are defined!

GlueGen JavaCallback: Native callback: Check ObjectRef validity and synchronize (MonitorEnter/Exit) with same Object of Java impl. -> thread safe

GlueGen JavaCallback: Emphasize all methods are thread-safe

doc/GlueGen_Mapping.md: Typo

GlueGen JavaCallback: Document native callback use-after-free potential (caught), zero-mem @ release

GlueGen JavaCallback: Native Callback: Reduce 'look-ahead' of read-after-free to critical lockObj only

GlueGen Struct [18]: Drop redundant 'static get*ElemCount() { return 1 }` for: isPrimitive && !isPointer && staticElemCount && maxOneElement

CMethodBindingEmitter JavaCallback: Use a friendly readable basename for errors

GlueGen JavaCallback: CMethodBindingEmitter: Check lockObj for NULL before GetObjectRefType(), avoid certain (older) Hotspot issues

GlueGen JavaCallback: CMethodBindingEmitter: Check, describe & clear exception if occurring - we must assume async off-thread source in general

Covered by unit tests now

GlueGen JavaCallback: Unify native 'T_JavaCallbackGlueData' typedef struct

GlueGen JavaCallback: Revised: Static Java callback dispatcher, dropping native heap, support Struct UserParam ...

Implementation now generates a static Java callback dispatcher for each defined SetCallbackFunction, which gets invoked by the generated native static counterpart with all arguments required.

The static callback utilizes its own synchronization for thread-safety and fetches the required data set stored at SetCallbackFunction to dispatch the call to the users' CallbackFunction.
In case the callback has been removed already, the static callback simply bails out quietly.

The native code does not create, release or manage heap memory and therefore is considered safe.

+++

Further Struct Type UserParam are now supported including Heterogeneous UserParam mapping (read GlueGen_Mapping.*).

+++

Cleaned up code by extracting all JavaCallback emitter code into JavaCallbackEmitter class in one place,
leaving JavaMethodbindingEmitter and CMethodbindingEmitter mostly in their original stage (non-convoluted).

In this regard, I had to refactor a few function, i.e. moving CMethodbindingEmitter.getJNIMangledArg(..)
into JavaType.appendDescriptor(..) and JavaType.appendJNIDescriptor(..) while reusing the toJNIMethodDescriptor(..) conversion.

Test4JavaCallback covers and passes all cases.

GlueGen JavaType.appendDescriptor(..): Fix regression: Must return a vanilla descriptor ('/' not '_') i.e. non JNI method-name descriptor to avoid double conversion

doc/GlueGen_Mapping.md: Quote `void*` correctly ..

GlueGen JavaCallback/LibraryOnLoad: Always include the `libraryBasename` agnostic 'emitJNIEnvDecl()' (declaration) in JNI code; Detach the thread from the JVM if newly attach in callback!

GlueGen: Add 'PascalString' string semantics (length + value-ptr), added prelim code for JavaCallback use-case emitBodyMapCToJNIType()

It is common in toolkit APIs that a string might not be passed as a 'nul' terminated (EOS) C string,
but as a Pascal string with a given length argument.

A C string is specied as
  ArgumentIsString alEventCallbackInject 3
while allowing multiple indices ..

A Pascal string can be specified as
  ArgumentIsPascalString ALEVENTPROCSOFT 3 4
while allowing multiple indice-tuples for length and value ..

The tuple consist of the length agrument-index first (usually an int)
followed by the value argument-index (usually a 'char*').

+++

CMethodBindingEmitter.emitBodyMapCToJNIType(), where PascalString is implemented,
is currently being used for
- JNI return statement (no PascalString impact possible)
- JavaCallback C type -> JNI type, PascalString impacting

Manual: Refine `ArgumentIsPascalString`

GlueGen JavaCallback: Fix `staticCBClazz*` initial setup (only), using a NewGlobalRef() for jclass (not required for static jmethodID)

Also use a longer jclass argument name 'clazz' -> 'staticCBClazz' to avoid potential collisions

GlueGen JavaCallback: Remove ambiguity: Config JavaCallbackDef/JavaCallbackKey: Always define both parameter indices; emitJavaStaticCallback(): Use cbFuncBinding and cbFuncKeyIndices from callback parameter to build key

GlueGen JavaCallback Doc: Remove reasoning (avoiding ambiguity) to CallbackFunction parameter index

GlueGen JavaCallback: Add capability to have UserParam as (part of) key

Resolves use case where UserParam reflects e.g. a context (AL_SOFT_events)
and will be (part of) the key mapping.

Implementation required an additional userParamID -> userParam mapping for default Object/ID usage.

Added 2 test cases.

Manual: Fix ArgumentIsPascalString

GlueGen JavaCallback: Add optional custom 'Callback-UserParamClass` for non-compound `UserParam` types to have more clarity in resulting API

doc/GlueGen_Mapping.md: Typos 'UserParam' -> 'UserParamClass'

doc/GlueGen_Mapping.md: Typos 'UserParam' -> 'UserParamClass' (2 more occassions)

doc/GlueGen_Mapping.md: Using 'UserParamClass' .. grammar (3 commits for 1 discount today)

Cough cough .. should have reviewed the whole thing once. Must be the summer distraction causing premature commits. Sorry about that :)

feat(generation): Add setter generation for not constant and not opaque compound attribute

feat(callbackGenerator): Add basic management of callback without userData

doc/GlueGen_Mapping.md: Add some documentation with JavaCallback without userData

feat(arrayAccessor): Allow to use ReturnedArrayLength with getter associated with field with name in PascalCase or camelCase

CMethodBindingEmitter.emitBodyMapCToJNIType(..): Add proper intendation to NIO ByteBuffer generation (isNIOBuffer || isCompoundTypeWrapper)

JavaCallbackEmitter.{emitCSetFuncPreCall, emitCAdditionalCode}(): Group 'userParamDefined' case (cleanup)

JavaCallbackEmitter.{emitCSetFuncPreCall, emitCAdditionalCode, emitJavaCallbackBodyPassJavaArguments}(): Use capitalized sub-string 'baseArgName' for (static) callback related entities

JavaCallbackEmitter.{emitCSetFuncPreCall, emitCAdditionalCode, emitJavaCallbackBodyPassJavaArguments}(): Fix exclusion of ad-hoc compound conversion for userParam

Passed CMethodBindingEmitter denotes the callback-function, including the binding.

The new iteration to handle the ad-hoc compound conversion,
introduced in commit ad69716fda64b517c33ed847c4b215ea398aac99 'callback without userData',
iterates over the callback-function argument list.
Hence it shall only exclude the ad-hoc compound conversion
if index != info.cbFuncUserParamIdx.

Dropping the addition exclusion 'i != info.setFuncUserParamIdx'.

JavaCallbackEmitter.emitCSetFuncPreCall(): Drop redundant arg 'CMethodBindingEmitter jcbFuncCMethodEmitter', use local 'info.cbFuncBinding'

Was added in commit ad69716fda64b517c33ed847c4b215ea398aac99 'callback without userData',
while adding ad-hoc compound conversion.

JavaCallbackEmitter.emitJavaCallbackBodyPassJavaArguments(): Drop redundant arg 'MethodBinding jcbFuncCMethodBinding', use local 'info.cbFuncBinding'

Since emitJavaCallbackBodyPassJavaArguments() is private now,
only use case is to handle info.cbFuncBinding and we can drop the redundant argument.

Similar to cleanup commit e9a2294b3f18bb4c4f38347ccf347058cb4642b3

JavaCallbackEmitter.emitCAdditionalCode(): Use `info.cbFuncBinding` locally and passed 'jcbFuncCMethodEmitter' only to invoke CMethodBindingEmitter.emitBodyMapCToJNIType(..)

Passed 'jcbFuncCMethodEmitter' only used to access CMethodBindingEmitter.emitBodyMapCToJNIType(int, boolean), a non-ideal hack! (FIXME)

General processing shall use the local `info.cbFuncBinding`.

JavaEmitter: Encapsulate 'needsJavaCallbackCode' query in JavaConfiguration. TBD: Is this even required?

- needsIntermediateOperation -> needsJavaCallbackCode
- Use JavaConfiguration.requiresJavaCallbackCode(..)

TBD: Is this even required?
As far as I see, the non-userParam callback case adds no additional code requirements.
Both, callback with and without userParam shares same code path
and the respective native static fields.
Only that the non-userParam code path adds additional native static fields,
but all code sections are produced in both cases.

Fix & Enhance Test4JavaCallback for non-userParam chapter12*: Fix ad-hoc compound equals and add chapter12b for additional parameter with different order

- ad-hoc compound equals must compare value, since native code creates a new class instance from native struct

- Add additional case with addition callback argument for further validation

feat(callbackGenerator): Prevent generation of CallBack interface if setter related isn't present

CMethodBindingEmitter.emitBodyPassCArguments(): Either pass STRING_CHARS_PREFIX or javaCallbackEmitter.emitCOptArgumentSuffix(..)

We only produce one variant in code.

Use case: String type as userParam (barely tested and not useful)

JavaEmitter.bindFunction(): Add JavaCallback userParam non-void case (i.e. 'String')

Use case: String type as userParam, barely tested and not useful.
However, let's pass through all cases in our code.

Added LOG INFO for mapped types.

JavaCallbackEmitter.emitJavaKeyClass(): Use directBufferAddress for compound types in equals and hashCode, i.e. use memory identity

Use case is having a compound-type as userParam, which also acts as key, see MessageCallback13, Test4JavaCallback.chapter13().

The Java compound instance is re-created using the actual identical native memory (address),
which has been stored or passed in the native toolkit.

JavaCallback: Remove non-UserParam JavaConfiguration.requiresJavaCallbackCode()

Method was encapsulated in commit d4e8ecc3b4f68b86d95ec951971a0fea20217988
and questioned whether it is required.

The non-userParam callback case adds no additional code requirements.
Both, callback with and without userParam shares same code path
and the respective native static fields.
Only that the non-userParam code path adds additional native static fields,
but all code sections are produced in both cases.

Passed all unit tests.

doc/GlueGen_Mapping.md: Shorten UserParamIndex '<0' to disable 'UserParam' and produce html page

wip(test_case): Example of test case for issue related of 927bbc7160a812bb29c0e7120d4a3009bfb13bbf

Almost done

Revert "JavaCallback: Remove non-UserParam JavaConfiguration.requiresJavaCallbackCode()"

This reverts commit 927bbc7160a812bb29c0e7120d4a3009bfb13bbf.

WIP JavaCallback Tests: Rename test2-gluegen.cfg -> test2-if.cfg

WIP JavaCallback Tests: Fix: Link library Bindingtest2p1 against library test2 not test1

WIP JavaCallback Tests: Fix: test2-CustomJavaImplCode.java.stub must be 'IncludeAs' for both implementations, Bindingtest2p1Impl and Bindingtest2p2Impl

WIP JavaCallback Tests: Fix typo in 'CustomJavaCode' Java class target name

WIP JavaCallback Tests: Fix Test4p2JavaCallback.chapter__TestLoadLibrary() issue loadBindingtest2p2() not loadBindingtest2p1()

GlueGen Code Unit Tests using a statically linked tool library do not need to load the tool library dynamically, hence dropped.

Just ensure GlueGen itself is initializes via Platform.initSingleton() in common BaseClass

JavaConfiguration.requiresJavaCallbackCode() shall return true for all JavaCallback cases no just non-userParam case

Additional body code for JavaCallback is required for methods it.

Cleanup unit test class names: Try to start w/ 'Test', remove intermediate 'Test' for supporting, non-test classes

Cleanup unit test class names (pt2): Try to start w/ 'Test', remove intermediate 'Test' for supporting, non-test classes

Cleanup unit test class names (pt3): Try to start w/ 'Test', remove intermediate 'Test' for supporting, non-test classes

Add notes `Loading a MacOS Native Library's Dependencies` and use absolute path in unit test script for library-path

Minor cleanup (includes, spacing)

JavaCallback: Add Mathieu Féry's detailed git comment regarding 2abb40b0ca9a6a06bdbe3e66b4235301ed15c693; Updated GlueGen_Mapping.md

Original comment of commit 2abb40b0ca9a6a06bdbe3e66b4235301ed15c693
  wip(test_case): Example of test case for issue related of 927bbc7160a812bb29c0e7120d4a3009bfb13bbf

Revised comment taken from unmerged updated branch f6de3646acf0fdadf55708fd8a1c42fbd8663bc5
    wip(test_case): Example of test case for issue related of 927bbc7160a812bb29c0e7120d4a3009bfb13bbf

    Some short summary of modifications :
     * Add tests with each emitters for test2, but tests are shared and run for each emitters
     * Update JavaParser.g to allow parsing of bindings generated after test2 processing
       * Add basic management of generic type (But not yet retrieved inside classTypeSpec args)
       * Add basic management of annotations (with or w/o parameter(s)) (Retrieved in statement, classes and interfaces but not used)
     * Align lexer constants in JavaParser.g
     * Update JavaParser.g to allow fetching all inner classes and inner interfaces to allow excluding by ExtendedInterfaceSymbolsIgnore
     * Modify JavaConfiguration::requiresJavaCallbackCode because all callback need to force generation not only callback without user param
       * Functions not generated w/o JavaConfiguration::requiresJavaCallbackCode :
         * SetLogCallBack12a
         * SetLogCallBack12b
         * MessageCallback11b
         * alBufferCallback0

feat(generation): Fix CodeGenUtils.emitJavaHeaders

When both classExtended and interfaces are specified for given class space missing between classExtended and implements keyword

feat(generation): Fix generic parsing inside JavaParser.g to allow parsing of java callback implementation

Bump jcpp (merged w/ jcpp upstream v1.4.14) and adopt to changes

Drop PCPP, GlueGen exclusively uses JCPP; Adopt test case Test{P->J}CPP

TestJCPP: Add recursive-include test and include a header file starting with '-' and in a subdir containing a '-'

ANTLR Syntax: Add debugging facility for GnuCParser.g and StdCParser.g

Bug 1450: Fix 'Number' rule, i.e. only consume positive numbers as `additiveExpr` and `unaryExpr` consume the '-' operator

n GlueGen commit 10032c0115f2794a254cffc2a1cd5e48ca8ff0b8 in branch JOGL_2_SANDBOX
Ken hacked in consuming a '-' prefix to have negative numbers covered by 'Number'.

This is wrong, as it breaks deduction of `additiveExpr` and 'unaryExpr' rules,
which want to consume '-' and '+'.
The latter is used to completely resolve constant expressions
starting from the 'constExpr' rule.

See ISO 9899:202x Programming Language - C
https://www.open-std.org/jtc1/sc22/wg14/www/docs/n2596.pdf

Bug 1450: Widen ConstantDefinition.isConstantExpression() to include 'patternCPPOperand'

i.e. all supported operands used for constant-expression of define macros.

Bug 1450: Be more verbose w/ JavaEmitter comment lines for enums and defines, include native expression

Bug 1450: Add test snippets covering the issues: test2.h for Bindingtest2, TestJCPP and new TestCParser

Bug 1450: TestCParser: Enable test10_cc() w/o JCPP

GlueGen: 'from expression' -> 'with expression'