JavaCPP

<sup>Commercial support:</sup>

Introduction

JavaCPP provides efficient access to native C++ inside Java, not unlike the way some C/C++ compilers interact with assembly language. No need to invent new languages such as with SWIG, SIP, C++/CLI, Cython, or RPython. Instead, similar to what cppyy strives to do for Python, it exploits the syntactic and semantic similarities between Java and C++. Under the hood, it uses JNI, so it works with all implementations of Java SE, in addition to Android, Avian, and RoboVM (instructions).

More specifically, when compared to the approaches above or elsewhere (CableSwig, JNIGeneratorApp, cxxwrap, JNIWrapper, Platform Invoke, GlueGen, LWJGL Generator, JNIDirect, ctypes, JNA, JNIEasy, JniMarshall, JNative, J/Invoke, HawtJNI, JNR, BridJ, CFFI, fficxx, CppSharp, cgo, pybind11, rust-bindgen, Panama Native, etc.), it maps naturally and efficiently many common features afforded by the C++ language and often considered problematic, including overloaded operators, class and function templates, callbacks through function pointers, function objects (aka functors), virtual functions and member function pointers, nested struct definitions, variable length arguments, nested namespaces, large data structures containing arbitrary cycles, virtual and multiple inheritance, passing/returning by value/reference/string/vector, anonymous unions, bit fields, exceptions, destructors and shared or unique pointers (via either try-with-resources or garbage collection), and documentation comments. Obviously, neatly supporting the whole of C++ would require more work (although one could argue about the intrinsic neatness of C++), but we are releasing it here as a proof of concept.

As a case in point, we have already used it to produce complete interfaces to OpenCV, FFmpeg, libdc1394, PGR FlyCapture, OpenKinect, videoInput, ARToolKitPlus, Leptonica, Tesseract, GSL, LLVM, HDF5, MKL, CUDA, Caffe, MXNet, TensorFlow, System APIs, and others as part of the JavaCPP Presets subproject, also demonstrating early parsing capabilities of C/C++ header files that show promising and useful results.

Please feel free to ask questions on the mailing list or the discussion forum if you encounter any problems with the software! I am sure it is far from perfect...

Downloads

Archives containing JAR files are available as releases.

We can also have everything downloaded and installed automatically with:

Maven (inside the pom.xml file)

  <dependency>
    <groupId>org.bytedeco</groupId>
    <artifactId>javacpp</artifactId>
    <version>1.5.13</version>
  </dependency>

Gradle (inside the build.gradle.kts or build.gradle file)

  dependencies {
    implementation("org.bytedeco:javacpp:1.5.13")
  }

Leiningen (inside the project.clj file)

  :dependencies [
    [org.bytedeco/javacpp "1.5.13"]
  ]

sbt (inside the build.sbt file)

  libraryDependencies += "org.bytedeco" % "javacpp" % "1.5.13"

Another option available to Gradle users is Gradle JavaCPP, and similarly for Scala users there is SBT-JavaCPP.

Required Software

To use JavaCPP, you will need to download and install the following software:

An implementation of Java SE 8 or newer:
- OpenJDK http://openjdk.java.net/install/ or
- Oracle JDK http://www.oracle.com/technetwork/java/javase/downloads/ or
- IBM JDK http://www.ibm.com/developerworks/java/jdk/ or
- Microsoft JDK https://www.microsoft.com/openjdk etc
A C++11 compiler, out of which these have been tested:
- GNU C/C++ Compiler (Linux, etc.) http://gcc.gnu.org/
  - For Windows x86 and x64 http://mingw-w64.org/
- LLVM Clang (Mac OS X, etc.) http://clang.llvm.org/
- Microsoft C/C++ Compiler, part of Visual Studio https://visualstudio.microsoft.com/
  - https://docs.microsoft.com/en-us/cpp/build/walkthrough-compiling-a-native-cpp-program-on-the-command-line

To produce binary files for Android 7.0 or newer, you will also have to install:

Android NDK r18 or newer http://developer.android.com/ndk/downloads/

And similarly to target iOS, you will need to install either:

Gluon VM http://gluonhq.com/products/mobile/vm/ or
RoboVM 1.x or newer http://robovm.mobidevelop.com/downloads/

To modify the source code, please note that the project files were created for:

Maven 3.x http://maven.apache.org/download.html

Finally, because we are dealing with native code, bugs can easily crash the virtual machine. Luckily, the HotSpot VM provides some tools to help us debug under those circumstances:

Troubleshooting Guide for Java SE with HotSpot VM
- http://docs.oracle.com/javase/8/docs/technotes/guides/troubleshoot/

Getting Started

To understand how JavaCPP is meant to be used, one should first take a look at the Mapping Recipes for C/C++ Libraries, but a high-level overview of the Basic Architecture is also available to understand the bigger picture. The repository of the JavaCPP Presets further provides complex examples that we can use as templates, but it also includes a wiki page on how to Create New Presets that explains their structure in detail along with a small but complete sample project from which one can start experimenting with.

Key Use Cases

To implement native methods, JavaCPP generates appropriate code for JNI, and passes it to the C++ compiler to build a native library. At no point do we need to get our hands dirty with JNI, makefiles, or other native tools. The important thing to realize here is that, while we do all customization inside the Java language using annotations, JavaCPP produces code that has zero overhead compared to manually coded JNI functions (verify the generated .cpp files to convince yourself). Moreover, at runtime, the Loader.load() method automatically loads the native libraries from Java resources, which were placed in the right directory by the building process. They can even be archived in a JAR file, it changes nothing. Users simply do not need to figure out how to make the system load the files. These characteristics make JavaCPP suitable for either

accessing native APIs,
using complex C++ types,
optimizing code performance, or
creating callback functions.

In addition to the few examples provided below, to learn more about how to use the features of this tool, please refer to the Mapping Recipes for C/C++ Libraries as well as the source code of the JavaCPP Presets for examples. For more information about the API itself, one may refer

Javacpp

Install / Use

README