Prepare for release 0.7

manuelbl · Jan 3, 2024 · 8db08aa · 8db08aa
1 parent 56d0145
commit 8db08aa
Show file tree

Hide file tree

Showing 17 changed files with 202 additions and 36 deletions.
diff --git a/.github/workflows/continuous-integration.yaml b/.github/workflows/continuous-integration.yaml
@@ -47,13 +47,13 @@ jobs:
         run: ./mvnw $MAVEN_ARGS clean compile
         working-directory: ./examples/enumerate
       - name: Example "enumerate" (Kotlin)
-        run: ./mvnw $MAVEN_ARGS clean compile
+        run: ./mvnw $MAVEN_ARGS clean package
         working-directory: ./examples/enumerate_kotlin
       - name: Example "monitor"
         run: ./mvnw $MAVEN_ARGS clean compile
         working-directory: ./examples/monitor
       - name: Example "monitor" (Kotlin)
-        run: ./mvnw $MAVEN_ARGS clean compile
+        run: ./mvnw $MAVEN_ARGS clean package
         working-directory: ./examples/monitor_kotlin
       - name: Example "stm_dfu"
         run: ./mvnw $MAVEN_ARGS clean compile

diff --git a/README.md b/README.md
@@ -8,7 +8,7 @@ The library uses the [Foreign Function & Memory API](https://github.com/openjdk/
 
 | Version | Main New Features | Compatibility |
 | - | - | - |
-| 0.7.x | Prerelease: New setter/getter names for improved Kotlin support; Kotlin examples | JDK 21 |
+| 0.7.x | New setter/getter names for improved Kotlin support; Kotlin examples | JDK 21 |
 | 0.6.x | Support for JDK 21; better handling of composite devices on Windows | JDK 21 |
 | 0.5.x | Support for JDK 20; high-throuput I/O streams | JDK 20 |
 | 0.4.x | Early release | JDK 19 |
@@ -48,14 +48,14 @@ If you are using Maven, add the below dependency to your pom.xml:
 <dependency>
       <groupId>net.codecrete.usb</groupId>
       <artifactId>java-does-usb</artifactId>
-      <version>0.6.1</version>
+      <version>0.7.0</version>
 </dependency>
 ```
 
 If you are using Gradle, add the below dependency to your build.gradle file:
 
 ```groovy
-compile group: 'net.codecrete.usb', name: 'java-does-usb', version: '0.6.1'
+compile group: 'net.codecrete.usb', name: 'java-does-usb', version: '0.7.0'
 ```
 
 ```java
@@ -134,9 +134,26 @@ The library has not been tested on Windows for ARM64. It might or might not work
 
 ### Troubleshooting
 
--  The error `java.lang.ClassFormatError: Illegal field name "" in class net/codecrete/usb/windows/WindowsUsbDeviceRegistry` is caused by a bug in JDK 21, which has been fixed in the mean-time. Please upgrade to the latest release of JDK 21.
+#### `ClassFormatError` (all platforms)
 
-- The error `Cannot open library: CoreFoundation.framework/CoreFoundation` is caused by an unfortunate build of the OpenJDK by Homebrew. Please use any other JDK edition instead, e.g. Zulu (`brew install zulu` or directly from https://www.azul.com/downloads/#zulu), Temurin (`brew install temurin` or from https://adoptium.net/en-GB/temurin/releases/), or download the official OpenJDK directly from https://openjdk.org/projects/jdk/21/. And don't forget to uninstall the Homebrew build (`brew uninstall openjdk`).
+The error `java.lang.ClassFormatError: Illegal field name "" in class net/codecrete/usb/windows/WindowsUsbDeviceRegistry` is caused by a bug in JDK 21, which has been fixed in the mean-time. Please upgrade to the latest release of JDK 21 (at least 21.0.1).
+
+
+#### `Cannot open library` (macOS only)
+
+The error `Cannot open library: CoreFoundation.framework/CoreFoundation` is caused by an unfortunate build of the OpenJDK by Homebrew. Please use any other JDK edition instead, e.g. Zulu (`brew install zulu` or directly from https://www.azul.com/downloads/#zulu), Temurin (`brew install temurin` or from https://adoptium.net/en-GB/temurin/releases/), or download the official OpenJDK directly from https://openjdk.org/projects/jdk/21/.
+
+It will usually not be possible to uninstall the problematic build (`brew uninstall openjdk`) as it is a dependency of other brew packages. So to run an application, set `JAVA_HOME`:
+
+```shell
+export JAVA_HOME=/Users/me/Documents/zulu21.30.15-ca-jdk21.0.1-macosx_aarch64
+```
+
+If the JDK was "installed" as opposed to downloaded, the path for `JAVA_HOME` will likely be listed by:
+
+```sheel
+/usr/libexec/java_home -V
+```
 
 
 ### 32-bit versions

diff --git a/examples/bulk_transfer/README.md b/examples/bulk_transfer/README.md
@@ -39,7 +39,7 @@ $ mvn compile exec:exec
 [INFO] Scanning for projects...
 [INFO] 
 [INFO] --------------< net.codecrete.usb.examples:bulk-transfer >--------------
-[INFO] Building bulk-transfer 0.6.1
+[INFO] Building bulk-transfer 0.7.0
 [INFO] --------------------------------[ jar ]---------------------------------
 [INFO] 
 [INFO] --- maven-resources-plugin:3.0.2:resources (default-resources) @ bulk-transfer ---

diff --git a/examples/bulk_transfer/pom.xml b/examples/bulk_transfer/pom.xml
@@ -6,7 +6,7 @@
 
   <groupId>net.codecrete.usb.examples</groupId>
   <artifactId>bulk-transfer</artifactId>
-  <version>0.6.1</version>
+  <version>0.7.0</version>
 
   <name>bulk-transfer</name>
   <url>https://github.com/manuelbl/JavaDoesUSB/examples/bulk_transfer</url>
@@ -21,7 +21,7 @@
     <dependency>
       <groupId>net.codecrete.usb</groupId>
       <artifactId>java-does-usb</artifactId>
-      <version>0.7.0-SNAPSHOT</version>
+      <version>0.7.0</version>
     </dependency>
   </dependencies>
 

diff --git a/examples/enumerate/README.md b/examples/enumerate/README.md
@@ -38,7 +38,7 @@ $ mvn compile exec:exec
 [INFO] Scanning for projects...
 [INFO] 
 [INFO] ----------------< net.codecrete.usb.examples:enumerate >----------------
-[INFO] Building enumerate 0.6.1
+[INFO] Building enumerate 0.7.0
 [INFO] --------------------------------[ jar ]---------------------------------
 [INFO] 
 [INFO] --- maven-resources-plugin:3.0.2:resources (default-resources) @ enumerate ---

diff --git a/examples/enumerate/pom.xml b/examples/enumerate/pom.xml
@@ -6,7 +6,7 @@
 
   <groupId>net.codecrete.usb.examples</groupId>
   <artifactId>enumerate</artifactId>
-  <version>0.6.1</version>
+  <version>0.7.0</version>
 
   <name>enumerate</name>
   <url>https://github.com/manuelbl/JavaDoesUSB/examples/enumerate</url>
@@ -21,7 +21,7 @@
     <dependency>
       <groupId>net.codecrete.usb</groupId>
       <artifactId>java-does-usb</artifactId>
-      <version>0.7.0-SNAPSHOT</version>
+      <version>0.7.0</version>
     </dependency>
     <dependency>
       <groupId>org.tinylog</groupId>

diff --git a/examples/enumerate_kotlin/README.md b/examples/enumerate_kotlin/README.md
@@ -0,0 +1,50 @@
+# USB Device Enumeration (Kotlin)
+
+This sample enumerates the connected USB devices and provides information about the interfaces and endpoints.
+
+## Prerequisites
+
+- Java 21
+- Apache Maven
+- 64-bit operating system (Windows, macOS, Linux)
+
+## How to run
+
+### Install Java 21
+
+Check that *Java 21* is installed:
+
+```shell
+$ java -version
+```
+
+If not, download and install it, e.g. from [Azul](https://www.azul.com/downloads/?package=jdk).
+
+### Install Maven
+
+Check that *Maven* is installed:
+
+```shell
+$ mvn -version
+```
+
+If it is not present, install it, typically using package manager like *Homebrew* on macOS, *Chocolately* on Windows and *apt* on Linux.
+
+### Build a self-contained jar file
+
+```shell
+$ cd JavaDoesUSB/examples/enumerate_kotlin
+$ mvn clean package
+```
+
+### Run the jar
+
+```shell
+$ java --enable-preview --enable-native-access=ALL-UNNAMED -jar target/enumerate-0.7.0-jar-with-dependencies.jar
+Device:
+  VID: 0xcafe
+  PID: 0xceaf
+  Manufacturer:  JavaDoesUSB
+  Product name:  Loopback
+...
+```
diff --git a/examples/enumerate_kotlin/pom.xml b/examples/enumerate_kotlin/pom.xml
@@ -3,17 +3,18 @@
   <modelVersion>4.0.0</modelVersion>
 
   <groupId>net.codecrete.usb.examples</groupId>
-  <artifactId>kotlin</artifactId>
-  <version>0.6.1-SNAPSHOT</version>
+  <artifactId>enumerate</artifactId>
+  <version>0.7.0</version>
   <packaging>jar</packaging>
 
-  <name>kotlin</name>
-  <url>https://github.com/manuelbl/JavaDoesUSB/examples/kotlin</url>
+  <name>enumerate</name>
+  <url>https://github.com/manuelbl/JavaDoesUSB/examples/enumerate_kotlin</url>
 
   <properties>
-    <kotlin.version>1.9.10</kotlin.version>
+    <kotlin.version>1.9.22</kotlin.version>
     <kotlin.compiler.incremental>true</kotlin.compiler.incremental>
     <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
+    <main.class>net.codecrete.usb.examples.EnumerateKt</main.class>
   </properties>
 
   <build>
@@ -27,6 +28,30 @@
         <version>${kotlin.version}</version>
         <extensions>true</extensions>
       </plugin>
+      <plugin>
+        <groupId>org.apache.maven.plugins</groupId>
+        <artifactId>maven-assembly-plugin</artifactId>
+        <version>3.6.0</version>
+        <executions>
+          <execution>
+            <id>make-assembly</id>
+            <phase>package</phase>
+            <goals>
+              <goal>single</goal>
+            </goals>
+            <configuration>
+              <archive>
+                <manifest>
+                  <mainClass>${main.class}</mainClass>
+                </manifest>
+              </archive>
+              <descriptorRefs>
+                <descriptorRef>jar-with-dependencies</descriptorRef>
+              </descriptorRefs>
+            </configuration>
+          </execution>
+        </executions>
+      </plugin>
     </plugins>
   </build>
 
@@ -39,7 +64,7 @@
     <dependency>
       <groupId>net.codecrete.usb</groupId>
       <artifactId>java-does-usb</artifactId>
-      <version>0.7.0-SNAPSHOT</version>
+      <version>0.7.0</version>
     </dependency>
     <dependency>
       <groupId>org.tinylog</groupId>

diff --git a/examples/epaper_display/README.md b/examples/epaper_display/README.md
@@ -45,7 +45,7 @@ $ mvn compile exec:exec
 [INFO] Scanning for projects...
 [INFO] 
 [INFO] -------------< net.codecrete.usb.examples:epaper-display >--------------
-[INFO] Building epaper-display 0.6.1
+[INFO] Building epaper-display 0.7.0
 [INFO]   from pom.xml
 [INFO] --------------------------------[ jar ]---------------------------------
 [INFO] 
@@ -81,6 +81,6 @@ $ sudo -i
 Password:
 $ cd /Users/me/Documents/JavaDoesUSB/examples/epaper_display
 $ export JAVA_HOME=/Library/Java/JavaVirtualMachines/zulu-20.jdk/Contents/Home
-$ $JAVA_HOME/bin/java --enable-preview --enable-native-access=ALL-UNNAMED -cp target/classes:/Users/me/.m2/repository/net/codecrete/usb/java-does-usb/0.6.1/java-does-usb-0.6.1.jar net.codecrete.usb.examples.EPaperDisplay
+$ $JAVA_HOME/bin/java --enable-preview --enable-native-access=ALL-UNNAMED -cp target/classes:/Users/me/.m2/repository/net/codecrete/usb/java-does-usb/0.7.0/java-does-usb-0.7.0.jar net.codecrete.usb.examples.EPaperDisplay
 Display size: 1200 x 825
 ```
diff --git a/examples/epaper_display/pom.xml b/examples/epaper_display/pom.xml
@@ -6,7 +6,7 @@
 
   <groupId>net.codecrete.usb.examples</groupId>
   <artifactId>epaper-display</artifactId>
-  <version>0.6.1</version>
+  <version>0.7.0</version>
 
   <name>epaper-display</name>
   <url>https://github.com/manuelbl/JavaDoesUSB/examples/epaper_display</url>
@@ -21,7 +21,7 @@
     <dependency>
       <groupId>net.codecrete.usb</groupId>
       <artifactId>java-does-usb</artifactId>
-      <version>0.7.0-SNAPSHOT</version>
+      <version>0.7.0</version>
     </dependency>
   </dependencies>
 

diff --git a/examples/monitor/README.md b/examples/monitor/README.md
@@ -38,7 +38,7 @@ $ mvn compile exec:exec
 [INFO] Scanning for projects...
 [INFO] 
 [INFO] -----------------< net.codecrete.usb.examples:monitor >-----------------
-[INFO] Building monitor 0.6.1
+[INFO] Building monitor 0.7.0
 [INFO] --------------------------------[ jar ]---------------------------------
 [INFO] 
 [INFO] --- maven-resources-plugin:3.0.2:resources (default-resources) @ monitor ---

diff --git a/examples/monitor/pom.xml b/examples/monitor/pom.xml
@@ -6,7 +6,7 @@
 
   <groupId>net.codecrete.usb.examples</groupId>
   <artifactId>monitor</artifactId>
-  <version>0.6.1</version>
+  <version>0.7.0</version>
 
   <name>monitor</name>
   <url>https://github.com/manuelbl/JavaDoesUSB/examples/monitor</url>
@@ -21,7 +21,7 @@
     <dependency>
       <groupId>net.codecrete.usb</groupId>
       <artifactId>java-does-usb</artifactId>
-      <version>0.7.0-SNAPSHOT</version>
+      <version>0.7.0</version>
     </dependency>
     <dependency>
       <groupId>org.tinylog</groupId>

diff --git a/examples/monitor_kotlin/README.md b/examples/monitor_kotlin/README.md
@@ -0,0 +1,49 @@
+# USB Device Monitoring (Kotlin)
+
+This sample enumerates the connected USB devices and provides information about the interfaces and endpoints.
+
+## Prerequisites
+
+- Java 21
+- Apache Maven
+- 64-bit operating system (Windows, macOS, Linux)
+
+## How to run
+
+### Install Java 21
+
+Check that *Java 21* is installed:
+
+```shell
+$ java -version
+```
+
+If not, download and install it, e.g. from [Azul](https://www.azul.com/downloads/?package=jdk).
+
+### Install Maven
+
+Check that *Maven* is installed:
+
+```shell
+$ mvn -version
+```
+
+If it is not present, install it, typically using package manager like *Homebrew* on macOS, *Chocolately* on Windows and *apt* on Linux.
+
+### Build a self-contained jar file
+
+```shell
+$ cd JavaDoesUSB/examples/monitor_kotlin
+$ mvn clean package
+```
+
+### Run the jar
+
+```shell
+$ java --enable-preview --enable-native-access=ALL-UNNAMED -jar target/monitor-0.7.0-jar-with-dependencies.jar
+WARNING: "public static final void net.codecrete.usb.examples.MonitorKt.main()" chosen over "public static void net.codecrete.usb.examples.MonitorKt.main(java.lang.String[])"
+Present:      VID: 0xcafe, PID: 0xceaf, manufacturer: JavaDoesUSB, product: Loopback, serial: 35A737883336, ID: 4295265643
+Present:      VID: 0x1a40, PID: 0x0801, manufacturer: null, product: USB 2.0 Hub, serial: null, ID: 4295259660
+Monitoring... Press ENTER to quit.
+...
+```