166 lines
5.0 KiB
Markdown
166 lines
5.0 KiB
Markdown
# Jni-rs Contribution Guide
|
||
|
||
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:
|
||
|
||
* how to [build](#how-to-build) it
|
||
* how to [test](#tests) it
|
||
* the [code style guidelines](#the-code-style)
|
||
* how to [submit an issue](#submitting-issues)
|
||
* how to [submit a PR](#submitting-pull-requests).
|
||
|
||
## How to Build
|
||
|
||
### System Dependencies
|
||
|
||
You need to install the following dependencies:
|
||
|
||
* [JDK 1.8+](http://jdk.java.net/10/).
|
||
* [Rust (latest stable)](https://www.rust-lang.org/).
|
||
|
||
### Building
|
||
|
||
To build `jni-rs`, simply run
|
||
|
||
```$sh
|
||
cargo build
|
||
```
|
||
|
||
inside project root directory. You can also build the library in release mode by
|
||
adding `--release` flag.
|
||
|
||
## Tests
|
||
|
||
### Categories of Tests
|
||
|
||
* Unit tests are typically placed at the bottom of their module file.
|
||
E.g. [unit tests of signature module](src/wrapper/signature.rs). Tests are wrapped
|
||
in private module with `test` attribute:
|
||
|
||
```rust
|
||
#[cfg(test)]
|
||
mod test {
|
||
use super::*;
|
||
|
||
#[test]
|
||
fn first_test() { /* ... */ }
|
||
|
||
// More tests...
|
||
}
|
||
```
|
||
|
||
* Integration tests are in [tests directory](tests). 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.
|
||
|
||
```rust
|
||
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](tests/util/mod.rs) 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](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](https://doc.rust-lang.org/beta/rustdoc/documentation-tests.html)
|
||
for more info about writing these tests.
|
||
|
||
### Running Tests
|
||
|
||
#### Setup Environment
|
||
|
||
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:
|
||
|
||
```$sh
|
||
source test_profile
|
||
```
|
||
|
||
#### Run Tests
|
||
|
||
To run all tests, execute the following command:
|
||
|
||
```$sh
|
||
cargo test --features=invocation
|
||
```
|
||
|
||
This command will run all tests, including unit, integration and documentation
|
||
tests.
|
||
|
||
#### Run Benchmarks
|
||
|
||
To run all benchmarks, execute the following command (nightly Rust required):
|
||
|
||
```$sh
|
||
cargo +nightly bench --features=invocation
|
||
```
|
||
|
||
They might help you to see the performance differences between
|
||
two [API flavours][checked-unchecked]: checked and unchecked, and
|
||
pick the right one for your application.
|
||
|
||
[checked-unchecked]: https://docs.rs/jni/0.19.0/jni/struct.JNIEnv.html#checked-and-unchecked-methods
|
||
|
||
## The Code Style
|
||
|
||
Rust code follows the [Rust style guide](https://github.com/rust-lang-nursery/fmt-rfcs/blob/master/guide/guide.md).
|
||
[`rustfmt`](https://github.com/rust-lang-nursery/rustfmt) enforces the code style.
|
||
|
||
After installation, you can run it with
|
||
|
||
```$sh
|
||
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](https://docs.oracle.com/javase/10/docs/specs/jni/index.html) 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:
|
||
|
||
```$sh
|
||
cargo doc --open
|
||
```
|
||
|
||
## Submitting Issues
|
||
|
||
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>
|
||
|
||
## Submitting Pull Requests
|
||
|
||
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.
|
||
|
||
## License
|
||
|
||
Licensed under either of
|
||
|
||
* Apache License, Version 2.0 ([LICENSE-APACHE](LICENSE-APACHE) or
|
||
<http://www.apache.org/licenses/LICENSE-2.0>)
|
||
* MIT license ([LICENSE-MIT](LICENSE-MIT) or <http://opensource.org/licenses/MIT>)
|
||
at your option.
|
||
|
||
### Contributor License Agreement
|
||
|
||
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.
|