JWin32

A Project Panama-based mapping + wrapper generator for win32 headers.

IMPORTANT NOTICE

• I have migrated to GNU/Linux, and can no longer keep this project maintained. If anyone is willing to carry the torch, just open an issue and i will put a link to the fork at the top of this readme.
• This project only works on the incubator release of Panama on java 17. Java 19 has different classes for panama, so the project DOES NOT COMPILE ON JDK 19!

IMPORTANT

• As of 0.5.0, no prebuilt jars will be provided. You must generate the mappings yourself.

  This is due to the new modular header system, which makes it impractical to include prebuilt jars for every combination.

• Now accepting pull requests for implementing function macros. Jextract cannot extract these, so it requires manual labor. See the Macros file for examples.

Table of Contents

0. Disclaimer
1. What is Project Panama
2. Dependencies
3. Selecting libraries
4. Generating mappings, wrappers and jar
5. Running code with panama
6. Linking libraries
7. What next?
8. Inspiration
9. Detailed description of the postprocessor
10. Changelog

0. Disclaimer

This project is not endorsed by nor affiliated with either Microsoft, Oracle, nor the OpenJDK project.

MSVC, Windows.h, d3d11.h and the Windows SDK are owned by Microsoft, and due to licensing issues, are not included as a part of this source code.

The project source code does not include generated and mapped files because there's a lot of files (more than 10k after every class is generated)

Libraries with builtin support:

• windows.h and most of the stuff it pulls in
• direct3d 9-12
• dxgi

I'm considering adding more libraries as "supported by default", such as DirectAudio, Direct2D, etc (basically the entire DirectX collection), as well as later expanding into non-win32 space, such as GLFW and OpenGL (only planned once panama comes out of incubator and becomes an experimental/stable feature usable in mainline releases). During the incubator phase, this project will be limited to windows libraries.

Any other libraries are currently unverified and may break. The built-in COM support is only verified with Direct3D COM objects, and may break when used with the actual COM system. More precisely, RuntimeClass GUIDs and Interface GUIDs cannot be retrieved during runtime, and MUST be specified either using #define constants, or using the GUID_J class. There's no way around this limitation at this time.

1. What is Project Panama

Java's project panama is an incubating feature of java, only accessible on a specific branch, is a brand-new solution that gets rid of writing JNI or JNA wrappers for native libraries, and instead almost completely automates the process, or hides it behind neat and efficient wrapper classes.

• Project Panama: https://openjdk.java.net/projects/panama/
• Project Panama Builds: https://jdk.java.net/panama/

Important reading before experimenting:

• handling native memory: https://github.com/openjdk/panama-foreign/blob/foreign-jextract/doc/panama_memaccess.md
• handling native functions: https://github.com/openjdk/panama-foreign/blob/foreign-jextract/doc/panama_ffi.md

2. Dependencies

0. (Optional) Installing the Windows developer VM.

   There's a possibility of jextract failing due to a nonstandard system setup. In this case, you need to do the jextract phase inside the Windows 10 developer VM, or if you don't want to install the Windows sdk on your host OS. You still need the panama jdk on your host to run the rest of the steps.

   1. You need either VMWare, Hyper-V, VirtualBox, or Parallels. If you haven't installed one of those yet, VirtualBox is the recommended option, as it was the only one tested with this project: https://www.virtualbox.org/wiki/Downloads
   2. Download the Windows 10 developer VM image for you virtual machine: https://developer.microsoft.com/en-us/windows/downloads/virtual-machines/
   3. (VirtualBox only) Extract the WinDev....Eval.ova file from the archive you downloaded, inside VirtualBox, click on Import, select the ova file in the File box, click next, then Import. After that, virtualbox will begin importing the image.
   4. Start the developer virtual machine, download this repository inside it, then proceed with the following steps.

1. Project Panama

   If you're using the VM, you still need to install this both on the host and the VM.

   1. Download and extract JDK-panama from this URL: https://jdk.java.net/panama

      (The latest version at the time of writing is 17-panama+3-167)

   2. Next, you have to replace your currently installed java with Panama in the PATH and JAVA_HOME system variables:

      Inside PATH, replace your current java path with, or, if you don't have one, add: <Directory where you extracted panama>\jdk-17-panama\bin

      Set JAVA_HOME to: <Directory where you extracted panama>\jdk-17-panama

   3. To verify that panama has been added to PATH properly, open a command prompt, and type java - version. The first output line should start with openjdk version "17-panama".

   4. Also enter jextract -versioninto the same command prompt. If the output starts with WARNING: Using incubator modules: jdk.incubator.foreign, jdk.incubator.jextract, panama is correctly installed.

2. Maven (optional if your IDE doesn't have it, or you don't use and IDE)

   Note: You only need this on your host system, not inside the VM.

   1. Download and extract maven from this URL: https://maven.apache.org/download.cgi
   2. Add the maven bin directory to your PATH: <Directory where you extracted maven>\bin
   3. To verify that maven has been added to PATH properly, open a command prompt, and type mvn -version.
   4. If the output starts with Apache Maven, maven is correctly installed.

3. Windows SDK

   After you've installed project panama, you also need the header files that are then passed to jextract. If you're using the VM for the jextract step, you don't need the SDK on your host system, only on the VM.

   If you already have Visual Studio installed with Windows SDK (default if you checked Desktop development with C++ when installing VS), you can skip this dependency.

   Otherwise, you either have to install Visual Studio with the Desktop development with C++ workload.

   If you don't have VS installed yet:

   1. Go to https://visualstudio.microsoft.com/downloads/
   2. Scroll down to Visual Studio 2019
   3. Under Community, click the Free download button.
   4. Start the installer, and follow the instructions until you reach the workload selection screen.

   If you already have VS installed, just type visual studio installer in the start menu search and launch it. Then, click Modify to enter the workload selection menu.

   The following steps are the same for both:

   1. Select the Desktop development with C++ workload
   2. Click install and wait until it finishes (Approximately 2 GB download size, 8 GB on disk. Less if visual studio is already installed)

   At this point, restart your system to make sure that every program has the correct system variables available. (when running the VM, only restart the VM).

3. Selecting libraries to be made available in java

First off, go into the c directory, and open the native.h file. In this file you can configure what you want to include.

Currently, you can select the following:

• Windows.h configurations using #define NO... defines.
• Direct3D version. You can choose any combination of directx 9, 10, 11, or 12. You can also choose none of them.
• DXGI

4. Generating mappings, wrappers and jar

After 0.5.0, the build script was unified, and the entire process is now done in one go.

The build_install.bat script installs the compiled jar files into the local maven repository.

The build_package.bat script outputs the compiled jar files into the target directory.

You can safely ignore errors that match one of these examples:

• WARNING: Using incubator modules: jdk.incubator.jextract, jdk.incubator.foreign
• WARNING: Layout size not available for ...
• WARNING: skipping ... because of unsupported type usage: long ...

You can check the full list of all known non-issue warnings in JEXTRACT_WARNINGS.txt

If you see any other kinds of errors, go back to the dependency setup step, download the Windows 10 developer virtual machine, and redo the setup inside it. If it fails in the virtual machine too, only then should you create a new issue concerning this step.

The wrapper classes simplify interaction with structs and COM objects, and also turn many #defines into public static final variables, which can then be used in switch statements (jextract puts #defines into getter methods, which cannot be used with switch statements).

To do this, simply run one of the build_ batch files and wait until it finishes.

Wrapper classes are just the original struct/COM interface name with a _J suffix.

Wrapper code is placed in the win32.mapped package, more precisely, structs get put in win32.mapped.struct, COM interfaces in win32.mapped.com, and #defined constants in the win32.mapped.constants.Constants class.

5. Running code with panama

By default, foreign (native) access, even in Project Panama, is blocked. To solve this, you have to provide the following command line arguments to java when running programs that contain panama code: `-Dforeign.restricted=permit --enable-native-access=ALL-UNNAMED --