1d387188d58623d134bdfd65093470461578ba38
[panamaz] / README
1
2 Introduction
3 ------------
4
5 This is an alternative to jextract for the OpenJDK panama project
6 which in turn is a project to implement Java to Native interfaces at
7 runtime.
8
9 It uses a gcc plugin for type extraction and a "simple" perl script to
10 transform this into Java source files with the appropriate annotations
11 for panama to do it's thing.
12
13 Compile
14 -------
15
16 Edit the makefile to point to your gcc directory and make.
17
18 $ cd src
19 $ vi Makefile
20 $ make
21
22 generate is a perl script.
23
24 See test-api/* for a simple example.  JAVA_HOME must point to
25 a compatible panama-enabled jdk.
26
27 Use dump.so
28 -----------
29
30 dump.so is a gcc plugin which captures structures, unions, enums,
31 exported functions, and a few typedefs into a perl source file
32 containing a single hash.
33
34 Put all the include files required for your api in api.h.
35
36 $ gcc -fplugin=src/export.so -fplugin-arg-export-output=api.pm api.h -o /dev/null
37
38 api.pm is a text file of perl source-code which contains a descriptor
39 of all supported types found.
40
41 Use generate
42 ------------
43
44 Quick and dirty:
45
46 $ generate -d dir -t name.space -c APILib -lapi ./api.pm
47
48 Generate all structures in api.pm (the ./ is required) and place all
49 functions into dir/name/space/APILib.java which will link with
50 libapi.so.
51
52 The generator is quite flexible, sub-sets of functions can be placed
53 in alternative *Lib.java files, types can be filtered.  If a function
54 or type is specified explicitly, then only those types it requires are
55 included in the generated output.
56
57 See the top of the file for details, it's probably up to date.
58
59 Status
60 ------
61
62 This is currently just a 'quick and dirty' weekend hack.  The tools
63 spew a lot of debug.  dump.cc is basic c-compatible-c++, because I
64 don't know c++.
65
66 dump.so works by hooking into the gcc pre-compiled headers function,
67 it might work with a c source file as well.  It's only been used with
68 gcc 9.
69
70 The dumper will hard-fail if it sees defintions it doesn't understand,
71 and currently it's only been tested with a small nubmer of libraries.
72
73 enumerations are currently translated to integres.  The generator
74 doesn't currently export any to Java.
75
76 varags is not implemented.
77
78 All function pointers are translated to a unique set of functional
79 interfaces whose names are based on the function signature.  So they
80 should remain stable.
81
82 Anonymous type names are based on the structure member they belong to,
83 but they may not be unique.
84
85 It will only ever support c.
86
87 Only tested against the panama 'openjdk-14-panama+1-15_linux'.
88
89 License
90 -------
91
92 GNU General Public License, version 3 or later, but see individual
93 file headers for specifics.
94
95 Links
96 -----
97
98  * https://www.zedzone/software/panamaz.html - project page.
99  * https://openjdk.java.net/projects/panama - openjdk panama page.