Add dependency generation for .api files
[panamaz] / README
1
2 Introduction
3 ------------
4
5 This is various experiments with the panama-foreign abi JEP for
6 invoking 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.
11
12 It uses a gcc plugin to compile c headers to obtain most of the api
13 information, but requires cpp and perl to extract the values of
14 #define constants as they are not available to the gcc plugin.
15
16 This api information is then converted to Java code using a
17 config-directed perl script `export-api'.  The config file can be used
18 to create static (all-in-one) or object oriented output.  It includes
19 templated strings as well as perl fragments to generate various source
20 parts.
21
22 The vulkan api is officially defined by a registry in xml, so there's
23 a separate generator for that.
24
25 Compile
26 -------
27
28 Requirements are gcc and GNU cpp, perl, GNU make, and of course a
29 compatible jdk-foreign jdk.  The various modules require headers or
30 sdks for their corresponding libraries, e.g. ffmpeg-5.x,
31 vulkan-tools-1.2.x.
32
33 Copy config.make.in to config.make and modify any variables required.
34
35 First compile the native binding tools.  This should only need to be
36 done once after which it auto-updates properly.
37
38 $ make notzed.nativez
39
40 Then make everything else, parallel make should work.
41
42 $ make -j
43
44 Or build one module:
45
46 $ make notzed.nativez
47
48 Or run a demo (see next section):
49
50 $ make run-notzed.vkregistry/vulkan.test.TestVulkan
51
52 A non-recursive make setup is used although make file fragments are
53 included from various locations across the modules.  All java is
54 compiled as modules.
55
56 JAVA_HOME must point to a compatible panama-enabled jdk.
57
58 The latest at the time of writing was:
59
60  branch: foreign-jextract
61  commit: 2e1291680024f12fbf2f0f02b0f79d7b4348b369
62  date: Fri Feb 4 11:01:21 2022 +0000
63
64 All output and intermediate files are in bin/
65
66 bin/modules/<module>/classes - compiled java modules
67 bin/gen/<module>/classes - generated java
68 bin/gen/<module>/gen - generated intermediate non-java
69
70 These are more or less an exploded view of all jmod files:
71
72 bin/<target>/bin - commands for all modules
73 bin/<target>/lib - libraries/config and modular jar files for all modules
74 bin/<target>/include - header files for all modules
75
76 Finally:
77
78 bin/<target>/jmods - .jmod modules
79
80
81 Demos
82 -----
83
84 Most examples have a demo, see the <module>_JMAIN variables in the
85 Makefile for the targets.  They are executed using:
86
87 $ make run-<module>/<main-class>
88
89 Modules
90 --------
91
92 notzed.nativez contains some support classes and the code generator.
93 The gcc plugin source is in src/notzed.nativez/native/ the code
94 generator is in src/notzed.nativez/{bin,lib}.
95
96 notzed.api is a pseudo-module containing a simple test c api for
97 experiments, it just builds into a library.
98
99 notzed.apistatic is a 'all in one class' static wrapper for
100 notzed.api.
101
102 notzed.apiobject is an object-oriented wrapper for notzed.api.
103
104 notzed.clstatic is an 'all in one class' static wrapper for OpenCL
105 (2.1).  The api closesly matches the C api except it converts error
106 codes into exceptins and can infer certain arguments from others such
107 as length parameters.  This is probably the most complete api.
108
109 notzed.ffmpeg is a partial object-oriented mapping for ffmpeg-5.0 that
110 closely follows the jjmpeg design.  It's enough to read video frames.
111 The demo requires a file 'movie.api' in the root directory to run.
112
113 notzed.vkheader uses the header-based generator on the vulkan
114 installed headers.  This is still very incomplete work in progress.
115 Much meta-data is lost such as which functions are extensions during
116 the generation of the headers.
117
118 notzed.vkregistry uses a completely different generator which directly
119 parses the official xml registry specification for vulkan
120 (/usr/share/vulkan/registry/vk.xml).  This is directly converted to
121 about-as-java-friendly a vulkan api as one can hope for, particularly
122 the constructors for all the config objects.
123
124 Export process
125 --------------
126
127 The main generator is written in perl and lives in
128 src/notzed.nativez/{bin,lib}.
129
130 The process:
131
132 * run the gcc plugin to extract all of the available c structures from
133   gcc and save them to a perl hash.
134
135   gcc plugins aren't very well documented so it was a lot of trial and
136   error to get it to output all the type information even starting
137   with a partial example.  The names of parameters for function calls
138   were particularly problematic.
139
140 * optionally run export-defines to extract #define constants.  They
141   can be grouped/excluded by name or by the filename they belong to.
142   The the first rule to match will complete the processing for a given
143   type.
144
145   This is also a surprisingly difficult process because the c
146   pre-processor can just generate arbitrary c expressions so the only
147   way to find their correct value is to execute the c.  So the export
148   script generates a c file which is compiled and executed to generate
149   the perl definitions.
150
151   Currently the types are mapped to a 'compatible' native type by
152   using the gcc operators __builtin_choose_expr,
153   __builtin_types_compatible_p, and typeof to implement a
154   pseudo-function overloading in c - possiblly using c++ is a better
155   choice here.  For now inclusions or exclusions are required to
156   avoid problematic definitions that confuse these operators.
157
158 These files are then fed to generate-api.  It proceeds in multiple
159 stages.
160
161 First stages are handled by lib/api.pm.
162
163 * Load and preprocess the api definition.
164
165  - Perform a bunch of 'fix up' processing on the data structures such
166    as inserting anonymous types which are not generated by the plugin.
167
168  - Create a full dependency tree for the objects
169    specificallyreferenced by the api definition so only objects and
170    functions of interest are included.
171
172  - Resolve all the various export options using some rules and store
173    the information about the selected options onto target objects.
174
175 Then generate-api produces the java files from a combination of the
176 processed data definitions and the api definition.
177
178 * Export 'libraries'.  These are static classes of functions and/or
179   constants.
180
181  - Can include static methods.  Methods can have per-method template
182    overrides.
183
184  - Can include constants.
185
186 * Export 'structures'.  These represent C pointers.
187
188  - struct/union have a MemorySegment, a layout, and potentially
189    accessors for fields.
190
191  - anonymous structures just have a MemoryAddress and no accessors.
192
193  - Can include static and member methods.  Methods can have per-method
194    template overrides.
195
196  - Can include constants.
197
198 * Export 'calls'.  These are function interfaces for function pointers.
199
200  - The interface is the java form of the call.
201
202  - If available a typedef name is used, otherwise the names are mapped
203    to a mangled name of the form Call_<args>_<return>.
204
205  - An upcall factory creates an upcall to an instance of a hidden
206    trampline interface which performs the mapping of arguments to java
207    and returns to c.
208
209  - A downcall factory creates a downcall which maps the java call to
210    native and back.
211
212  - Both factories return a record of type FunctionPointer<type> which
213    contains both a NativeSymbol and the java interface instance so they
214    can be used from either environment.
215
216 * Export 'constants'.  These are referenced enums or any defines which
217   haven't been included in any other library or struct.
218
219  - enums are mapped to an interface with fields of:
220      'static final int FOO = xx'
221    of
222      'static final long FOO = xx'
223
224  - defines are mapped to a matching native type which includes
225    floating point types and strings in addition to all the integral
226    types.
227
228 lib/code.pm is used to generate some of the code and handle
229 templating. Common code templates are defined in lib/code.api but can
230 be extended or replaced by a given api file.
231
232 lib/method.pm is used to generate per-field (struct) and per-argument
233 (function) sub-templates for mapping c to and from java.  The
234 sub-templates it uses are defined in lib/types.api but again they can
235 be extended or replaced by a given api file.
236
237 Status
238 ------
239
240 It's all very much work in progress and due to the constant changes in
241 panama will be in flux for some time.
242
243 * bitfields are implemented.
244 * varargs is not implemented.
245 * the generator for notzed.vkregistry uses a lot of miserable
246   write-once perl.
247 * the scope and object lifecycle stuff is not really sorted out yet.
248 * the config format and features are still being fiddled with.
249 * the config file isn't really documented.
250 * the build system is still being fiddled with, some of the output
251   directories are mixed up.
252 * linux-amd64 only at this point in time.
253
254 License
255 -------
256
257 GNU General Public License, version 3 or later, but see individual
258 file headers for specifics.
259
260 Links
261 -----
262
263  * https://www.zedzone/software/panamaz.html - project page.
264  * https://openjdk.java.net/projects/panama - openjdk panama page.
265  * https://github.com/openjdk/panama-foreign - openjdk panama source.