From f63c65fa7a0d34892047da7b5bf42c24e5ffa08c Mon Sep 17 00:00:00 2001
From: carrot <149851+lopcode@users.noreply.github.com>
Date: Tue, 20 Aug 2024 22:43:17 +0100
Subject: [PATCH] Tidy up README ready for a first release (#26)

---
 ...rs.run.xml => Generate Vips class.run.xml} |   6 +-
 ...mpleRunner.run.xml => Run samples.run.xml} |   2 +-
 README.md                                     | 125 +++++++++++-------
 .../app/photofox/vipsffm/generated/Vips.java  |   0
 generate_ffm_bindings.sh                      |   2 +-
 .../build.gradle.kts                          |   2 +-
 .../main/kotlin/vipsffm/GenerateVipsClass.kt  |   6 +-
 helper/build.gradle.kts                       |  52 --------
 run_samples.sh                                |   4 +-
 sample/build.gradle.kts                       |   1 -
 settings.gradle.kts                           |   2 +-
 11 files changed, 90 insertions(+), 112 deletions(-)
 rename .run/{Generate helpers.run.xml => Generate Vips class.run.xml} (65%)
 rename .run/{SampleRunner.run.xml => Run samples.run.xml} (84%)
 rename {helper => core}/src/main/java/app/photofox/vipsffm/generated/Vips.java (100%)
 rename {helper-generator => generator}/build.gradle.kts (96%)
 rename helper-generator/src/main/kotlin/vipsffm/GenerateHelpers.kt => generator/src/main/kotlin/vipsffm/GenerateVipsClass.kt (99%)
 delete mode 100644 helper/build.gradle.kts

diff --git a/.run/Generate helpers.run.xml b/.run/Generate Vips class.run.xml
similarity index 65%
rename from .run/Generate helpers.run.xml
rename to .run/Generate Vips class.run.xml
index 8392d88..41b6e3e 100644
--- a/.run/Generate helpers.run.xml	
+++ b/.run/Generate Vips class.run.xml	
@@ -1,7 +1,7 @@
 <component name="ProjectRunConfigurationManager">
-  <configuration default="false" name="Generate helpers" type="JetRunConfigurationType">
-    <option name="MAIN_CLASS_NAME" value="vipsffm.GenerateHelpers" />
-    <module name="vips-ffm.helper-generator.main" />
+  <configuration default="false" name="Generate Vips class" type="JetRunConfigurationType">
+    <option name="MAIN_CLASS_NAME" value="vipsffm.GenerateVipsClass" />
+    <module name="vips-ffm.generator.main" />
     <shortenClasspath name="NONE" />
     <option name="VM_PARAMETERS" value="--enable-preview" />
     <method v="2">
diff --git a/.run/SampleRunner.run.xml b/.run/Run samples.run.xml
similarity index 84%
rename from .run/SampleRunner.run.xml
rename to .run/Run samples.run.xml
index 2c53c6e..ceab043 100644
--- a/.run/SampleRunner.run.xml
+++ b/.run/Run samples.run.xml	
@@ -1,5 +1,5 @@
 <component name="ProjectRunConfigurationManager">
-  <configuration default="false" name="SampleRunner" type="JetRunConfigurationType">
+  <configuration default="false" name="Run samples" type="JetRunConfigurationType">
     <envs>
       <env name="DYLD_LIBRARY_PATH" value="native_libs" />
     </envs>
diff --git a/README.md b/README.md
index 2344b30..6ad511d 100644
--- a/README.md
+++ b/README.md
@@ -6,28 +6,89 @@ of libvips, FFM, and auto-generated helpers makes for performant, safe, and ergo
 Supports a vast range of image formats, including HEIC, JXL, WebP, PNG, JPEG, and more. Pronounced "vips (like zips)
 eff-eff-emm".
 
-Bindings are automatically generated using `jextract`, and enhanced with some helpful wrapper functions to make usage
-more idiomatic.
+Raw bindings are automatically generated using `jextract`, then processed and wrapped with some lightweight "helpers" to
+allow for safe, idiomatic usage.
 
-Incubating in [Photo Fox](https://github.com/lopcode/photo-fox).
+Like what you've read so far? Please give the repo a star 🌟️!
+
+## Usage
+
+This is still a work-in-progress, and there aren't any packages published yet. As the project uses the FFM API, it must
+target JDK 22+.
+
+The libvips API is exposed via a Java helper class, `Vips`. You must provide an [Arena][1] during initialisation. This
+Arena constrains the lifetime of objects generated during usage of the vips-ffm API, so be careful to only keep it in
+scope for as long as you need to. If the arena doesn't close, your memory usage will grow forever. Constructing the
+`Vips` object is cheap, as it's just a wrapper, so make them as you need.
+
+This library **does not** include `libvips` in the download, you must add it to the system you're building on, then make
+sure it's available in `DYLD_LIBRARY_PATH` (on macOS) or `LD_LIBRARY_PATH` (on Linux). 
+
+🚨 Raw bindings generated by `jextract` are available in `VipsRaw` as static methods. It's very difficult to use
+`VipsRaw` functions without accidentally causing memory leaks, or even segfaults! If what you want to do is available in
+`Vips`, use that instead. If you notice something missing, open a GitHub Issue.
+
+### Thumbnail sample
+
+To get a feeling for the bindings, here's an indicative sample written in Kotlin (using the Java bindings) that:
+* Loads an original JPEG image from disk
+* Writes a copy of it to disk
+* Creates a 400px thumbnail from the original, and writes that to disk
+
+<img align="right" width="200" src="sample/src/main/resources/sample_images/rabbit.jpg">
+
+```kotlin
+import app.photofox.vipsffm.generated.Vips
+import java.lang.foreign.Arena
+
+// ...
+
+Arena.ofConfined().use { arena ->
+    val vips = Vips(arena)
+
+    val version = vips.versionString()
+    logger.info("vips version: $version")
+  
+    val sourceImage = vips.imageNewFromFile(
+        "sample/src/main/resources/sample_images/rabbit.jpg",
+        VipsIntOption("access", VipsRaw.VIPS_ACCESS_SEQUENTIAL())
+    )
+    val sourceWidth = VipsImage.Xsize(sourceImage)
+    val sourceHeight = VipsImage.Ysize(sourceImage)
+    logger.info("source image size: $sourceWidth x $sourceHeight")
+
+    val outputPath = workingDirectory.resolve("rabbit_copy.jpg")
+    vips.imageWriteToFile(sourceImage, outputPath.absolutePathString())
+
+    val outputImagePointer = VipsOutputPointer(arena)
+    vips.thumbnail("sample/src/main/resources/sample_images/rabbit.jpg", outputImagePointer, 400)
+    val thumbnailImage = outputImagePointer.dereferencedOrThrow()
+    val thumbnailPath = workingDirectory.resolve("rabbit_thumbnail_400.jpg")
+    vips.imageWriteToFile(thumbnailImage, thumbnailPath.absolutePathString())
+
+    val thumbnailWidth = VipsImage.Xsize(thumbnailImage)
+    val thumbnailHeight = VipsImage.Ysize(thumbnailImage)
+    logger.info("thumbnail image size: $thumbnailWidth x $thumbnailHeight")
+}
+```
+
+The project has several samples, [described below](#samples).
 
 ## Project goals
 
-* Publish to GitHub Packages via Gradle, so that using the library is as easy as
-`implementation("app.photofox:vips-ffm-core:$version")` (TODO)
-* Automate as much as possible, including API generation via [jextract](https://github.com/openjdk/jextract), so
-  upstream changes can be rapidly integrated ✅
-* Core module should only include this automated output, with a minimum of extra things that can break as upstreams
-  change ✅
-* If helpers are required, publish in another artifact ✅
-  * Generate these too, if possible
-* Keep generated APIs as similar to the original as possible
-* Incubate in Photo Fox with some "real world" usage
+Ideas and suggestions are welcome, but please make sure they fit in to these goals, or you have a good argument about
+why a goal should change!
+
+* Avoid manual work by automating as much as possible. This means upstream changes can be rapidly integrated.
+* Keep generated APIs as similar to the original as is sensible. Small changes to make the API nicer, or make correct 
+  usage easier, are ok (eg `gboolean` -> `boolean`, or `VipsOutputPointer` to manage tricky pointer translations).
+* Provide access to the raw bindings (`VipsRaw`), so users aren't blocked by helper bugs or API annoyances.
+* Incubate in [Photo Fox](https://github.com/lopcode/photo-fox) with some "real world" usage.
 
 ## Samples
 
 Samples are included that show various usages of the `libvips` bindings. They include validations, and run on GitHub
-Actions to validate new versions during development.
+Actions as "end-to-end tests" during development.
 
 To get set up to run samples (on macOS):
 * `brew install vips`
@@ -36,7 +97,7 @@ To get set up to run samples (on macOS):
 * (Optional, to regenerate bindings) `./generate_ffm_bindings.sh`
 * Then either:
   * Run `./run_samples.sh` in your terminal
-  * Run `VipsFfm` in IntelliJ to run samples and validations
+  * Run `SampleRunner` in IntelliJ to run samples and validations
 
 ```
 [main] INFO vipsffm.SampleRunner - clearing sample run directory at path "sample_run"
@@ -59,36 +120,4 @@ memory: high-water mark 36.55 MB
 [main] INFO vipsffm.SampleRunner - all samples ran successfully 🎉
 ```
 
-### Thumbnail sample
-
-To get a feeling for the bindings, here's an indicative sample written in Kotlin (using the Java bindings) that:
-* Loads an original JPEG image from disk
-* Writes a copy of it to disk
-* Creates a 400px thumbnail from the original, and writes that to disk 
-
-```kt
-Arena.ofConfined().use { arena ->
-    val vips = Vips(arena)
-
-    val sourceImage = vips.imageNewFromFile(
-        "sample/src/main/resources/sample_images/rabbit.jpg",
-        VipsIntOption("access", VipsRaw.VIPS_ACCESS_SEQUENTIAL())
-    )
-    val sourceWidth = VipsImage.Xsize(sourceImage)
-    val sourceHeight = VipsImage.Ysize(sourceImage)
-    logger.info("source image size: $sourceWidth x $sourceHeight")
-
-    val outputPath = workingDirectory.resolve("rabbit_copy.jpg")
-    vips.imageWriteToFile(sourceImage, outputPath.absolutePathString())
-
-    val outputImagePointer = VipsOutputPointer(arena)
-    vips.thumbnail("sample/src/main/resources/sample_images/rabbit.jpg", outputImagePointer, 400)
-    val thumbnailImage = outputImagePointer.dereferencedOrThrow()
-    val thumbnailPath = workingDirectory.resolve("rabbit_thumbnail_400.jpg")
-    vips.imageWriteToFile(thumbnailImage, thumbnailPath.absolutePathString())
-
-    val thumbnailWidth = VipsImage.Xsize(thumbnailImage)
-    val thumbnailHeight = VipsImage.Ysize(thumbnailImage)
-    logger.info("thumbnail image size: $thumbnailWidth x $thumbnailHeight")
-}
-```
\ No newline at end of file
+[1]: https://docs.oracle.com/en/java/javase/22/core/memory-segments-and-arenas.html
\ No newline at end of file
diff --git a/helper/src/main/java/app/photofox/vipsffm/generated/Vips.java b/core/src/main/java/app/photofox/vipsffm/generated/Vips.java
similarity index 100%
rename from helper/src/main/java/app/photofox/vipsffm/generated/Vips.java
rename to core/src/main/java/app/photofox/vipsffm/generated/Vips.java
diff --git a/generate_ffm_bindings.sh b/generate_ffm_bindings.sh
index c98f34b..7071125 100755
--- a/generate_ffm_bindings.sh
+++ b/generate_ffm_bindings.sh
@@ -67,4 +67,4 @@ set -x
 @includes_filtered.txt \
 "$LIBVIPS_ENTRY_PATH"
 
-./gradlew clean helper-generator:run
+./gradlew clean generator:run
diff --git a/helper-generator/build.gradle.kts b/generator/build.gradle.kts
similarity index 96%
rename from helper-generator/build.gradle.kts
rename to generator/build.gradle.kts
index 26f7cc4..5571de4 100644
--- a/helper-generator/build.gradle.kts
+++ b/generator/build.gradle.kts
@@ -44,7 +44,7 @@ tasks.withType<Test> {
 }
 
 application {
-    mainClass = "vipsffm.GenerateHelpers"
+    mainClass = "vipsffm.GenerateVipsClass"
     applicationDefaultJvmArgs = listOf("--enable-preview")
     tasks.run.get().workingDir = rootProject.projectDir
 }
\ No newline at end of file
diff --git a/helper-generator/src/main/kotlin/vipsffm/GenerateHelpers.kt b/generator/src/main/kotlin/vipsffm/GenerateVipsClass.kt
similarity index 99%
rename from helper-generator/src/main/kotlin/vipsffm/GenerateHelpers.kt
rename to generator/src/main/kotlin/vipsffm/GenerateVipsClass.kt
index 0c8e9b1..441cd24 100644
--- a/helper-generator/src/main/kotlin/vipsffm/GenerateHelpers.kt
+++ b/generator/src/main/kotlin/vipsffm/GenerateVipsClass.kt
@@ -22,9 +22,9 @@ import java.util.Locale
 import javax.lang.model.SourceVersion
 import javax.lang.model.element.Modifier
 
-object GenerateHelpers {
+object GenerateVipsClass {
 
-    private val logger = LoggerFactory.getLogger(GenerateHelpers::class.java)
+    private val logger = LoggerFactory.getLogger(GenerateVipsClass::class.java)
     private val vipsValidatorType = ClassName.get("app.photofox.vipsffm.helper", "VipsValidation")
     private val vipsInvokerType = ClassName.get("app.photofox.vipsffm.helper", "VipsInvoker")
     private val vipsErrorType = ClassName.get("app.photofox.vipsffm.helper", "VipsError")
@@ -372,7 +372,7 @@ object GenerateHelpers {
             .build()
         val javaFile = JavaFile.builder("app.photofox.vipsffm.generated", vipsClass)
             .build()
-        val targetGeneratedSourceRoot = Path.of("helper/src/main/java/")
+        val targetGeneratedSourceRoot = Path.of("core/src/main/java/")
         javaFile.writeToPath(targetGeneratedSourceRoot, Charsets.UTF_8)
     }
 
diff --git a/helper/build.gradle.kts b/helper/build.gradle.kts
deleted file mode 100644
index 4d0c5ee..0000000
--- a/helper/build.gradle.kts
+++ /dev/null
@@ -1,52 +0,0 @@
-@file:Suppress("UnstableApiUsage")
-
-import org.gradle.api.tasks.testing.logging.TestExceptionFormat
-import org.gradle.api.tasks.testing.logging.TestLogEvent
-
-plugins {
-    id("com.github.johnrengelman.shadow") version "8.1.1"
-    `java-library`
-}
-
-repositories {
-    mavenCentral()
-}
-
-java {
-    toolchain {
-        languageVersion.set(JavaLanguageVersion.of(22))
-    }
-}
-
-testing {
-    suites {
-        val test by getting(JvmTestSuite::class) {
-            useKotlinTest("2.0.0")
-            testType = TestSuiteType.UNIT_TEST
-        }
-    }
-}
-
-tasks.withType<Test> {
-    testLogging {
-        events = TestLogEvent.values().toSet() - TestLogEvent.STARTED
-        exceptionFormat = TestExceptionFormat.FULL
-    }
-    jvmArgs("--enable-native-access=ALL-UNNAMED")
-    environment(mapOf("DYLD_LIBRARY_PATH" to "native_libs"))
-    outputs.upToDateWhen { false }
-}
-
-tasks.named("check") {
-    dependsOn(testing.suites.named("test"))
-}
-
-tasks.withType<JavaExec>().configureEach {
-    jvmArgs("--enable-native-access=ALL-UNNAMED")
-    environment(mapOf("DYLD_LIBRARY_PATH" to "native_libs"))
-    javaLauncher.set(project.javaToolchains.launcherFor(java.toolchain))
-}
-
-dependencies {
-    implementation(project(":core"))
-}
\ No newline at end of file
diff --git a/run_samples.sh b/run_samples.sh
index 681b2b0..fba80d8 100755
--- a/run_samples.sh
+++ b/run_samples.sh
@@ -15,4 +15,6 @@ echo "checking for leaks..."
 if grep --quiet "objects alive:" sample_output.log; then
   echo "failure - detected a memory leak!"
   exit 1
-fi
\ No newline at end of file
+fi
+
+echo "no leaks detected 🎉"
\ No newline at end of file
diff --git a/sample/build.gradle.kts b/sample/build.gradle.kts
index 8cca284..7b39939 100644
--- a/sample/build.gradle.kts
+++ b/sample/build.gradle.kts
@@ -15,7 +15,6 @@ repositories {
 
 dependencies {
     implementation(project(":core"))
-    implementation(project(":helper"))
     implementation(platform("org.slf4j:slf4j-bom:2.0.16"))
     implementation("org.slf4j:slf4j-api")
     implementation("org.slf4j:slf4j-simple")
diff --git a/settings.gradle.kts b/settings.gradle.kts
index 400e1ff..e18e239 100644
--- a/settings.gradle.kts
+++ b/settings.gradle.kts
@@ -12,4 +12,4 @@ plugins {
 }
 
 rootProject.name = "vips-ffm"
-include("core", "helper", "helper-generator", "sample")
+include("core", "generator", "sample")