Skip to content

Latest commit

 

History

History
executable file
·
152 lines (101 loc) · 6.4 KB

rules.md

File metadata and controls

executable file
·
152 lines (101 loc) · 6.4 KB
Raw

jni_headers

load("@rules_jni//jni:defs.bzl", "jni_headers")

jni_headers(name, lib)

Generates the native headers for a java_library and exposes it to cc_* rules.

For every Java class com.example.Foo in the java_library target specified by lib that contains at least one function marked with native or constant annotated with @Native, the include directory exported by this rule will contain a file com_example_Foo.h that provides the C/C++ interface for this class. Consuming cc_* rules should have this rule added to their deps and can then access such a header file via:

#include "com_example_Foo.h"

This rule also directly exports the JNI header, which can be included via:

#include <jni.h>

Example:

load("@fmeum_rules_jni//jni:defs.bzl", "jni_headers")

java_library(
    name = "os_utils",
    ...
)

jni_headers(
    name = "os_utils_hdrs",
    lib = ":os_utils",
)

cc_library(
    name = "os_utils_impl",
    ...
    deps = [":os_utils_hdrs"],
)

ATTRIBUTES

Name Description Type Mandatory Default
name A unique name for this target. Name required
lib The Java library for which native header files should be generated. Label required

cc_jni_library

load("@rules_jni//jni:defs.bzl", "cc_jni_library")

cc_jni_library(name, platforms, cc_binary_args)

A native library that can be loaded by a Java application at runtime.

Add this target to the native_libs of a java_jni_library.

The native libraries are exposed as Java resources, which are placed in a Java package determined from the Bazel package of this target according to the Maven standard directory layout. If the library should be included in the com/example subdirectory of a deploy JAR, which corresponds to the Java package com.example, place it under one of the following Bazel package structures:

  • **/src/*/native/com/example (preferred)
  • **/src/*/resources/com/example
  • **/src/*/java/com/example
  • **/java/com/example

Note: Building a native library for multiple platforms by setting the platforms attribute to a non-empty list of platforms requires either remote execution or cross-compilation toolchains for the target platforms. As both require a more sophisticated Bazel setup, the following simpler process can be helpful for smaller or open-source projects:

  1. Leave the platforms attribute empty or unspecified.
  2. Build the deploy JAR of the Java library or application with all native libraries included separately for each target platform, for example using a CI platform.
  3. Manually (outside Bazel) merge the deploy JARs. The .class files will be identical and can thus safely be replaced, but the resulting JAR will include all versions of the native library and the correct version will be loaded at runtime.

An example of such a CI workflow can be found here.

PARAMETERS

Name Description Default Value
name A unique name for this target. none
platforms A list of platforms for which this native library should be built. If the list is empty (the default), the library is only built for the current target platform. []
cc_binary_args Any arguments to a cc_library, except for: linkshared (always True), linkstatic (always True), data (runfiles are not supported) none

java_jni_library

load("@rules_jni//jni:defs.bzl", "java_jni_library")

java_jni_library(name, native_libs, java_library_args)

A Java library that bundles one or more native libraries created with cc_jni_library.

To load a native library referenced in the native_libs argument, use the static methods of the RulesJni class, which is accessible for srcs of this target due to an implicit dependency on @fmeum_rules_jni//jni/tools/native_loader. These methods automatically choose the correct version of the library for the current OS and CPU architecture, if available.

The native libraries referenced in the native_libs argument are added as resources and are thus included in the deploy JARs of any java_binary depending on this target.

Implicit output targets

  • <name>.hdrs: The auto-generated JNI headers for this library.

    This target can be added to the deps of a cc_library or cc_jni_library. See jni_headers for a more detailed description of the underlying rule.

PARAMETERS

Name Description Default Value
name A unique name for this target. none
native_libs A list of cc_jni_library targets to include in this Java library. []
java_library_args Any arguments to a java_library. none