toad-java

This repo contains the Java & Scala APIs for the toad CoAP network runtime.

Developing

Developing - Clone

> git clone git@github.com:toad-lib/toad-java toad-java
> cd toad-java

Developing - Tooling

Developing - Tooling - System

If on a minimal os (ex. bare debian image) install if not present:

• a C compiler, examples:
  • debian apt install gcc
  • macos brew install gcc
  • macos - xcode commandline tools
• openssl, examples:
  • debian apt install libssl-dev
  • macos brew install openssl
• (debian only) apt install pkg-config

Developing - Tooling - asdf

this repo is configured to use asdf for managing versions of rust, the JVM, and coursier used by this project.

To use it follow the asdf installation guide then run the following in bash or zsh in the directory you cloned the repo to:

> asdf install
> asdf plugin add java     # skip if you have system install of JDK version 20
> asdf plugin add rust     # skip if you have system install of Rust
> asdf plugin add coursier # skip if you have system install of coursier

Developing - Tooling - Manual

• install openjdk or equivalent version 20 or higher
  • after installing, ensure that $JAVA_HOME correctly refers to JDK 20 (java -version should output openjdk version "20" 202x-xx-xx)
• install coursier
• install rust

Developing - Tooling - sbt

After following the above steps, add coursier-installed binaries to your PATH, ex with:

> echo 'export PATH=$PATH:/root/.local/share/coursier/bin' >> ~/.zshrc

Then install sbt

> coursier install sbt

Developing - Rust

There is a non-trivial amount of nasty glue code necessary to support the interop between toad (a rust library) and toad-java (a java project).

There is a published library toad-jni which contains general abstractions that are useful for this project and may be useful to others. This includes things like "high-level rust struct for java.util.ArrayList doing nice things like implementing Iterator."

Separately is a rust project in this repository, ./glue/. This is not a published crate and is instead source code for a shared library specifically to implement native java methods in this java project.

Development tips specific to the glue lib can be found in ./glue/README.md.

Developing - Build

the sbt command compile (sbt compile or compile in the sbt shell) is the only required build step for this project.

sbt compile can be broken into the following steps:

1. run javac to generate C headers for java files with native function requirements
2. dump the headers into ./target/native/debug/
   • (dual purpose; a native interface available to manually cross-check against the hard rust implementation, as well as providing an interface to the built library artifact)
3. run cargo build within ./glue/ (builds to ./target/native/)
4. run cargo test within ./glue/
5. build java & scala sources to ./target/

Tests

todo