diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index c0e82042..fabf2b74 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -59,6 +59,15 @@ jobs: - name: Gradle Test run: gradle jvmTest --info + markdown_lint: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - uses: DavidAnson/markdownlint-cli2-action@v18 + with: + config: '.markdownlint.yaml' + globs: '**/README.md' + # NOTE: In GitHub repository settings, the "Require status checks to pass # before merging" branch protection rule ensures that commits are only merged # from branches where specific status checks have passed. These checks are @@ -67,7 +76,7 @@ jobs: ci: name: CI status checks runs-on: ubuntu-latest - needs: build + needs: [build, markdown_lint] if: always() steps: - name: Check whether all jobs pass diff --git a/.markdownlint.yaml b/.markdownlint.yaml new file mode 100644 index 00000000..144a0959 --- /dev/null +++ b/.markdownlint.yaml @@ -0,0 +1,7 @@ +{ + "MD013": false, # Line length limitation + "MD024": false, # Allow multiple headings with the same content + "MD033": false, # Enable Inline HTML + "MD041": false, # Allow first line heading + "MD045": false, # Allow Images have no alternate text +} \ No newline at end of file diff --git a/README.md b/README.md index 1e8c711e..6d76814e 100644 --- a/README.md +++ b/README.md @@ -7,7 +7,6 @@ [![License](https://img.shields.io/badge/License-EPL%202.0-blue)](https://choosealicense.com/licenses/epl-2.0/) [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0) - # Eclipse Zenoh The Eclipse Zenoh: Zero Overhead Pub/sub, Store/Query and Compute. @@ -16,29 +15,27 @@ Zenoh (pronounce _/zeno/_) unifies data in motion, data at rest and computations Check the website [zenoh.io](http://zenoh.io) and the [roadmap](https://github.com/eclipse-zenoh/roadmap) for more detailed information. - ---- # Java Java API - This repository provides a Java compatible Kotlin binding based on the main [Zenoh implementation written in Rust](https://github.com/eclipse-zenoh/zenoh). The code relies on the Zenoh JNI native library, which written in Rust and communicates with the Kotlin layer via the Java Native Interface (JNI). ## Documentation -The documentation of the API is published at https://eclipse-zenoh.github.io/zenoh-java/index.html. +The documentation of the API is published at [https://eclipse-zenoh.github.io/zenoh-java/index.html](https://eclipse-zenoh.github.io/zenoh-java/index.html). Alternatively, you can build it locally as [explained below](#building-the-documentation). ---- -# How to import +# How to import :warning: Note nº1: **Breaking changes incoming** -With the purpose of providing an upgraded API across all the languages supported by the Zenoh ecosystem, +With the purpose of providing an upgraded API across all the languages supported by the Zenoh ecosystem, we are currently releasing a series of alpha and beta versions, the latest one being currently the [1.0.0-beta.1](https://github.com/eclipse-zenoh/zenoh-java/releases/tag/1.0.0-beta.1). @@ -50,13 +47,13 @@ the time comes. :warning: Note nº2: **About the released packages** The released packages can be found in the "packages" section of this repository, or in the links below: -* [Android packages](https://github.com/eclipse-zenoh/zenoh-java/packages/2019754/versions) -* [JVM packages](https://github.com/eclipse-zenoh/zenoh-java/packages/2017294/versions) + +- [Android packages](https://github.com/eclipse-zenoh/zenoh-java/packages/2019754/versions) +- [JVM packages](https://github.com/eclipse-zenoh/zenoh-java/packages/2017294/versions) These are 'nightly' packages that need to be imported as explained in the following sections of this README. We plan to publish our packages into Maven central for the `1.0.0` stable release. - ## Android For Android applications For this first version we have published a [Github package](https://github.com/eclipse-zenoh/zenoh-java/packages/2019754) with the library which can be imported on your projects. @@ -95,6 +92,7 @@ implementation("io.zenoh:zenoh-java-android:0.11.0") ### Platforms The library targets the following platforms: + - x86 - x86_64 - arm @@ -150,26 +148,27 @@ implementation("io.zenoh:zenoh-java-jvm:0.11.0") For the moment, the library targets the following platforms: - - x86_64-unknown-linux-gnu - - aarch64-unknown-linux-gnu - - x86_64-apple-darwin - - aarch64-apple-darwin - - x86_64-pc-windows-msvc +- x86_64-unknown-linux-gnu +- aarch64-unknown-linux-gnu +- x86_64-apple-darwin +- aarch64-apple-darwin +- x86_64-pc-windows-msvc - ---- +---- # How to build it ## What you need Basically: -* Rust ([Installation guide](https://doc.rust-lang.org/cargo/getting-started/installation.html)) -* Kotlin ([Installation guide](https://kotlinlang.org/docs/getting-started.html#backend)) -* Gradle ([Installation guide](https://gradle.org/install/)) + +- Rust ([Installation guide](https://doc.rust-lang.org/cargo/getting-started/installation.html)) +- Kotlin ([Installation guide](https://kotlinlang.org/docs/getting-started.html#backend)) +- Gradle ([Installation guide](https://gradle.org/install/)) and in case of targetting Android you'll also need: -* Android SDK ([Installation guide](https://developer.android.com/about/versions/11/setup-sdk)) + +- Android SDK ([Installation guide](https://developer.android.com/about/versions/11/setup-sdk)) ## JVM JVM @@ -189,7 +188,7 @@ Once we have published the package, we should be able to find it under `~/.m2/re Finally, in the `build.gradle.kts` file of the project where you intend to use this library, add mavenLocal to the list of repositories and add zenoh-java as a dependency: -``` +```kotlin repositories { mavenCentral() mavenLocal() @@ -212,14 +211,14 @@ It can be set up by using Android Studio (go to `Preferences > Languages & Frame or alternatively it can be found [here](https://developer.android.com/ndk/downloads). The native platforms we are going to target are the following ones: -``` + - x86 - x86_64 - arm - arm64 -``` Therefore, if they are not yet already added to the Rust toolchain, run: + ```bash rustup target add armv7-linux-androideabi; \ rustup target add i686-linux-android; \ @@ -229,8 +228,8 @@ rustup target add x86_64-linux-android to install them. - So, in order to publish the library onto Maven Local, run: + ```bash gradle -Pandroid=true publishAndroidReleasePublicationToMavenLocal ``` @@ -240,7 +239,8 @@ publish the library, containing the native binaries. You should now be able to see the package under `~/.m2/repository/io/zenoh/zenoh-java-android/0.11.0` with the following files: -``` + +```raw zenoh-java-android-0.11.0-sources.jar zenoh-java-android-0.11.0.aar zenoh-java-android-0.11.0.module @@ -251,7 +251,8 @@ Now the library is published on maven local, let's now see how to import it into First, we need to indicate we want to look into mavenLocal for our library, so in your top level `build.gradle.kts` you need to specify the `mavenLocal` repository: -``` + +```kotlin repositories { mavenCentral() ... @@ -260,13 +261,14 @@ repositories { ``` Then in your app's `build.gradle.kts` filen add the dependency: -``` + +```kotlin implementation("io.zenoh:zenoh-java-android:0.11.0") ``` And finally, do not forget to add the required internet permissions on your manifest! -``` +```xml ``` @@ -278,6 +280,7 @@ And that was it! You can now import the code from the `io.zenoh` package and use Because it's a Kotlin project, we use [Dokka](https://kotlinlang.org/docs/dokka-introduction.html) to generate the documentation. In order to build it, run: + ```bash gradle zenoh-java:dokkaHtml ``` @@ -308,7 +311,7 @@ causes the logs to appear in standard output. The log levels are the ones from Rust: `trace`, `info`, `debug`, `error` and `warn`. ---- +---- # Examples @@ -323,25 +326,20 @@ For instance in order to run the [ZPub](examples/src/main/java/io.zenoh/ZPub.jav You can find more info about these examples on the [examples README file](/examples/README.md). - - - - ---- # :warning: Considerations & Future work -### Packaging +## Packaging We intend to publish this code on Maven in the short term in order to ease the installation, but for the moment, until we add some extra functionalities and test this library a bit further, we will only publish packages to Github packages. -### Potential API changes - -When using this library, keep in mind the api is not fully stable. Changes are to be expected, especially for version 1.0.0. +## Potential API changes +When using this library, keep in mind the api is not fully stable. Changes are to be expected, especially for version 1.0.0. -### Performance +## Performance The communication between the Kotlin code and the Rust code through the java native interface (JNI) has its toll on performance. diff --git a/examples/README.md b/examples/README.md index 21c2c398..886ebc34 100644 --- a/examples/README.md +++ b/examples/README.md @@ -4,8 +4,6 @@ ## Start instructions - - ```bash ./gradle ``` @@ -13,7 +11,7 @@ :warning: Passing arguments to these examples has not been enabled yet for this first version. Altering the Zenoh configuration for these examples must be done programmatically. :warning: ----- +---- ## Examples description @@ -29,6 +27,7 @@ Usage: ``` ### ZSub + Creates a subscriber with a key expression. The subscriber will be notified of each put made on any key expression matching the subscriber's key expression, and will print this notification. @@ -61,6 +60,7 @@ Usage: ``` ### ZDelete + Performs a Delete operation into a path/value into Zenoh. Usage: