aboutsummaryrefslogtreecommitdiffstats
path: root/README.md
diff options
context:
space:
mode:
authorSven Gothel <[email protected]>2023-06-16 02:16:20 +0200
committerSven Gothel <[email protected]>2023-06-16 02:16:20 +0200
commit8b127c4c1dd26fcb1756805ddb83729203161f78 (patch)
treef8563a0e39d293bc070ef01e457cfe08ee44096d /README.md
parentaeadfab9572e4b441b1bc1f0708cf4c72dfe181e (diff)
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.
Diffstat (limited to 'README.md')
-rw-r--r--README.md79
1 files changed, 79 insertions, 0 deletions
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..e6a0a57
--- /dev/null
+++ b/README.md
@@ -0,0 +1,79 @@
+# GlueGen, Native Binding Generator for Java™
+
+[Original document location](https://jogamp.org/cgit/gluegen.git/about/)
+
+## Git Repository
+This project's canonical repositories is hosted on [JogAmp](https://jogamp.org/cgit/gluegen.git/).
+
+## Overview
+[GlueGen](https://jogamp.org/gluegen/www/) is a compiler for function and data-structure declarations,
+generating Java™ and JNI C code offline at compile time
+and allows using native libraries within your Java™ application.
+
+It reads ANSI C header files
+and separate configuration files which provide control over many
+aspects of the glue code generation. GlueGen uses a complete ANSI C
+parser and an internal representation (IR) capable of representing all
+C types to represent the APIs for which it generates interfaces. It
+has the ability to perform significant transformations on the IR
+before glue code emission.
+
+GlueGen can produce native foreign function bindings to Java™ as well as
+map native data structures to be fully accessible from Java™ including
+potential calls to embedded function pointer.
+
+GlueGen is also capable to bind even low-level APIs such as the Java™ Native Interface (JNI) and
+the AWT Native Interface (JAWT) back up to the Java™ programming language.
+
+GlueGen utilizes [JCPP](https://jogamp.org/cgit/jcpp.git/about/), migrated C preprocessor written in Java™.
+
+GlueGen is used for the [JogAmp](https://jogamp.org) projects
+[JOAL](https://jogamp.org/cgit/joal.git/about/),
+[JOGL](https://jogamp.org/cgit/jogl.git/about/) and
+[JOCL](https://jogamp.org/cgit/jocl.git/).
+
+GlueGen is part of [the JogAmp project](https://jogamp.org).
+
+**The JogAmp project needs funding and we offer [commercial support](https://jogamp.org/wiki/index.php?title=Maintainer_and_Contacts#Commercial_Support)!**<br/>
+Please contact [Göthel Software (Jausoft)](https://jausoft.com/).
+
+### License
+See [LICENSE.txt](LICENSE.txt).
+
+## Documentation
+
+* [GlueGen Java™ API-Doc](https://jogamp.org/deployment/jogamp-next/javadoc/gluegen/javadoc/)
+* [GlueGen Native Data & Function Mapping for Java™](doc/GlueGen_Mapping.md)
+* [GlueGen Manual](doc/manual/)
+* [JogAmp's MacOS Version Support](doc/JogAmpMacOSVersions.md)
+* [How To Build](https://jogamp.org/gluegen/doc/HowToBuild.html)
+
+## Build Requirements
+Check [GlueGen's HowToBuild](https://jogamp.org/gluegen/doc/HowToBuild.html).
+
+## Directory Organization:
+```
+make/ Build-related files and the main build.xml
+doc/ Documentation
+jcpp/ JCPP (git sub-module), migrated C preprocessor written in Java
+src/ The actual source for the JOAL APIs.
+src/junit/ Unit tests
+test/ Standalone manual tests
+build/ (generated directory) Where the Jar and DLL files get built to
+www/ JOAL project webpage files
+```
+
+## Contact Us
+- JogAmp [http://jogamp.org/](https://jogamp.org/)
+- JOAL Web [http://jogamp.org/](https://jogamp.org/joal/)
+- Forum/Mailinglist [http://forum.jogamp.org/](https://forum.jogamp.org/)
+- Repository [http://jogamp.org/git/](https://jogamp.org/git/)
+- Wiki [https://jogamp.org/wiki/](https://jogamp.org/wiki/)
+- Maintainer [https://jogamp.org/wiki/index.php/Maintainer_and_Contacts](https://jogamp.org/wiki/index.php/Maintainer_and_Contacts)
+- Sven's Blog [https://jausoft.com/blog/tag/jogamp/](https://jausoft.com/blog/tag/jogamp/)
+- Email sgothel _at_ jausoft _dot_ com
+
+## History
+Since roughly 2010, GlueGen development has been continued
+by individuals of the JogAmp community, see git log for details.
+