Markdown comments and libvips 8.17.0 (#150)

* Migrate to maintained JavaPoet

* Build with JDK 24 but target 22 compatibility

* Migrate hand-written comments to markdown

* Generate Markdown documentation for all V-Classes

* Add libvips submodule to work against

Author: lopcode

.github/workflows/checks.yml

@@ -18,7 +18,7 @@ jobs:
         uses: actions/setup-java@v4
         with:
           distribution: "temurin"
-          java-version: 22
+          java-version: 23
 
       - name: Setup Gradle
         uses: gradle/actions/setup-gradle@v3
@@ -43,7 +43,7 @@ jobs:
         uses: actions/setup-java@v4
         with:
           distribution: "temurin"
-          java-version: 22
+          java-version: 23
 
       - name: Setup Gradle
         uses: gradle/actions/setup-gradle@v3
@@ -68,7 +68,7 @@ jobs:
         uses: actions/setup-java@v4
         with:
           distribution: "temurin"
-          java-version: 22
+          java-version: 23
 
       - name: Setup Gradle
         uses: gradle/actions/setup-gradle@v3
@@ -78,12 +78,12 @@ jobs:
       - name: Run samples
         shell: pwsh
         run: |
-          Invoke-WebRequest "https://github.com/libvips/build-win64-mxe/releases/download/v8.15.3/vips-dev-w64-web-8.15.3-static-ffi.zip" -OutFile "vips_w64.zip"
-          (Get-FileHash .\vips_w64.zip).Hash -eq "60500d990c6063a1e95f1ff29a540c5943537ccbed4dd55711947b68229774ee"
+          Invoke-WebRequest "https://github.com/libvips/build-win64-mxe/releases/download/v8.17.0-rc1/vips-dev-w64-web-8.17.0-rc1-static-ffi.zip" -OutFile "vips_w64.zip"
+          (Get-FileHash .\vips_w64.zip).Hash -eq "sha256:ffbea9b23d57a60ef85fd0761510949e66116799ad6c2878c17d31780bd93a8a"
           Expand-Archive vips_w64.zip
-          $env:Path = "$pwd\vips_w64\vips-dev-8.15;$pwd\vips_w64\vips-dev-8.15\bin;" + $env:Path 
+          $env:Path = "$pwd\vips_w64\vips-dev-8.17;$pwd\vips_w64\vips-dev-8.17\bin;" + $env:Path 
           Write-Output $env:Path
-          Get-ChildItem .\vips_w64\vips-dev-8.15
+          Get-ChildItem .\vips_w64\vips-dev-8.17
           .\gradlew.bat sample:clean sample:shadowJar
           java -jar sample/build/libs/sample-all.jar
 
@@ -97,7 +97,7 @@ jobs:
         uses: actions/setup-java@v4
         with:
           distribution: "temurin"
-          java-version: 22
+          java-version: 23
 
       - name: Setup Gradle
         uses: gradle/actions/setup-gradle@v3

.github/workflows/release.yml

@@ -20,7 +20,7 @@ jobs:
         uses: actions/setup-java@v4
         with:
           distribution: "temurin"
-          java-version: 22
+          java-version: 23
 
       - name: Setup Gradle
         uses: gradle/actions/setup-gradle@v3

.gitignore

@@ -16,4 +16,4 @@ hs_err*
 sample_run
 .kotlin
 sample_output*
-sample*.jar
+sample*.jar

.gitmodules

@@ -0,0 +1,4 @@
+[submodule "libvips"]
+	path = libvips
+	url = https://github.com/libvips/libvips/
+	branch = tags/v8.17.0

.run/Discover Vips operations.run.xml

@@ -1,7 +1,7 @@
 <component name="ProjectRunConfigurationManager">
   <configuration default="false" name="Discover Vips operations" type="JetRunConfigurationType">
     <envs>
-      <env name="DYLD_LIBRARY_PATH" value="/opt/homebrew/lib" />
+      <env name="DYLD_LIBRARY_PATH" value="libvips/release/lib:/opt/homebrew/lib:$DYLD_LIBRARY_PATH" />
     </envs>
     <option name="MAIN_CLASS_NAME" value="vipsffm.DiscoverVipsOperationsKt" />
     <module name="vips-ffm.generator.main" />

.run/Generate V classes.run.xml

@@ -1,7 +1,7 @@
 <component name="ProjectRunConfigurationManager">
   <configuration default="false" name="Generate V classes" type="JetRunConfigurationType">
     <envs>
-      <env name="DYLD_LIBRARY_PATH" value="/opt/homebrew/lib" />
+      <env name="DYLD_LIBRARY_PATH" value="libvips/release/lib:/opt/homebrew/lib:$DYLD_LIBRARY_PATH" />
     </envs>
     <option name="MAIN_CLASS_NAME" value="vipsffm.GenerateVClasses" />
     <module name="vips-ffm.generator.main" />

.run/Generate VipsHelper class.run.xml

@@ -1,7 +1,7 @@
 <component name="ProjectRunConfigurationManager">
   <configuration default="false" name="Generate VipsHelper class" type="JetRunConfigurationType">
     <envs>
-      <env name="DYLD_LIBRARY_PATH" value="/opt/homebrew/lib" />
+      <env name="DYLD_LIBRARY_PATH" value="libvips/release/lib:/opt/homebrew/lib:$DYLD_LIBRARY_PATH" />
     </envs>
     <option name="MAIN_CLASS_NAME" value="vipsffm.GenerateVipsHelperClass" />
     <module name="vips-ffm.generator.main" />

.run/Run samples.run.xml

@@ -1,7 +1,7 @@
 <component name="ProjectRunConfigurationManager">
   <configuration default="false" name="Run samples" type="JetRunConfigurationType">
     <envs>
-      <env name="DYLD_LIBRARY_PATH" value="/opt/homebrew/lib" />
+      <env name="DYLD_LIBRARY_PATH" value="libvips/release/lib:/opt/homebrew/lib:$DYLD_LIBRARY_PATH" />
     </envs>
     <option name="MAIN_CLASS_NAME" value="vipsffm.SampleRunner" />
     <module name="vips-ffm.sample.main" />

CONTRIBUTING.md

@@ -23,7 +23,9 @@ Thank you for being enthusiastic about the project!
 ## Code changes
 
 You'll find it easiest to use [IntelliJ IDEA](https://www.jetbrains.com/idea/) to work on the project - there's a free
-version.
+version. The project is only developed on macOS, but in theory it should be possible to work in other Unix-like environments.
+
+Set up the libvips submodule, and create a build of it, by running `./setup_development.sh`. 
 
 The project uses Gradle, and is split into multiple modules:
 * `generator` uses the libvips operations API to generate most of the code in `core`

README.md

@@ -22,7 +22,7 @@ repositories {
 }
 
 dependencies {
-    implementation("app.photofox.vips-ffm:vips-ffm-core:1.5.2")
+    implementation("app.photofox.vips-ffm:vips-ffm-core:1.6.0")
 }
 ```
 
@@ -33,8 +33,8 @@ There are also lots of examples in the [samples](#samples).
 You must add `--enable-native-access=ALL-UNNAMED` to your JVM runtime arguments. If you don't, you'll get a warning
 about "Restricted methods". In the future, the JVM will throw an error if you don't explicitly include this flag.
 
-As the project uses the Java FFM API, your target must also be JDK 22+. Bindings are currently generated from libvips
-`8.16.1` (but should be safe to use with different minor or patch versions).
+As the project uses the Java FFM API, and Markdown comments, your target must also be JDK 23+. Bindings are currently
+generated from libvips `8.17.0` (but should be safe to use with different minor or patch versions).
 
 > [!NOTE]
 > This library **does not** include `libvips` in the download, you must add it to the system/container you're building
@@ -92,7 +92,7 @@ Samples are included that show various usages of these bindings. They include va
 
 To get set up to run samples (on macOS):
 * `brew install vips`
-* `sdk use java 22-open`
+* `sdk use java 23-open`
 * Then either:
   * Run `./run_samples.sh` in your terminal
   * Use the included `Run samples` profile in IntelliJ
@@ -222,4 +222,4 @@ Thank you for being enthusiastic about the project!
   * And only after a GitHub Release is made
   * Run `./publish_release_to_maven_central.sh <version matching github release version, including v prefix>` 
 
-[1]: https://docs.oracle.com/en/java/javase/22/core/memory-segments-and-arenas.html
+[1]: https://docs.oracle.com/en/java/javase/23/core/memory-segments-and-arenas.html