< prev index next >

doc/panama_foreign.md

Print this page
rev 55895 : 8223033: panama_foreign.md should have a basic hello world example
Reviewed-by: TBA


   6 
   7 There are two ways to get a panama foreign branch JDK.
   8 
   9 1. Locally build "foreign" branch of panama repo [http://hg.openjdk.java.net/panama/dev/](http://hg.openjdk.java.net/panama/dev/)
  10 2. Download pre-built panama "foreign" early access binaries from [http://jdk.java.net/panama/](http://jdk.java.net/panama/)
  11 
  12 Using foreign function call in Java involves the following three steps:
  13 
  14 1. Use **jextract** tool to generate java interface for your C header file(s)
  15 2. Use **java.foreign** API to create ("bind") implementation for C header interfaces
  16 3. Invoke C functions via the jextracted Java interface
  17 
  18 ### Windows notes
  19 
  20 You will (almost always) need to have Visual Studio installed, since most libraries indirectly depend on Visual Studio runtime libraries and this currently means that jextract needs their header to extract successfully. Windows examples have been tested with [Build Tools for Visual Studio 2017](https://visualstudio.microsoft.com/downloads/#build-tools-for-visual-studio-2017).
  21 
  22 It is generally a good idea to give jextract a bunch of extra memory since a lot of big system headers are transitively included. The extra memory will make the jextract run significantly faster. Windows support was added only recently, and the memory usage of jextract has not been optimized yet, so this is a workaround. You can give extra memory by passing e.g. `-J-Xmx8G` to jextract as an additional argument, which in this example gives jextract 8 gigabytes of memory.
  23 
  24 Commands are tested in PowerShell.
  25 































































  26 ## Embedding Python interpreter in your Java program (Mac OS)
  27 
  28 ### jextract a Jar file for Python.h
  29 
  30 ```sh
  31 
  32 jextract -l python2.7 \
  33   -L /System/Library/Frameworks/Python.framework/Versions/2.7/lib --record-library-path \
  34   --exclude-symbols .*_FromFormatV\|_.*\|PyOS_vsnprintf\|.*_VaParse.*\|.*_VaBuild.*\|PyBuffer_SizeFromFormat\|vasprintf\|vfprintf\|vprintf\|vsprintf \
  35   -t org.python \
  36   /usr/include/python2.7/Python.h \
  37   -o python.jar
  38 
  39 ```
  40 
  41 ### Java program that uses extracted Python interface
  42 
  43 ```java
  44 
  45 // import java.foreign packages




   6 
   7 There are two ways to get a panama foreign branch JDK.
   8 
   9 1. Locally build "foreign" branch of panama repo [http://hg.openjdk.java.net/panama/dev/](http://hg.openjdk.java.net/panama/dev/)
  10 2. Download pre-built panama "foreign" early access binaries from [http://jdk.java.net/panama/](http://jdk.java.net/panama/)
  11 
  12 Using foreign function call in Java involves the following three steps:
  13 
  14 1. Use **jextract** tool to generate java interface for your C header file(s)
  15 2. Use **java.foreign** API to create ("bind") implementation for C header interfaces
  16 3. Invoke C functions via the jextracted Java interface
  17 
  18 ### Windows notes
  19 
  20 You will (almost always) need to have Visual Studio installed, since most libraries indirectly depend on Visual Studio runtime libraries and this currently means that jextract needs their header to extract successfully. Windows examples have been tested with [Build Tools for Visual Studio 2017](https://visualstudio.microsoft.com/downloads/#build-tools-for-visual-studio-2017).
  21 
  22 It is generally a good idea to give jextract a bunch of extra memory since a lot of big system headers are transitively included. The extra memory will make the jextract run significantly faster. Windows support was added only recently, and the memory usage of jextract has not been optimized yet, so this is a workaround. You can give extra memory by passing e.g. `-J-Xmx8G` to jextract as an additional argument, which in this example gives jextract 8 gigabytes of memory.
  23 
  24 Commands are tested in PowerShell.
  25 
  26 ## Hello World
  27 
  28 ### Hello World C Header
  29 
  30 ```C
  31 
  32 #ifndef helloworld_h
  33 #define helloworld_h
  34 
  35 extern void helloworld(void);
  36 
  37 ```
  38 
  39 ### Hello World C Source
  40 
  41 ```C
  42 
  43 #include <stdio.h>
  44 
  45 #include "helloworld.h"
  46 
  47 void helloworld(void) {
  48     printf("Hello World!\n");
  49 }
  50 
  51 ```
  52 
  53 ### jextract a Jar file for helloworld.h
  54 
  55 ```sh
  56 
  57 jextract -t org.hello -L . -lhelloworld --record-library-path helloworld.h -o helloworld.jar
  58 
  59 ```
  60 
  61 ### Java program that uses extracted helloworld interface
  62 
  63 ```java
  64 
  65 import org.hello.helloworld_lib;
  66 
  67 import static org.hello.helloworld_lib.*;
  68 
  69 public class HelloWorld {
  70     public static void main(String[] args) {
  71         try (Scope s = helloworld_lib.scope().fork()) {
  72             helloworld();
  73         }
  74     }
  75 }
  76 
  77 ```
  78 
  79 ### Running the Java code that invokes helloworld
  80 
  81 ```sh
  82 
  83 javac -cp helloworld.jar HelloWorld.java
  84 
  85 java -cp helloworld.jar:. HelloWorld
  86 
  87 ```
  88 
  89 ## Embedding Python interpreter in your Java program (Mac OS)
  90 
  91 ### jextract a Jar file for Python.h
  92 
  93 ```sh
  94 
  95 jextract -l python2.7 \
  96   -L /System/Library/Frameworks/Python.framework/Versions/2.7/lib --record-library-path \
  97   --exclude-symbols .*_FromFormatV\|_.*\|PyOS_vsnprintf\|.*_VaParse.*\|.*_VaBuild.*\|PyBuffer_SizeFromFormat\|vasprintf\|vfprintf\|vprintf\|vsprintf \
  98   -t org.python \
  99   /usr/include/python2.7/Python.h \
 100   -o python.jar
 101 
 102 ```
 103 
 104 ### Java program that uses extracted Python interface
 105 
 106 ```java
 107 
 108 // import java.foreign packages


< prev index next >