Bump to jdk 13.
[nativez] / README
1
2 Copyright (C) 2018,2019 Michael Zucchi
3
4 See the section LICENSE for details.
5
6 Introduction
7 ------------
8
9 This is a C link library and Java base class which can be used to help
10 implement libraries which use the Java Native Interface (JNI).
11
12 It provides a base class for native objects which provides automatic
13 (and manual) reclaimation, and a shared library for easy access to
14 these and other JNI utilities.
15
16 Compile
17 -------
18
19 This module must be compiled under a GNU/Linux system.  Cross
20 compilation is possible to windows-amd64 by installing
21 gcc-mingw-w64-x86-64.
22
23 $ make
24 $ make TARGET=linux-amd64
25 $ make TARGET=windows-amd64
26
27 The target-specific jmodule:
28
29 `bin/notzed.nativez/<target>/notzed.nativez.jmod'
30
31 Other files of import which can be used for an IDE, dependent project
32 compilation, or non-modular use:
33
34 `bin/notzed.nativez/notzed.nativez.jar' - portable modular jar
35 `bin/notzed.nativez/<target>/include' - header files
36 `bin/notzed.nativez/<target>/include' - header files
37 `bin/notzed.nativez/<target>/lib/libnativez.so' - linux shared library
38 `bin/modules/notzed.nativez/' - compiled class files
39 `bin/notzed.nativez/<target>/bin/nativez-gen' - table generator
40
41 Usage
42 -----
43
44 Java Library
45 - - - - - --
46
47 Define a common base class and derive from
48 `au.notzed.nativez.NativeZ'.  This (and all derived classes) must
49 implement the single long (pointer) constructor and load the
50 corresponding dynamic library which implements the native interfaces
51 from any derived classes.
52
53 Each derived class should include a `static void release(long p)'
54 method which will be called once the object is no longer accessible
55 from Java.  This will typically be a native method that frees the
56 associated resources.
57
58 The module for the library must export the package containing the
59 derived classes to the `notzed.nativez' module using the `opens'
60 directive.
61
62 Native Library
63 - - - - - - --
64
65 Whilst not necessary one can use the native library for access to the
66 NativeZ_* functions and some other cross-platform tools.
67
68 The native library should link with -lnativez and include "nativez.h".
69
70 Before using any functions invoke the nativez_OnLoad() function,
71 typically in the native library's JNI_OnLoad() function.
72
73 Any instance of a class derived from NativeZ must be created or
74 referenced using the NativeZ_* functions in order to partake of
75 automatic cleanup.
76
77 Native functions should take object arguments and resolve them to
78 native pointers using NativeZ_getP().
79
80 The nativez_* functions are just general JNI and useful cross-platform
81 utility functions which may be freely used within (any) JNI code.
82
83 See nativez.h for more information.
84
85 nativez-gen
86 -- - - - --
87
88 nativez provides a couple of functions for compact table based
89 resolution of shared library entry points from dynamically loaded
90 libraries, and for resolving Java classes and field and method
91 acccessors.
92
93 Whilst the tables can be generated manually nativez-gen can be used to
94 generate correct tables from a definition file.  When run on a
95 definition file it will create one or two pairs of static variables to
96 be included in the C file that uses it.
97
98 nativez-gen requires `perl' and the header section processing requires
99 `cproto'.
100
101 The definition file is made of any number of sections.  Each section
102 starts with a header which must be on the same line (including the
103 `{') and a number of entries each on their own line followed by a `}'.
104 Non-EOL whitespace is ignored. No quoting or escaping is available.
105
106 See also `src/notzed.nativez/jni/nativez.gen'.  It's dumb but somewhat
107 messy perl.
108
109 See also `src/notzed.nativez/jni/jni.make' for an example of how to
110 invoke it automatically.
111
112 java section
113 -  -- --  --
114
115 Each entry must be on a separate line as below.
116
117 java VarName com/package/name/ClassName {
118    static funcName, funcSig
119    funcName, funcSig
120    static fieldName,fieldSig
121    fieldName,fieldSig
122 }
123
124 VarName must be unique for each section in a single definition file.
125
126 The *Name* and *Sig values are those passed to the corresponding JNI
127 functions.  The static modifier calls the *Static* variaants.  A
128 funcSig will contain a pair of parentheses and a fieldSig will not.
129
130 For each java section the following definitions will be created:
131
132 static struct {
133         jclass VarName_classid;
134         jmethodID funcName_[encodedSig];
135         jmethodID funcName_[encodedSig];
136         jfieldID fieldName_[encodedSig];
137         jfieldID fieldName_[encodedSig];
138 } java;
139
140 static const char *java_names =
141         "#com/package/name/ClassName\0"
142         ":funcName\0funcSig\0"
143         ".funcName\0funcSig\0"
144         ";fieldName\0fieldSig\0"
145         ",fieldName\0fieldSig\0"
146         ;
147   
148 encodedSig depends on the arguments to nativez-gen.  By default for
149 functions a compact variation of JNI name mangling is used where the
150 primitive types are lowercased and any object types are converted to
151 'l' with all [ collapsed to nothing.  A longer option (--java-long) is
152 somewhat similar but not (current) quite the same as the JNI name
153 mangling and allows for overriden functions taking different object
154 types in the same position.
155
156 See the nativez-gen header for the rest of the options.
157
158 header section
159  --  -- --  --
160
161 A header section extracts prototypes from C .h header files and
162 creates a typesafe structure of same.
163
164 header libname path/header.h {
165    funcname_a
166    funcmame_b
167 }
168
169 libname is the name of the library as used in the
170 nativez_ResolveLibraries() table.  i.e. it's just a key and not the
171 actual name.
172
173 path/header.h should be the name as included directly in a C file,
174 i.e. it can be used direclty in a #include directive.  It is relative
175 to the (-b path) command line argument.
176
177 The contents of the section are just the function names required.
178
179 All header sections in a definition file will be combined to create a
180 pair of variables.  If one assumes a second section for libname2 is in
181 the file, this is an example output:
182
183 #inclulde <path/header.h>
184 #inclulde <path/header2.h>
185
186 static struct {
187         /* libname */
188         type (*funcname_a)(args);
189         type (*funcname_b)(args);
190         /* libname2 */
191         type (*funcname_c)(args);
192 } fn;
193
194 static const char *fn_names =
195         "#libname\0"
196         "funcname_a\0"
197         "funcname_b\0"
198         "@libname2\0"
199         "funcname_c\0"
200         ;
201
202 See the nativez-gen header for the options.
203
204 LICENSE
205 -------
206
207 This is supplied under the permissive 3-clause BSD license.  It allows
208 for commercial use.  See also notzed.nativez/legal/LICENSE.
209
210 java.make is covered by the GNU GPL Version 3 or later but is only
211 required at build time.
212
213  Copyright (C) 2018,2019 Michael Zucchi
214
215  Redistribution and use in source and binary forms, with or without
216  modification, are permitted provided that the following conditions are
217  met:
218
219      (1) Redistributions of source code must retain the above copyright
220      notice, this list of conditions and the following disclaimer. 
221
222      (2) Redistributions in binary form must reproduce the above copyright
223      notice, this list of conditions and the following disclaimer in
224      the documentation and/or other materials provided with the
225      distribution.  
226      
227      (3)The name of the author may not be used to
228      endorse or promote products derived from this software without
229      specific prior written permission.
230  
231  THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
232  IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
233  WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
234  DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT,
235  INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
236  (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
237  SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
238  HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
239  STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING
240  IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
241  POSSIBILITY OF SUCH DAMAGE. 
242