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