Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/bytedeco/javacpp-presets
The missing Java distribution of native C++ libraries
https://github.com/bytedeco/javacpp-presets
android java javacpp-presets maven native-libraries python
Last synced: 5 days ago
JSON representation
The missing Java distribution of native C++ libraries
- Host: GitHub
- URL: https://github.com/bytedeco/javacpp-presets
- Owner: bytedeco
- License: other
- Created: 2014-04-21T13:19:55.000Z (almost 11 years ago)
- Default Branch: master
- Last Pushed: 2025-01-14T09:57:30.000Z (19 days ago)
- Last Synced: 2025-01-20T20:09:47.457Z (13 days ago)
- Topics: android, java, javacpp-presets, maven, native-libraries, python
- Language: Java
- Homepage:
- Size: 702 MB
- Stars: 2,697
- Watchers: 125
- Forks: 750
- Open Issues: 258
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE.txt
Awesome Lists containing this project
README
JavaCPP Presets
===============
[](https://gitter.im/bytedeco/javacpp) [](https://maven-badges.herokuapp.com/maven-central/org.bytedeco/javacpp-presets) [](http://bytedeco.org/builds/)
Build status for all platforms (Android, iOS, Linux, Mac OS X, Windows):
[](https://github.com/bytedeco/javacpp-presets/actions?query=workflow%3Aopencv)
[](https://github.com/bytedeco/javacpp-presets/actions?query=workflow%3Affmpeg)
[](https://github.com/bytedeco/javacpp-presets/actions?query=workflow%3Aflycapture)
[](https://github.com/bytedeco/javacpp-presets/actions?query=workflow%3Aspinnaker)
[](https://github.com/bytedeco/javacpp-presets/actions?query=workflow%3Alibdc1394)
[](https://github.com/bytedeco/javacpp-presets/actions?query=workflow%3Alibfreenect)
[](https://github.com/bytedeco/javacpp-presets/actions?query=workflow%3Alibfreenect2)
[](https://github.com/bytedeco/javacpp-presets/actions?query=workflow%3Alibrealsense)
[](https://github.com/bytedeco/javacpp-presets/actions?query=workflow%3Alibrealsense2)
[](https://github.com/bytedeco/javacpp-presets/actions?query=workflow%3Avideoinput)
[](https://github.com/bytedeco/javacpp-presets/actions?query=workflow%3Aartoolkitplus)
[](https://github.com/bytedeco/javacpp-presets/actions?query=workflow%3Achilitags)
[](https://github.com/bytedeco/javacpp-presets/actions?query=workflow%3Aflandmark)
[](https://github.com/bytedeco/javacpp-presets/actions?query=workflow%3Aarrow)
[](https://github.com/bytedeco/javacpp-presets/actions?query=workflow%3Ahdf5)
[](https://github.com/bytedeco/javacpp-presets/actions?query=workflow%3Ahyperscan)
[](https://github.com/bytedeco/javacpp-presets/actions?query=workflow%3Alz4)
[](https://github.com/bytedeco/javacpp-presets/actions?query=workflow%3Amkl)
[](https://github.com/bytedeco/javacpp-presets/actions?query=workflow%3Amkl-dnn)
[](https://github.com/bytedeco/javacpp-presets/actions?query=workflow%3Adnnl)
[](https://github.com/bytedeco/javacpp-presets/actions?query=workflow%3Aopenblas)
[](https://github.com/bytedeco/javacpp-presets/actions?query=workflow%3Aarpack-ng)
[](https://github.com/bytedeco/javacpp-presets/actions?query=workflow%3Acminpack)
[](https://github.com/bytedeco/javacpp-presets/actions?query=workflow%3Afftw)
[](https://github.com/bytedeco/javacpp-presets/actions?query=workflow%3Agsl)
[](https://github.com/bytedeco/javacpp-presets/actions?query=workflow%3Acpython)
[](https://github.com/bytedeco/javacpp-presets/actions?query=workflow%3Anumpy)
[](https://github.com/bytedeco/javacpp-presets/actions?query=workflow%3Ascipy)
[](https://github.com/bytedeco/javacpp-presets/actions?query=workflow%3Agym)
[](https://github.com/bytedeco/javacpp-presets/actions?query=workflow%3Allvm)
[](https://github.com/bytedeco/javacpp-presets/actions?query=workflow%3Alibffi)
[](https://github.com/bytedeco/javacpp-presets/actions?query=workflow%3Alibpostal)
[](https://github.com/bytedeco/javacpp-presets/actions?query=workflow%3Alibraw)
[](https://github.com/bytedeco/javacpp-presets/actions?query=workflow%3Aleptonica)
[](https://github.com/bytedeco/javacpp-presets/actions?query=workflow%3Atesseract)
[](https://github.com/bytedeco/javacpp-presets/actions?query=workflow%3Acaffe)
[](https://github.com/bytedeco/javacpp-presets/actions?query=workflow%3Aopenpose)
[](https://github.com/bytedeco/javacpp-presets/actions?query=workflow%3Acuda)
[](https://github.com/bytedeco/javacpp-presets/actions?query=workflow%3Anvcodec)
[](https://github.com/bytedeco/javacpp-presets/actions?query=workflow%3Aopencl)
[](https://github.com/bytedeco/javacpp-presets/actions?query=workflow%3Amxnet)
[](https://github.com/bytedeco/javacpp-presets/actions?query=workflow%3Apytorch)
[](https://github.com/bytedeco/javacpp-presets/actions?query=workflow%3Asentencepiece)
[](https://github.com/bytedeco/javacpp-presets/actions?query=workflow%3Atensorflow)
[](https://github.com/bytedeco/javacpp-presets/actions?query=workflow%3Atensorflow-lite)
[](https://github.com/bytedeco/javacpp-presets/actions?query=workflow%3Atensorrt)
[](https://github.com/bytedeco/javacpp-presets/actions?query=workflow%3Atritonserver)
[](https://github.com/bytedeco/javacpp-presets/actions?query=workflow%3Aale)
[](https://github.com/bytedeco/javacpp-presets/actions?query=workflow%3Adepthai)
[](https://github.com/bytedeco/javacpp-presets/actions?query=workflow%3Aonnx)
[](https://github.com/bytedeco/javacpp-presets/actions?query=workflow%3Angraph)
[](https://github.com/bytedeco/javacpp-presets/actions?query=workflow%3Aonnxruntime)
[](https://github.com/bytedeco/javacpp-presets/actions?query=workflow%3Atvm)
[](https://github.com/bytedeco/javacpp-presets/actions?query=workflow%3Abullet)
[](https://github.com/bytedeco/javacpp-presets/actions?query=workflow%3Aliquidfun)
[](https://github.com/bytedeco/javacpp-presets/actions?query=workflow%3Aqt)
[](https://github.com/bytedeco/javacpp-presets/actions?query=workflow%3Askia)
[](https://github.com/bytedeco/javacpp-presets/actions?query=workflow%3Acpu_features)
[](https://github.com/bytedeco/javacpp-presets/actions?query=workflow%3Amodsecurity)
[](https://github.com/bytedeco/javacpp-presets/actions?query=workflow%3Asystems)
Commercial support and paid services for custom presets: [](https://xscode.com/bytedeco/javacpp-presets)
Introduction
------------
The JavaCPP Presets modules contain Java configuration and interface classes for widely used C/C++ libraries. The configuration files in the `org.bytedeco..presets` packages are used by the `Parser` to create from C/C++ header files the Java interface files targeting the `org.bytedeco.` packages, which in turn are used by the `Generator` and the native C++ compiler to produce the required JNI libraries. Moreover, helper classes make their functionality easier to use on the Java platform, including Android.
For orientation purposes, the documentation of this repository can be thought of as being split into 2 levels:
1. The directory where this parent README.md document is located belongs to the upper level, the `javacpp-presets` module itself, and
2. The subdirectories in it are the actual child modules, with their README.md files, presets, and packages, as the lower level.
This parent README.md file contains general information applicable to all modules to solve issues concerning downloads, common requirements, installation procedures, and build instructions. The respective README.md files in each subdirectory contain extra information, links, and notes concerning API documentation, specific requirements, dependencies for `pom.xml` files, and sample usage code, for the presets and packages of each module. Please be aware that not all of the presets have the same level of maturity, and the style and layout may also differ from one to another since they are based on the APIs of third-party libraries.
Please refer to the wiki page for more information about how to [create new presets](https://github.com/bytedeco/javacpp-presets/wiki/Create-New-Presets). Since additional documentation is currently lacking, please also feel free to ask questions on [the mailing list](http://groups.google.com/group/javacpp-project) or [the discussion forum](https://github.com/bytedeco/javacpp-presets/discussions).
Downloads
---------
JAR files containing binaries for all child modules and builds for all supported platforms (Android, iOS, Linux, Mac OS X, and Windows) can be obtained from the [Maven Central Repository](http://search.maven.org/#search|ga|1|bytedeco). Archives containing these JAR files are also available as [releases](https://github.com/bytedeco/javacpp-presets/releases).
To install manually the JAR files, follow the instructions in the [Manual Installation](#manual-installation) section below.
We can also have everything downloaded and installed automatically with:
* Maven (inside the `pom.xml` file)
```xml
org.bytedeco
${moduleName}-platform
${moduleVersion}-1.5.11
```
* Gradle (inside the `build.gradle.kts` or `build.gradle` file)
```groovy
dependencies {
implementation("org.bytedeco:$moduleName-platform:$moduleVersion-1.5.11")
}
```
* Leiningen (inside the `project.clj` file)
```clojure
:dependencies [
[~(symbol (str "org.bytedeco/" moduleName "-platform")) ~(str moduleVersion "-1.5.11")]
]
```
* sbt (inside the `build.sbt` file)
```scala
libraryDependencies += "org.bytedeco" % moduleName + "-platform" % moduleVersion + "-1.5.11"
```
where the `moduleName` and `moduleVersion` variables correspond to the desired module. This downloads binaries for all platforms, but to get binaries for only one platform we can set the `javacpp.platform` system property (via the `-D` command line option) to something like `android-arm`, `linux-x86_64`, `macosx-x86_64`, `windows-x86_64`, etc. We can also specify more than one platform, see the examples at [Reducing the Number of Dependencies](https://github.com/bytedeco/javacpp-presets/wiki/Reducing-the-Number-of-Dependencies). Another option available to Gradle users is [Gradle JavaCPP](https://github.com/bytedeco/gradle-javacpp), and similarly for Scala users there is [SBT-JavaCPP](https://github.com/bytedeco/sbt-javacpp).
Required Software
-----------------
To use the JavaCPP Presets, you will need to download and install the following software:
* An implementation of Java SE 7 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/
Further, in the case of Android, the JavaCPP Presets also rely on:
* Android SDK API 24 or newer http://developer.android.com/sdk/
Manual Installation
-------------------
Simply put all the desired JAR files (`opencv*.jar`, `ffmpeg*.jar`, etc.), in addition to `javacpp.jar`, somewhere in your class path. The JAR files available as pre-built artifacts are meant to be used with [JavaCPP](https://github.com/bytedeco/javacpp). The binaries for Linux are built with Ubuntu, so they should work on most distributions currently in use. Here are some more specific instructions for common cases:
NetBeans (Java SE 7 or newer):
1. In the Projects window, right-click the Libraries node of your project, and select "Add JAR/Folder...".
2. Locate the JAR files, select them, and click OK.
Eclipse (Java SE 7 or newer):
1. Navigate to Project > Properties > Java Build Path > Libraries and click "Add External JARs...".
2. Locate the JAR files, select them, and click OK.
Visual Studio Code (Java SE 7 or newer):
1. Navigate to Java Projects > Referenced Libraries, and click `+`.
2. Locate the JAR files, select them, and click OK.
IntelliJ IDEA (Android 7.0 or newer):
1. Follow the instructions on this page: http://developer.android.com/training/basics/firstapp/
2. Copy all the JAR files into the `app/libs` subdirectory.
3. Navigate to File > Project Structure > app > Dependencies, click `+`, and select "2 File dependency".
4. Select all the JAR files from the `libs` subdirectory.
After that, we can access almost transparently the corresponding C/C++ APIs through the interface classes found in the `org.bytedeco.` packages. Indeed, the `Parser` translates the code comments from the C/C++ header files into the Java interface files, (almost) ready to be consumed by Javadoc. However, since their translation still leaves to be desired, one may wish to refer to the original documentation pages. For instance, the ones for OpenCV and FFmpeg can be found online at:
* [OpenCV documentation](http://docs.opencv.org/master/)
* [FFmpeg documentation](http://ffmpeg.org/doxygen/trunk/)
Build Instructions
------------------
If the binary files available above are not enough for your needs, you might need to rebuild them from the source code. To this end, project files on the Java side were created as [Maven modules](#the-maven-modules). By default, the Maven build also installs the native libraries on the native C/C++ side with the [`cppbuild.sh` scripts](#the-cppbuildsh-scripts), but they can also be installed by other means.
Additionally, one can find on the wiki page additional information about the recommended [build environments](https://github.com/bytedeco/javacpp-presets/wiki/Build-Environments) for the major platforms.
### The Maven modules
The JavaCPP Presets depend on Maven, a powerful build system for Java, so before attempting a build, be sure to install and read up on:
* Maven 3.x http://maven.apache.org/download.html
* JavaCPP 1.5.11 https://github.com/bytedeco/javacpp
Each child module in turn relies by default on the included [`cppbuild.sh` scripts](#the-cppbuildsh-scripts), explained below, to install its corresponding native libraries in the `cppbuild` subdirectory. To use native libraries already installed somewhere else on the system, other installation directories than `cppbuild` can also be specified either in the `pom.xml` files or in the `.java` configuration files. The following versions are supported:
* OpenCV 4.11.x https://opencv.org/releases/
* FFmpeg 7.1.x http://ffmpeg.org/download.html
* FlyCapture 2.13.x https://www.flir.com/products/flycapture-sdk
* Spinnaker 4.0.x https://www.flir.com/products/spinnaker-sdk
* libdc1394 2.2.6 http://sourceforge.net/projects/libdc1394/files/
* libfreenect 0.5.7 https://github.com/OpenKinect/libfreenect
* libfreenect2 0.2.0 https://github.com/OpenKinect/libfreenect2
* librealsense 1.12.x https://github.com/IntelRealSense/librealsense
* librealsense2 2.53.x https://github.com/IntelRealSense/librealsense
* videoInput 0.200 https://github.com/ofTheo/videoInput/
* ARToolKitPlus 2.3.1 https://launchpad.net/artoolkitplus
* Chilitags https://github.com/chili-epfl/chilitags
* flandmark 1.07 https://github.com/uricamic/flandmark
* Arrow 6.0.x https://arrow.apache.org/install/
* HDF5 1.14.x https://www.hdfgroup.org/downloads/
* Hyperscan 5.4.x https://github.com/intel/hyperscan
* LZ4 1.9.x https://github.com/lz4/lz4
* MKL 2025.x https://software.intel.com/mkl
* MKL-DNN 0.21.x https://github.com/oneapi-src/oneDNN
* DNNL 3.6.x https://github.com/oneapi-src/oneDNN
* OpenBLAS 0.3.28 http://www.openblas.net/
* ARPACK-NG 3.9.x https://github.com/opencollab/arpack-ng
* CMINPACK 1.3.11 https://github.com/devernay/cminpack
* FFTW 3.3.10 http://www.fftw.org/download.html
* GSL 2.8 http://www.gnu.org/software/gsl/#downloading
* CPython 3.13.x https://www.python.org/downloads/
* NumPy 2.2.x https://github.com/numpy/numpy
* SciPy 1.15.x https://github.com/scipy/scipy
* Gym 0.26.x https://github.com/openai/gym
* LLVM 19.1.x http://llvm.org/releases/download.html
* libffi 3.4.x https://github.com/libffi/libffi
* libpostal 1.1 https://github.com/openvenues/libpostal
* LibRaw 0.21.x https://www.libraw.org/download
* Leptonica 1.85.x http://www.leptonica.org/download.html
* Tesseract 5.5.x https://github.com/tesseract-ocr/tesseract
* Caffe 1.0 https://github.com/BVLC/caffe
* OpenPose 1.7.0 https://github.com/CMU-Perceptual-Computing-Lab/openpose
* CUDA 12.6.x https://developer.nvidia.com/cuda-downloads
* cuDNN 9.5.x https://developer.nvidia.com/cudnn
* NCCL 2.23.x https://developer.nvidia.com/nccl
* nvCOMP 4.1.x https://developer.nvidia.com/nvcomp
* NVIDIA Video Codec SDK 12.2.x https://developer.nvidia.com/nvidia-video-codec-sdk
* OpenCL 3.0.x https://github.com/KhronosGroup/OpenCL-ICD-Loader
* MXNet 1.9.x https://github.com/apache/incubator-mxnet
* PyTorch 2.5.x https://github.com/pytorch/pytorch
* SentencePiece 0.2.0 https://github.com/google/sentencepiece
* TensorFlow 1.15.x https://github.com/tensorflow/tensorflow
* TensorFlow Lite 2.18.x https://github.com/tensorflow/tensorflow
* TensorRT 10.6.x https://developer.nvidia.com/tensorrt
* Triton Inference Server 2.51.x https://developer.nvidia.com/nvidia-triton-inference-server
* The Arcade Learning Environment 0.8.x https://github.com/mgbellemare/Arcade-Learning-Environment
* DepthAI 2.24.x https://github.com/luxonis/depthai-core
* ONNX 1.17.x https://github.com/onnx/onnx
* nGraph 0.26.0 https://github.com/NervanaSystems/ngraph
* ONNX Runtime 1.20.x https://github.com/microsoft/onnxruntime
* TVM 0.18.x https://github.com/apache/tvm
* Bullet Physics SDK 3.25 https://pybullet.org
* LiquidFun http://google.github.io/liquidfun/
* Qt 5.15.x https://download.qt.io/archive/qt/
* Mono/Skia 2.88.x https://github.com/mono/skia
* cpu_features 0.7.0 https://github.com/google/cpu_features
* ModSecurity 3.0.x https://github.com/SpiderLabs/ModSecurity
* System APIs of the build environments:
* Linux (glibc) https://www.gnu.org/software/libc/
* Mac OS X (XNU libc) https://opensource.apple.com/
* Windows (Win32) https://developer.microsoft.com/en-us/windows/
Once everything installed and configured, simply execute
```bash
$ mvn install --projects .,opencv,ffmpeg,etc. -Djavacpp.platform.root=/path/to/android-ndk/
```
inside the directory containing the parent `pom.xml` file, by specifying only the desired child modules in the command, but **without the leading period "." in the comma-separated list of projects, the parent `pom.xml` file itself might not get installed.** (The `-Djavacpp.platform.root=...` option is required only for Android builds.) Also specify `-Djavacpp.cppbuild.skip` as option to skip the execution of the `cppbuild.sh` scripts. In addition to `-Djavacpp.platform=...`, some of the presets can also be built against CUDA with `-Djavacpp.platform.extension=-gpu` or CPython with `-Djavacpp.platform.extension=-python`. Please refer to the comments inside the `pom.xml` file for further details. From the "platform" subdirectory, we can also install the "platform" artifacts with a similar command:
```bash
$ cd platform
$ mvn install --projects ../opencv/platform,../ffmpeg/platform,etc. -Djavacpp.platform.host
```
### The `cppbuild.sh` scripts
Running the scripts allows us to install easily the native libraries on multiple platforms, but additional software is required:
* A recent version of Linux, Mac OS X, or Windows with MSYS and Visual Studio
* Android NDK r18 or newer http://developer.android.com/ndk/downloads/ (required only for Android builds)
With the above in working order, the scripts get launched automatically as part of the Maven build lifecycle, but we can also manually execute
```bash
$ ANDROID_NDK=/path/to/android-ndk/ bash cppbuild.sh [-platform ] [-extension ] [projects]
```
where possible platform names are:
* `android-arm`
* `android-arm64`
* `android-x86`
* `android-x86_64`
* `ios-arm64`
* `ios-x86_64`
* `linux-armhf`
* `linux-arm64`
* `linux-ppc64le`
* `linux-x86`
* `linux-x86_64`
* `macosx-arm64`
* `macosx-x86_64`
* `windows-x86`
* `windows-x86_64`
The `-gpu` extension as supported by some builds also require CUDA to be installed. (The `ANDROID_NDK` variable is required only for Android builds.) Please note that the scripts download source archives from appropriate sites as necessary.
To compile binaries for an Android device with no FPU, first make sure this is what you want. Without FPU, the performance of either OpenCV or FFmpeg is bound to be unacceptable. If you still wish to continue down that road, then replace "armeabi-v7a" by "armeabi" and "-march=armv7-a -mfloat-abi=softfp -mfpu=vfpv3-d16" with "-march=armv5te -mtune=xscale -msoft-float", inside various files.
Although JavaCPP can pick up native libraries installed on the system, the scripts exist to facilitate the build process across multiple platforms. They also allow JavaCPP to copy the native libraries and load them at runtime from the JAR files created above by Maven, a useful feature for standalone applications or Java applets. Moreover, tricks such as the following work with JNLP:
```xml
```
Thanks to Jose Gómez for testing this out!
How Can I Help?
---------------
Contributions of any kind are highly welcome! At the moment, the `Parser` has limited capabilities, so I plan to improve it gradually to the point where it can successfully parse large C++ header files that are even more convoluted than the ones from OpenCV, Caffe, or TensorFlow, but the build system could also be improved. Consequently, I am looking for help especially with the five following tasks, in no particular order:
* Setting up continuous integration, preferably free on the cloud ([Travis CI](https://travis-ci.org/)?)
* Improving the `Parser` (by using the [presets for LLVM and Clang](llvm)?)
* Providing builds for more platforms, as with `linux-armhf` for [Raspberry Pi](https://www.raspberrypi.org/), etc.
* Replacing the Bash/Maven build combo by something easier to use ([Gradle](http://gradle.org/)?)
* Adding new presets as child modules for other C/C++ libraries (Caffe2, OpenNI, OpenMesh, PCL, etc.)
To contribute, please fork and create pull requests, or post your suggestions [as a new "issue"](https://github.com/bytedeco/javacpp-presets/issues). Thank you very much in advance for your contribution!
----
Project lead: Samuel Audet [samuel.audet `at` gmail.com](mailto:samuel.audet at gmail.com)
Developer site: https://github.com/bytedeco/javacpp-presets
Discussion group: http://groups.google.com/group/javacpp-project