Jni-rs is open to any contributions, whether it is a feedback on existing features, a request for a new one, a bug report or a pull request. This document describes how to work with this project:
You need to install the following dependencies:
To build jni-rs, simply run
cargo build
inside project root directory. You can also build the library in release mode by adding --release flag.
Unit tests are typically placed at the bottom of their module file. E.g. unit tests of signature module. Tests are wrapped in private module with test attribute:
#[cfg(test)] mod test { use super::*; #[test] fn first_test() { /* ... */ } // More tests... }
Integration tests are in tests directory. They use the same pattern as unit tests, but split into several files instead of private modules. Integration tests use jni-rs as every other Rust application — by importing library using extern crate keyword.
extern crate jni; use jni::*;
Integration tests typically require running a JVM, so you should add #![cfg(feature = "invocation")] at the top of the file. You can use helper methods from util module to run JVM.
Keep in mind, that only one JVM can be run per process. Therefore, tests that need to launch it with different parameters have to be placed in different source files. Cargo runs tests from different modules in parallel.
Benchmarks are in benches directory. As integration tests, they require launching a JVM from native.
Doc tests are rarely used, but they allow to efficiently test some functionality by providing an example of its usage. Consult Rust documentation for more info about writing these tests.
As some tests need to launch a JVM, add a directory with JVM library that you want to use to LD_LIBRARY_PATH on Linux/Mac or PATH environment variable on Windows. On Linux/Mac, you can use the following script for this purpose:
source test_profile
To run all tests, execute the following command:
cargo test --features=invocation
This command will run all tests, including unit, integration and documentation tests.
To run all benchmarks, execute the following command (nightly Rust required):
cargo +nightly bench --features=invocation
They might help you to see the performance differences between two API flavours: checked and unchecked, and pick the right one for your application.
Rust code follows the Rust style guide. rustfmt enforces the code style.
After installation, you can run it with
cargo fmt --all -- --check
Every public entry of the API must be thoroughly documented and covered with tests if it is possible. You can use JNI specification as a reference for how to write detailed documentation.
Do not forget to update project guides and tutorials along with documentation.
To open local documentation of the project, you can use the following command:
cargo doc --open
Use Github Issues to submit an issue, whether it is a question, some feedback, a bug or a feature request: https://github.com/jni-rs/jni-rs/issues/new
Before starting to work on a PR, please submit an issue describing the intended changes. Chances are — we are already working on something similar. If not — we can then offer some help with the requirements, design, implementation or documentation.
It’s fine to open a PR as soon as you need any feedback — ask any questions in the description.
Licensed under either of
Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion is the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.