Skip jextract binding generation by default

docs/release notes/4.1.0/716.enhancement.md

@@ -0,0 +1,21 @@
+### Skip jextract binding generation by default
+
+**Description**
+
+Modifies the process by which maven builds the native SIMD library so that bindings are not generated by default.
+This change only impacts you if you build jvector from source.
+
+**Motivation**
+
+The existing build process re-generates the bindings on each build as long as jextract is in the path. This can cause issues since the jextract version on the system may not match the jextract version used to generate the checked-in bindings. This not only creates noise in the git working tree, but can also cause build errors since newer jextract releases may use language features from newer JDKs.
+
+**Usage notes**
+
+- `jextract_vector_simd.sh` is split into two scripts, `build_native_lib.sh` and `jextract_generate_bindings.sh`. Bindings are not generated by default during the build process.
+- To force binding generation, set the maven property `native.jextract.skip` to `false` at runtime or in the pom. Alternatively, run `jextract_generate_bindings.sh` directly.
+- If you have multiple jextract versions installed, or if jextract is not installed, you can set the environment variable `JEXTRACT_BIN` to the full path of the executable.
+
+Example:
+```sh
+JEXTRACT_BIN="/opt/jextract-22/bin/jextract" mvn compile -pl jvector-native -Dnative.jextract.skip=false
+```

jvector-native/pom.xml

@@ -13,6 +13,7 @@
     <name>Native</name>
     <properties>
         <native.buildtype>release</native.buildtype>
+        <native.jextract.skip>true</native.jextract.skip>
     </properties>
     <build>
         <plugins>
@@ -130,14 +131,31 @@
                         <artifactId>exec-maven-plugin</artifactId>
                         <executions>
                             <execution>
-                                <id>execute-jextract-compile-script</id>
+                                <id>jextract-generate</id>
+                                <!-- Note that jextract in the generate-sources phase runs before the .so is built in the generate-resources phase -->
+                                <phase>generate-sources</phase>
+                                <goals>
+                                    <goal>exec</goal>
+                                </goals>
+                                <configuration>
+                                    <executable>bash</executable>
+                                    <arguments>
+                                        <argument>jextract_generate_bindings.sh</argument>
+                                    </arguments>
+                                    <skip>${native.jextract.skip}</skip>
+                                    <workingDirectory>${project.basedir}/src/main/native/src/</workingDirectory>
+                                </configuration>
+                            </execution>
+                            <execution>
+                                <id>execute-native-compile-script</id>
                                 <phase>generate-resources</phase>
                                 <goals>
                                     <goal>exec</goal>
                                 </goals>
                                 <configuration>
-                                    <executable>./jextract_vector_simd.sh</executable>
+                                    <executable>bash</executable>
                                     <arguments>
+                                        <argument>build_native_lib.sh</argument>
                                         <argument>${native.buildtype}</argument>
                                     </arguments>
                                     <skip>false</skip>

jvector-native/src/main/native/src/jextract_vector_simd.sh → jvector-native/src/main/native/src/build_native_lib.sh

@@ -26,14 +26,12 @@ set -x
 # anywhere inside the repo).
 # ---------------------------------------------------------------------------
 REPO_ROOT="$(git -C "$(dirname "$0")" rev-parse --show-toplevel)"
-SCRIPT_DIR="${REPO_ROOT}/jvector-native/src/main/native/src"
 NATIVE_DIR="${REPO_ROOT}/jvector-native/src/main/native"
 MODULE_ROOT="${REPO_ROOT}/jvector-native"
 
 HIGHWAY_DIR="${NATIVE_DIR}/third_party/highway"
 BUILD_DIR="${MODULE_ROOT}/target/meson-build"
 RESOURCES_DIR="${MODULE_ROOT}/src/main/resources"
-JAVA_OUT_DIR="${MODULE_ROOT}/src/main/java"
 
 if [ "$1" == "--auto-install-deps" ] ; then AUTO_INSTALL_DEPS=true ; shift ; fi
 printf "AUTO_INSTALL_DEPS=%s\n" "${AUTO_INSTALL_DEPS}"
@@ -115,23 +113,3 @@ if [ -z "${SOFILE}" ]; then
     exit 1
 fi
 cp "${SOFILE}" "${RESOURCES_DIR}/libjvector.so"
-
-# Generate Java source code
-# Should only be run when c header changes
-# Check if jextract is available before running
-if ! command -v jextract &> /dev/null
-then
-    echo "WARNING: jextract could not be found, please install it if you need to update bindings."
-    exit 0
-fi
-
-jextract \
-  --output "${JAVA_OUT_DIR}" \
-  -t io.github.jbellis.jvector.vector.cnative \
-  -I "${SCRIPT_DIR}" \
-  --header-class-name NativeSimdOps \
-  "${SCRIPT_DIR}/jvector_simd.h"
-
-# Set critical linker option with heap-based segments for all generated methods
-sed -i 's/DESC)/DESC, Linker.Option.critical(true))/g' \
-  "${JAVA_OUT_DIR}/io/github/jbellis/jvector/vector/cnative/NativeSimdOps.java"

jvector-native/src/main/native/src/jextract_generate_bindings.sh

@@ -0,0 +1,55 @@
+#!/usr/bin/env bash
+
+# Copyright DataStax, Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+# Generate Java bindings for the native library.
+# Only needs to be run when the native header changes.
+
+set -euo pipefail
+
+REPO_ROOT="$(git -C "$(dirname "$0")" rev-parse --show-toplevel)"
+MODULE_ROOT="${REPO_ROOT}/jvector-native"
+SCRIPT_DIR="${REPO_ROOT}/jvector-native/src/main/native/src"
+JAVA_OUT_DIR="${MODULE_ROOT}/src/main/java"
+
+# The user is allowed to specify a custom jextract path via env var.
+# This is useful if there are multiple jextract versions on the system.
+if [[ -z "${JEXTRACT_BIN:-}" ]]; then
+  if command -v jextract &> /dev/null
+  then
+    JEXTRACT_BIN=jextract
+  else
+    echo 1>&2 "ERROR: jextract could not be found, please install it if you need to update bindings."
+    exit 1
+  fi
+fi
+
+jextract_version="$("$JEXTRACT_BIN" --version 2>&1 | head -1 | cut -d' ' -f2)"
+want_jextract_version=22
+if [[ "$jextract_version" != "$want_jextract_version" ]] ;then
+    echo 1>&2 "WARNING: got jextract version [${jextract_version}], expected [${want_jextract_version}]."
+    echo 1>&2 "WARNING: Generated bindings may cause compile errors."
+fi
+
+"$JEXTRACT_BIN" \
+  --output "${JAVA_OUT_DIR}" \
+  -t io.github.jbellis.jvector.vector.cnative \
+  -I "${SCRIPT_DIR}" \
+  --header-class-name NativeSimdOps \
+  "${SCRIPT_DIR}/jvector_simd.h"
+
+# Set critical linker option with heap-based segments for all generated methods
+sed -i 's/DESC)/DESC, Linker.Option.critical(true))/g' \
+  "${JAVA_OUT_DIR}/io/github/jbellis/jvector/vector/cnative/NativeSimdOps.java"