Remove some internal dumps.
[panamaz] / README
1
2 Introduction
3 ------------
4
5 This is some experiments with the panama-foreign abi JEP for invoking
6 native C functions from Java directly and without JNI.
7
8 The main goal is to experiment with creating a "java friendly" and
9 mostly type-safe api directly in one step, without requiring
10 additional wrapping or inconvenient use.
11
12 It's roughly tracking the openjdk repository of the same date.
13
14 It uses a gcc plugin to compile the headers to obtain most of the api
15 information, but requires cpp and perl to extract the values of
16 #define constants.
17
18 This api information is then converted to Java wrappers using a
19 config-directed perl script `generate-native'.  The config is flexible
20 enough to either generate c-like libraries of static functions or
21 object-oriented layouts with data, static and object functions grouped
22 by class.
23
24 test-vulkan uses a different approach as the vulkan api is officially
25 defined by an xml registry and not the generated C headers.  This is
26 directly converted to about-as-java-friendly a vulkan api as one can
27 hope for (all those structs you need to initialise get messy in any
28 language).  Most of the script is converting the registry vk.xml file
29 into a usable structure as it's really only designed for outputting c
30 headers.
31
32 Compile
33 -------
34
35 Requirements are gcc and cpp, perl, GNU make.
36
37 First run make in src.
38
39 See test-*/* for examples.  JAVA_HOME must point to a compatible
40 panama-enabled jdk.
41
42 Status
43 ------
44
45 It's all work in progress of course.
46
47 * bitfields not implemented yet.
48 * varargs is not implemented.
49 * the support library in Memory.java is copied to each output api, but should
50   be global.
51 * the scope and object lifecycle stuff is not really sorted out yet.
52
53 License
54 -------
55
56 GNU General Public License, version 3 or later, but see individual
57 file headers for specifics.
58
59 Links
60 -----
61
62  * https://www.zedzone/software/panamaz.html - project page.
63  * https://openjdk.java.net/projects/panama - openjdk panama page.
64  * https://github.com/openjdk/panama-foreign - openjdk panama source.