bdk-jni

⚠️⚠️ Notice ⚠️⚠️

This library is now unmaintained and was deprecated in favor of the newest bdk-android and bdk-jvm libraries. Please consider this repository an archive only.

Overview

This repository is home of two libraries, bdk-jvm and bdk-android. You can build bdk-jvm without building bdk-android, but bdk-android relies on the artifact built in bdk-jvm to function, so if you are building for Android you need to compile both libraries. Both rely on the test-fixtures project for testing.

Building both libraries

The minimum JDK version required to build this library is JDK 11. Make sure your JAVA_HOME env variable is set and java --version displays version 11 or above. The Rust version used to compile this library is 1.53.0.

If you haven't installed rust android targets first add those to your environment using rustup

rustup target add x86_64-apple-darwin x86_64-unknown-linux-gnu x86_64-linux-android aarch64-linux-android armv7-linux-androideabi i686-linux-android

Then make sure that you have an Android NDK installed (our Github CI is using 21.4.7075529, and that you have an ANDROID_NDK_HOME env variable set before you start building the library. Usually, if installed through the sdkmanager, your ANDROID_NDK_HOME will look more or less like this: /home/<user>/Android/Sdk/ndk/<version>/.

export ANDROID_NDK_HOME=/home/<user>/Android/Sdk/ndk/<NDK version, ie. 21.4.7075529>

Build and unit test jvm .jar and build android .aar libraries with:

./gradlew build

Test android .aar library connected unit tests with:

./gradlew :android:connectedDebugAndroidTest

Gradle will build automatically the native library with rust for all 4 platforms using NDK. You can choose to build only for a specific platform by setting the env variable BUILD_TARGETS to a comma-separated list containing one or more of the following items:

aarch64
armv7
x86_64
i686

The output aar library is available at ./android/build/outputs/aar.

To run the tests first launch a local android emulator from the Android Studio IDE or via the command line. If starting from the command line you will also need to set the ANDROID_SDK_ROOT env variable.

export ANDROID_SDK_ROOT=</home/<user>/Android/Sdk or where ever your Sdk is installed>

Publish .aar and .jar files to local maven repository

Use the below command to publish the jvm .jar and android .aar files generated by this project to your local maven2 repository (~/.m2/repository/org/bitcoindevkit/bdkjni/bdk-):

./gradlew :jvm:publishToMavenLocal
./gradlew :android:publishToMavenLocal

Once published you will see two new artifacts in your local maven repository:

~/.m2/repository/org/bitcoindevkit/bdkjni/bdk-jvm/<version>/bdk-jvm-<version>.jar
~/.m2/repository/org/bitcoindevkit/bdkjni/bdk-android/<version>/bdk-android-<version>.aar
~/.m2/repository/org/bitcoindevkit/bdkjni/bdk-android-debug/<version>/bdk-android-debug-<version>.aar

When you include the bdk-android.aar or bdk-android-debug.aar library in a local Android project the bdk-jvm.jar will also be included as a transitive dependency. To include dependencies from your local maven repository add mavenLocal() to the allprojects section of your project build.gradle file:

allprojects {
    repositories {
        mavenLocal()
        ...
    }
}

At the moment we recommend using the bdk-android-debug version of the library so it can be debugged and used locally in the IDE. Because you added your local Maven repository to your build.gradle file, you can now simply add bdk-android or bdk-android-debug to your app/build.gradle dependencies:

dependencies {
    implementation 'org.bitcoindevkit.bdkjni:bdk-android-debug:0.2.1-dev'
    ...
}

Using the `bdk-jvm` library

The bdk-jvm library will attempt to load the native library (the libbdk_jni.so file) when you call the Lib.load() method. You must put the native library in the path it searches by default or you provide a custom paths in order for the library to find the native library. Do do this, you can either:

Run the app without doing anything special and see the error thrown. You can then place the native library for your architecture (located in the /native-libs/target/<your architecture>/debug/ directory) in one of those locations
Define a LD_LIBRARY_PATH environment variable with a path to a location where you put the native library file
Call your application from the command line while providing a java.library.path variable.

Build just the native library

If you only want to build the native library, maybe for one single platform, you can do so with something like:

CARGO_TARGET_AARCH64_LINUX_ANDROID_LINKER="aarch64-linux-android21-clang" CC="aarch64-linux-android21-clang" cargo build --target=aarch64-linux-android

Make sure that the compiler from the NDK is in your PATH

If the library is built in debug mode, there should already be a symlink from ./target/debug//libbdk_jni.so to the jniLibs directory, otherwise manually copy the shared object.

License

Licensed under either of

Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)

at your option.

bitcoindevkit/bdk-jni