Automatically initialise libvips by default

.run/Run samples.run.xml

@@ -1,5 +1,6 @@
 <component name="ProjectRunConfigurationManager">
   <configuration default="false" name="Run samples" type="JetRunConfigurationType">
+    <option name="ALTERNATIVE_JRE_PATH" value="24" />
     <envs>
       <env name="DYLD_LIBRARY_PATH" value="libvips/release/lib:/opt/homebrew/lib:$DYLD_LIBRARY_PATH" />
     </envs>

README.md

@@ -23,7 +23,7 @@ repositories {
 }
 
 dependencies {
-    implementation("app.photofox.vips-ffm:vips-ffm-core:1.9.0")
+    implementation("app.photofox.vips-ffm:vips-ffm-core:1.9.1")
 }
 ```
 
@@ -56,11 +56,6 @@ import app.photofox.vipsffm.enums.VipsAccess
 
 // ...
 
-// Call once to initialise libvips when your program starts, from any thread
-//   Note that by default this blocks untrusted operations (like loading PDFs)
-//   See the "Allowing untrusted operations" section below to read about permitting untrusted operations
-Vips.init()
-
 // Use `Vips.run` to wrap your usage of the API, and get an arena with an appropriate lifetime to use
 // Usage of the API, arena, and resulting V-Objects must be done from the thread that called `Vips.run`
 Vips.run { arena ->
@@ -162,7 +157,16 @@ which isn't present in `vips-ffm`, you can use `VipsOption.Enum(rawValue)` or `V
 > available in `VImage` and other `V`-prefixed classes, use those instead. If you notice something missing, please open
 > a GitHub Issue.
 
-### Docker checks
+## Initialisation
+
+Initialisation of libvips is performed automatically the first time the `Vips`, `VipsHelper`, or `VipsInvoker` classes
+are initialised (which will cover almost all normal usage of vips-ffm). Previous versions of vips-ffm required users to
+call `Vips.init` manually, but this is no longer required.
+
+If you'd like to disable auto-initialisation of libvips, set the system property `vipsffm.autoinit` to the string value
+`false`.
+
+## Docker checks
 
 These samples are also run in Docker containers, to verify behaviour on specific Linux distributions. They're useful to
 look at if you're deploying `libvips` and `vips-ffm` workloads using containers.
@@ -207,7 +211,6 @@ If running an image proxy, or something that processes lots of different images,
 disable it:
 
 ```java
-Vips.init();
 Vips.disableOperationCache();
 ```
 

core/src/main/java/app/photofox/vipsffm/Vips.java

@@ -1,20 +1,63 @@
 package app.photofox.vipsffm;
 
 import java.lang.foreign.Arena;
+import java.util.Locale;
+import java.util.Optional;
+import java.util.concurrent.atomic.AtomicBoolean;
 
 /// Helper class for running Vips commands with an appropriate arena
 ///
 /// Blocks untrusted operations by default
 public class Vips {
 
+    private static final AtomicBoolean HAS_INITIALISED = new AtomicBoolean(false);
+
+    static {
+        autoInit();
+    }
+
+    /// Note that you do not usually need to call [Vips#init] yourself, as initialisation is performed
+    /// automatically when vips-ffm classes are used
     public static void init() {
-        init(false, false);
+        initOnce();
     }
 
+    /// @deprecated Please migrate to using [Vips#allowUntrustedOperations] and [Vips#enableLeakDetection], and note
+    /// that calling [Vips#init] is no longer required
+    @Deprecated(forRemoval = true)
     public static void init(boolean allowUntrusted, boolean detectLeaks) {
-        var arena = Arena.global();
-        VipsHelper.init(arena, allowUntrusted);
-        VipsHelper.leak_set(detectLeaks);
+        initOnce();
+        if (allowUntrusted) {
+            Vips.allowUntrustedOperations();
+        }
+        if (detectLeaks) {
+            Vips.enableLeakDetection();
+        }
+    }
+
+    // Intentionally package-private
+    static void autoInit() {
+        if (HAS_INITIALISED.get()) {
+            // Optimistically skip reading system property
+            return;
+        }
+        var shouldAutoInitString = Optional.ofNullable(System.getProperty("vipsffm.autoinit"))
+            .orElse("true")
+            .toLowerCase(Locale.ENGLISH);
+        var shouldAutoInit = Boolean.parseBoolean(shouldAutoInitString);
+        if (!shouldAutoInit) {
+            return;
+        }
+
+        initOnce();
+    }
+
+    private static void initOnce() {
+        if (HAS_INITIALISED.get()) {
+            return;
+        }
+        VipsHelper.init(Arena.global());
+        HAS_INITIALISED.set(true);
     }
 
     /// Provides a scoped arena to provide a memory boundary for running libvips operations
@@ -30,6 +73,14 @@ public static void shutdown() {
         VipsHelper.shutdown();
     }
 
+    /// Enables leak detection
+    ///
+    /// Calling [Vips#shutdown] will make libvips print out any leaks, and what classes hold memory references
+    /// causing these leaks
+    public static void enableLeakDetection() {
+        VipsHelper.leak_set(true);
+    }
+
     /// Permits untrusted operations, such as loading PDFs
     ///
     /// vips-ffm blocks these by default - see the [libvips docs](https://www.libvips.org/API/8.17/func.block_untrusted_set.html)

core/src/main/java/app/photofox/vipsffm/VipsHelper.java

@@ -12,13 +12,16 @@
 ///
 /// **Nothing in this class is guaranteed to stay the same across minor versions - use at your own risk!**
 public final class VipsHelper {
-  public static void init(Arena arena, boolean allowUntrusted) {
+  {
+    Vips.autoInit();
+  }
+
+  public static void init(Arena arena) {
     var nameCString = arena.allocateFrom("vips-ffm");
     var result = VipsRaw.vips_init(nameCString);
     if (!VipsValidation.isValidResult(result)) {
       VipsValidation.throwVipsError("vips_init");
     }
-    VipsRaw.vips_block_untrusted_set(allowUntrusted ? 0 : 1);
   }
 
   /// Binding for:

core/src/main/java/app/photofox/vipsffm/VipsInvoker.java

@@ -19,6 +19,10 @@
 /// a new version of libvips. You can find examples of how to use it in [VImage]
 public class VipsInvoker {
 
+    static {
+        Vips.autoInit();
+    }
+
     public static void invokeOperation(
         Arena arena,
         String nickname,

docs/allclasses-index.html

@@ -29,6 +29,7 @@
 <ul id="navbar-top-firstrow" class="nav-list" title="Navigation">
 <li><a href="index.html">Overview</a></li>
 <li><a href="overview-tree.html">Tree</a></li>
+<li><a href="deprecated-list.html">Deprecated</a></li>
 <li><a href="index-all.html">Index</a></li>
 <li><a href="search.html">Search</a></li>
 <li><a href="help-doc.html#all-classes">Help</a></li>

docs/allpackages-index.html

@@ -29,6 +29,7 @@
 <ul id="navbar-top-firstrow" class="nav-list" title="Navigation">
 <li><a href="index.html">Overview</a></li>
 <li><a href="overview-tree.html">Tree</a></li>
+<li><a href="deprecated-list.html">Deprecated</a></li>
 <li><a href="index-all.html">Index</a></li>
 <li><a href="search.html">Search</a></li>
 <li><a href="help-doc.html#all-packages">Help</a></li>

docs/app.photofox.vipsffm/app/photofox/vipsffm/VBlob.html

@@ -30,6 +30,7 @@
 <li><a href="../../../../index.html">Overview</a></li>
 <li class="nav-bar-cell1-rev">Class</li>
 <li><a href="package-tree.html">Tree</a></li>
+<li><a href="../../../../deprecated-list.html">Deprecated</a></li>
 <li><a href="../../../../index-all.html">Index</a></li>
 <li><a href="../../../../search.html">Search</a></li>
 <li><a href="../../../../help-doc.html#class">Help</a></li>

docs/app.photofox.vipsffm/app/photofox/vipsffm/VCustomSource.ReadCallback.html

@@ -30,6 +30,7 @@
 <li><a href="../../../../index.html">Overview</a></li>
 <li class="nav-bar-cell1-rev">Class</li>
 <li><a href="package-tree.html">Tree</a></li>
+<li><a href="../../../../deprecated-list.html">Deprecated</a></li>
 <li><a href="../../../../index-all.html">Index</a></li>
 <li><a href="../../../../search.html">Search</a></li>
 <li><a href="../../../../help-doc.html#class">Help</a></li>

docs/app.photofox.vipsffm/app/photofox/vipsffm/VCustomSource.SeekCallback.html

@@ -30,6 +30,7 @@
 <li><a href="../../../../index.html">Overview</a></li>
 <li class="nav-bar-cell1-rev">Class</li>
 <li><a href="package-tree.html">Tree</a></li>
+<li><a href="../../../../deprecated-list.html">Deprecated</a></li>
 <li><a href="../../../../index-all.html">Index</a></li>
 <li><a href="../../../../search.html">Search</a></li>
 <li><a href="../../../../help-doc.html#class">Help</a></li>

docs/app.photofox.vipsffm/app/photofox/vipsffm/VCustomSource.SeekWhence.html

@@ -30,6 +30,7 @@
 <li><a href="../../../../index.html">Overview</a></li>
 <li class="nav-bar-cell1-rev">Class</li>
 <li><a href="package-tree.html">Tree</a></li>
+<li><a href="../../../../deprecated-list.html">Deprecated</a></li>
 <li><a href="../../../../index-all.html">Index</a></li>
 <li><a href="../../../../search.html">Search</a></li>
 <li><a href="../../../../help-doc.html#class">Help</a></li>

docs/app.photofox.vipsffm/app/photofox/vipsffm/VCustomSource.html

@@ -30,6 +30,7 @@
 <li><a href="../../../../index.html">Overview</a></li>
 <li class="nav-bar-cell1-rev">Class</li>
 <li><a href="package-tree.html">Tree</a></li>
+<li><a href="../../../../deprecated-list.html">Deprecated</a></li>
 <li><a href="../../../../index-all.html">Index</a></li>
 <li><a href="../../../../search.html">Search</a></li>
 <li><a href="../../../../help-doc.html#class">Help</a></li>

docs/app.photofox.vipsffm/app/photofox/vipsffm/VCustomTarget.EndCallback.html

@@ -30,6 +30,7 @@
 <li><a href="../../../../index.html">Overview</a></li>
 <li class="nav-bar-cell1-rev">Class</li>
 <li><a href="package-tree.html">Tree</a></li>
+<li><a href="../../../../deprecated-list.html">Deprecated</a></li>
 <li><a href="../../../../index-all.html">Index</a></li>
 <li><a href="../../../../search.html">Search</a></li>
 <li><a href="../../../../help-doc.html#class">Help</a></li>

docs/app.photofox.vipsffm/app/photofox/vipsffm/VCustomTarget.WriteCallback.html

@@ -30,6 +30,7 @@
 <li><a href="../../../../index.html">Overview</a></li>
 <li class="nav-bar-cell1-rev">Class</li>
 <li><a href="package-tree.html">Tree</a></li>
+<li><a href="../../../../deprecated-list.html">Deprecated</a></li>
 <li><a href="../../../../index-all.html">Index</a></li>
 <li><a href="../../../../search.html">Search</a></li>
 <li><a href="../../../../help-doc.html#class">Help</a></li>

docs/app.photofox.vipsffm/app/photofox/vipsffm/VCustomTarget.html

@@ -30,6 +30,7 @@
 <li><a href="../../../../index.html">Overview</a></li>
 <li class="nav-bar-cell1-rev">Class</li>
 <li><a href="package-tree.html">Tree</a></li>
+<li><a href="../../../../deprecated-list.html">Deprecated</a></li>
 <li><a href="../../../../index-all.html">Index</a></li>
 <li><a href="../../../../search.html">Search</a></li>
 <li><a href="../../../../help-doc.html#class">Help</a></li>

docs/app.photofox.vipsffm/app/photofox/vipsffm/VEnum.Raw.html

@@ -30,6 +30,7 @@
 <li><a href="../../../../index.html">Overview</a></li>
 <li class="nav-bar-cell1-rev">Class</li>
 <li><a href="package-tree.html">Tree</a></li>
+<li><a href="../../../../deprecated-list.html">Deprecated</a></li>
 <li><a href="../../../../index-all.html">Index</a></li>
 <li><a href="../../../../search.html">Search</a></li>
 <li><a href="../../../../help-doc.html#class">Help</a></li>

docs/app.photofox.vipsffm/app/photofox/vipsffm/VEnum.html

@@ -30,6 +30,7 @@
 <li><a href="../../../../index.html">Overview</a></li>
 <li class="nav-bar-cell1-rev">Class</li>
 <li><a href="package-tree.html">Tree</a></li>
+<li><a href="../../../../deprecated-list.html">Deprecated</a></li>
 <li><a href="../../../../index-all.html">Index</a></li>
 <li><a href="../../../../search.html">Search</a></li>
 <li><a href="../../../../help-doc.html#class">Help</a></li>

docs/app.photofox.vipsffm/app/photofox/vipsffm/VImage.FindTrimOutput.html

@@ -30,6 +30,7 @@
 <li><a href="../../../../index.html">Overview</a></li>
 <li class="nav-bar-cell1-rev">Class</li>
 <li><a href="package-tree.html">Tree</a></li>
+<li><a href="../../../../deprecated-list.html">Deprecated</a></li>
 <li><a href="../../../../index-all.html">Index</a></li>
 <li><a href="../../../../search.html">Search</a></li>
 <li><a href="../../../../help-doc.html#class">Help</a></li>

docs/app.photofox.vipsffm/app/photofox/vipsffm/VImage.ProfileOutput.html

@@ -30,6 +30,7 @@
 <li><a href="../../../../index.html">Overview</a></li>
 <li class="nav-bar-cell1-rev">Class</li>
 <li><a href="package-tree.html">Tree</a></li>
+<li><a href="../../../../deprecated-list.html">Deprecated</a></li>
 <li><a href="../../../../index-all.html">Index</a></li>
 <li><a href="../../../../search.html">Search</a></li>
 <li><a href="../../../../help-doc.html#class">Help</a></li>

docs/app.photofox.vipsffm/app/photofox/vipsffm/VImage.ProjectOutput.html

@@ -30,6 +30,7 @@
 <li><a href="../../../../index.html">Overview</a></li>
 <li class="nav-bar-cell1-rev">Class</li>
 <li><a href="package-tree.html">Tree</a></li>
+<li><a href="../../../../deprecated-list.html">Deprecated</a></li>
 <li><a href="../../../../index-all.html">Index</a></li>
 <li><a href="../../../../search.html">Search</a></li>
 <li><a href="../../../../help-doc.html#class">Help</a></li>

docs/app.photofox.vipsffm/app/photofox/vipsffm/VImage.html

@@ -30,6 +30,7 @@
 <li><a href="../../../../index.html">Overview</a></li>
 <li class="nav-bar-cell1-rev">Class</li>
 <li><a href="package-tree.html">Tree</a></li>
+<li><a href="../../../../deprecated-list.html">Deprecated</a></li>
 <li><a href="../../../../index-all.html">Index</a></li>
 <li><a href="../../../../search.html">Search</a></li>
 <li><a href="../../../../help-doc.html#class">Help</a></li>

docs/app.photofox.vipsffm/app/photofox/vipsffm/VInterpolate.html

@@ -30,6 +30,7 @@
 <li><a href="../../../../index.html">Overview</a></li>
 <li class="nav-bar-cell1-rev">Class</li>
 <li><a href="package-tree.html">Tree</a></li>
+<li><a href="../../../../deprecated-list.html">Deprecated</a></li>
 <li><a href="../../../../index-all.html">Index</a></li>
 <li><a href="../../../../search.html">Search</a></li>
 <li><a href="../../../../help-doc.html#class">Help</a></li>

docs/app.photofox.vipsffm/app/photofox/vipsffm/VNamedEnum.html

@@ -30,6 +30,7 @@
 <li><a href="../../../../index.html">Overview</a></li>
 <li class="nav-bar-cell1-rev">Class</li>
 <li><a href="package-tree.html">Tree</a></li>
+<li><a href="../../../../deprecated-list.html">Deprecated</a></li>
 <li><a href="../../../../index-all.html">Index</a></li>
 <li><a href="../../../../search.html">Search</a></li>
 <li><a href="../../../../help-doc.html#class">Help</a></li>

docs/app.photofox.vipsffm/app/photofox/vipsffm/VSource.html

@@ -30,6 +30,7 @@
 <li><a href="../../../../index.html">Overview</a></li>
 <li class="nav-bar-cell1-rev">Class</li>
 <li><a href="package-tree.html">Tree</a></li>
+<li><a href="../../../../deprecated-list.html">Deprecated</a></li>
 <li><a href="../../../../index-all.html">Index</a></li>
 <li><a href="../../../../search.html">Search</a></li>
 <li><a href="../../../../help-doc.html#class">Help</a></li>

docs/app.photofox.vipsffm/app/photofox/vipsffm/VTarget.html

@@ -30,6 +30,7 @@
 <li><a href="../../../../index.html">Overview</a></li>
 <li class="nav-bar-cell1-rev">Class</li>
 <li><a href="package-tree.html">Tree</a></li>
+<li><a href="../../../../deprecated-list.html">Deprecated</a></li>
 <li><a href="../../../../index-all.html">Index</a></li>
 <li><a href="../../../../search.html">Search</a></li>
 <li><a href="../../../../help-doc.html#class">Help</a></li>