NotZed's Source Code Repository - panamaz/blob - 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.