6fe7c06e6320bafcc5500f1e3b6d2eec46241a0d
[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 (recursively).
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 integers.  The generator
74 doesn't currently export any of the symbolic values to Java but it is
75 easy to add.
76
77 varags is not implemented.
78
79 All function pointers are translated to a unique set of functional
80 interfaces whose names are based on the function signature.  So the
81 type names are ugly but they are stable.
82
83 Anonymous type names are based on the structure member they belong to
84 so they may not be unique.
85
86 It will only ever support c.
87
88 Only tested against the panama 'openjdk-14-panama+1-15_linux' on
89 slackware-current @ 2020.01.01 and gcc 9.2.0.
90
91 License
92 -------
93
94 GNU General Public License, version 3 or later, but see individual
95 file headers for specifics.
96
97 Links
98 -----
99
100  * https://www.zedzone/software/panamaz.html - project page.
101  * https://openjdk.java.net/projects/panama - openjdk panama page.