From 48a8af38882a95c0663ca0cede59f5ff4c604cd5 Mon Sep 17 00:00:00 2001
From: Xuanwo <github@xuanwo.io>
Date: Mon, 22 Dec 2025 21:05:50 +0800
Subject: [PATCH 01/11] feat(bindings/java): Add musl platform support

---
 .github/workflows/release_java.yml            | 16 ++++
 .../java/org/apache/opendal/Environment.java  | 55 ++++++++++-
 .../org/apache/opendal/NativeLibrary.java     | 96 ++++++++++++++++---
 .../org/apache/opendal/EnvironmentTest.java   | 67 +++++++++++++
 bindings/java/tools/build.py                  | 11 ++-
 5 files changed, 228 insertions(+), 17 deletions(-)
 create mode 100644 bindings/java/src/test/java/org/apache/opendal/EnvironmentTest.java

diff --git a/.github/workflows/release_java.yml b/.github/workflows/release_java.yml
index c530d0fcb5bb..fea5d57226a5 100644
--- a/.github/workflows/release_java.yml
+++ b/.github/workflows/release_java.yml
@@ -42,8 +42,12 @@ jobs:
         include:
           - os: ubuntu-latest
             classifier: linux-x86_64
+          - os: ubuntu-latest
+            classifier: linux-x86_64-musl
           - os: ubuntu-24.04-arm
             classifier: linux-aarch_64
+          - os: ubuntu-24.04-arm
+            classifier: linux-aarch_64-musl
           - os: windows-latest
             classifier: windows-x86_64
           - os: macos-latest
@@ -135,11 +139,21 @@ jobs:
         with:
           name: linux-x86_64-local-staging
           path: ~/linux-x86_64-local-staging
+      - name: Download linux x86_64 (musl) staging directory
+        uses: actions/download-artifact@v5
+        with:
+          name: linux-x86_64-musl-local-staging
+          path: ~/linux-x86_64-musl-local-staging
       - name: Download linux aarch_64 staging directory
         uses: actions/download-artifact@v5
         with:
           name: linux-aarch_64-local-staging
           path: ~/linux-aarch_64-local-staging
+      - name: Download linux aarch_64 (musl) staging directory
+        uses: actions/download-artifact@v5
+        with:
+          name: linux-aarch_64-musl-local-staging
+          path: ~/linux-aarch_64-musl-local-staging
       - name: Download darwin staging directory
         uses: actions/download-artifact@v5
         with:
@@ -160,7 +174,9 @@ jobs:
           python ./scripts/merge_local_staging.py $LOCAL_STAGING_DIR/staging \
             ~/windows-x86_64-local-staging/staging \
             ~/linux-x86_64-local-staging/staging \
+            ~/linux-x86_64-musl-local-staging/staging \
             ~/linux-aarch_64-local-staging/staging \
+            ~/linux-aarch_64-musl-local-staging/staging \
             ~/osx-x86_64-local-staging/staging \
             ~/osx-aarch_64-local-staging/staging
 
diff --git a/bindings/java/src/main/java/org/apache/opendal/Environment.java b/bindings/java/src/main/java/org/apache/opendal/Environment.java
index ccdaab8caab7..5f6edc65d49e 100644
--- a/bindings/java/src/main/java/org/apache/opendal/Environment.java
+++ b/bindings/java/src/main/java/org/apache/opendal/Environment.java
@@ -22,6 +22,8 @@
 import java.io.IOException;
 import java.io.InputStream;
 import java.io.UncheckedIOException;
+import java.nio.file.Files;
+import java.nio.file.Paths;
 import java.util.Properties;
 
 /**
@@ -31,6 +33,7 @@ public enum Environment {
     INSTANCE;
 
     public static final String UNKNOWN = "<unknown>";
+    private static final String LIBC_PROPERTY = "org.apache.opendal.libc";
     private String classifier = UNKNOWN;
     private String projectVersion = UNKNOWN;
 
@@ -44,8 +47,18 @@ public enum Environment {
             throw new UncheckedIOException("cannot load environment properties file", e);
         }
 
+        INSTANCE.classifier = detectClassifier(System.getProperty("os.name"), System.getProperty("os.arch"));
+    }
+
+    static String detectClassifier(String osName, String osArch) {
+        final String os = osName == null ? "" : osName.toLowerCase();
+        final String arch = osArch == null ? "" : osArch.toLowerCase();
+        final boolean musl = !os.startsWith("windows") && !os.startsWith("mac") && isMusl(arch);
+        return buildClassifier(os, arch, musl);
+    }
+
+    static String buildClassifier(String os, String arch, boolean musl) {
         final StringBuilder classifier = new StringBuilder();
-        final String os = System.getProperty("os.name").toLowerCase();
         if (os.startsWith("windows")) {
             classifier.append("windows");
         } else if (os.startsWith("mac")) {
@@ -54,13 +67,49 @@ public enum Environment {
             classifier.append("linux");
         }
         classifier.append("-");
-        final String arch = System.getProperty("os.arch").toLowerCase();
         if (arch.equals("aarch64")) {
             classifier.append("aarch_64");
         } else {
             classifier.append("x86_64");
         }
-        INSTANCE.classifier = classifier.toString();
+        if (classifier.toString().startsWith("linux-") && musl) {
+            classifier.append("-musl");
+        }
+        return classifier.toString();
+    }
+
+    static boolean isMusl(String osArch) {
+        final String override = System.getProperty(LIBC_PROPERTY);
+        if (override != null) {
+            final String libc = override.trim().toLowerCase();
+            if (libc.equals("musl")) {
+                return true;
+            }
+            if (libc.equals("gnu") || libc.equals("glibc")) {
+                return false;
+            }
+        }
+
+        final String loader = muslLoaderName(osArch);
+        if (loader == null) {
+            return false;
+        }
+        return Files.exists(Paths.get("/lib", loader)) || Files.exists(Paths.get("/usr/lib", loader));
+    }
+
+    private static String muslLoaderName(String osArch) {
+        if (osArch == null) {
+            return null;
+        }
+        switch (osArch) {
+            case "aarch64":
+                return "ld-musl-aarch64.so.1";
+            case "x86_64":
+            case "amd64":
+                return "ld-musl-x86_64.so.1";
+            default:
+                return null;
+        }
     }
 
     /**
diff --git a/bindings/java/src/main/java/org/apache/opendal/NativeLibrary.java b/bindings/java/src/main/java/org/apache/opendal/NativeLibrary.java
index bc67e3237610..4e65c59d010a 100644
--- a/bindings/java/src/main/java/org/apache/opendal/NativeLibrary.java
+++ b/bindings/java/src/main/java/org/apache/opendal/NativeLibrary.java
@@ -59,6 +59,8 @@ private enum LibraryState {
      *         <ul>
      *             <li>org.apache.opendal:opendal-{version}-linux-x86_64</li>
      *             <li>org.apache.opendal:opendal-{version}-linux-aarch_64</li>
+     *             <li>org.apache.opendal:opendal-{version}-linux-x86_64-musl</li>
+     *             <li>org.apache.opendal:opendal-{version}-linux-aarch_64-musl</li>
      *             <li>org.apache.opendal:opendal-{version}-osx-x86_64</li>
      *             <li>org.apache.opendal:opendal-{version}-osx-aarch_64</li>
      *             <li>org.apache.opendal:opendal-{version}-windows-x86_64</li>
@@ -77,6 +79,9 @@ public static void loadLibrary() {
             } catch (IOException e) {
                 libraryLoaded.set(LibraryState.NOT_LOADED);
                 throw new UncheckedIOException("Unable to load the OpenDAL shared library", e);
+            } catch (RuntimeException | Error e) {
+                libraryLoaded.set(LibraryState.NOT_LOADED);
+                throw e;
             }
             libraryLoaded.set(LibraryState.LOADED);
             return;
@@ -103,22 +108,89 @@ private static void doLoadLibrary() throws IOException {
     }
 
     private static void doLoadBundledLibrary() throws IOException {
-        final String libraryPath = bundledLibraryPath();
-        try (final InputStream is = NativeObject.class.getResourceAsStream(libraryPath)) {
-            if (is == null) {
-                throw new IOException("cannot find " + libraryPath);
+        final String libraryName = System.mapLibraryName("opendal_java");
+        final String[] libraryPaths = bundledLibraryPaths(libraryName);
+
+        final UnsatisfiedLinkError[] linkErrors = new UnsatisfiedLinkError[libraryPaths.length];
+        for (int i = 0; i < libraryPaths.length; i++) {
+            final String libraryPath = libraryPaths[i];
+            try (final InputStream is = NativeObject.class.getResourceAsStream(libraryPath)) {
+                if (is == null) {
+                    continue;
+                }
+
+                final File tmpFile = createTempLibraryFile(libraryName);
+                tmpFile.deleteOnExit();
+                Files.copy(is, tmpFile.toPath(), StandardCopyOption.REPLACE_EXISTING);
+                try {
+                    System.load(tmpFile.getAbsolutePath());
+                    return;
+                } catch (UnsatisfiedLinkError e) {
+                    linkErrors[i] = e;
+                }
+            }
+        }
+
+        final StringBuilder attempted = new StringBuilder();
+        for (int i = 0; i < libraryPaths.length; i++) {
+            if (i > 0) {
+                attempted.append(", ");
+            }
+            attempted.append(libraryPaths[i]);
+        }
+
+        final UnsatisfiedLinkError last = lastNonNull(linkErrors);
+        if (last != null) {
+            final UnsatisfiedLinkError e = new UnsatisfiedLinkError(
+                    "Unable to load the OpenDAL shared library from classpath. Tried: " + attempted);
+            for (UnsatisfiedLinkError err : linkErrors) {
+                if (err != null) {
+                    e.addSuppressed(err);
+                }
             }
-            final int dot = libraryPath.indexOf('.');
-            final File tmpFile = File.createTempFile(libraryPath.substring(0, dot), libraryPath.substring(dot));
-            tmpFile.deleteOnExit();
-            Files.copy(is, tmpFile.toPath(), StandardCopyOption.REPLACE_EXISTING);
-            System.load(tmpFile.getAbsolutePath());
+            throw e;
         }
+        throw new IOException("cannot find bundled OpenDAL shared library in classpath. Tried: " + attempted);
     }
 
-    private static String bundledLibraryPath() {
+    private static String[] bundledLibraryPaths(String libraryName) {
         final String classifier = Environment.getClassifier();
-        final String libraryName = System.mapLibraryName("opendal_java");
-        return "/native/" + classifier + "/" + libraryName;
+        if (classifier.startsWith("linux-") && classifier.endsWith("-musl")) {
+            final String gnu = classifier.substring(0, classifier.length() - "-musl".length());
+            return new String[] {
+                "/native/" + classifier + "/" + libraryName,
+                "/native/" + gnu + "/" + libraryName,
+            };
+        }
+        if (classifier.startsWith("linux-")) {
+            return new String[] {
+                "/native/" + classifier + "/" + libraryName,
+                "/native/" + classifier + "-musl/" + libraryName,
+            };
+        }
+        return new String[] {"/native/" + classifier + "/" + libraryName};
+    }
+
+    private static File createTempLibraryFile(String libraryName) throws IOException {
+        final int dot = libraryName.lastIndexOf('.');
+        final String prefix;
+        final String suffix;
+        if (dot >= 0) {
+            prefix = libraryName.substring(0, dot);
+            suffix = libraryName.substring(dot);
+        } else {
+            prefix = libraryName;
+            suffix = null;
+        }
+        return File.createTempFile(prefix + "-", suffix);
+    }
+
+    private static UnsatisfiedLinkError lastNonNull(UnsatisfiedLinkError[] errors) {
+        for (int i = errors.length - 1; i >= 0; i--) {
+            if (errors[i] != null) {
+                return errors[i];
+            }
+        }
+        return null;
     }
 }
diff --git a/bindings/java/src/test/java/org/apache/opendal/EnvironmentTest.java b/bindings/java/src/test/java/org/apache/opendal/EnvironmentTest.java
new file mode 100644
index 000000000000..3eeb264fb481
--- /dev/null
+++ b/bindings/java/src/test/java/org/apache/opendal/EnvironmentTest.java
@@ -0,0 +1,67 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you 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.
+ */
+
+package org.apache.opendal;
+
+import static org.assertj.core.api.Assertions.assertThat;
+
+import org.junit.jupiter.api.Test;
+
+public class EnvironmentTest {
+    @Test
+    public void testBuildClassifierLinuxGnuX8664() {
+        assertThat(Environment.buildClassifier("linux", "x86_64", false)).isEqualTo("linux-x86_64");
+    }
+
+    @Test
+    public void testBuildClassifierLinuxMuslX8664() {
+        assertThat(Environment.buildClassifier("linux", "x86_64", true)).isEqualTo("linux-x86_64-musl");
+    }
+
+    @Test
+    public void testBuildClassifierLinuxMuslAarch64() {
+        assertThat(Environment.buildClassifier("linux", "aarch64", true)).isEqualTo("linux-aarch_64-musl");
+    }
+
+    @Test
+    public void testBuildClassifierNonLinuxIgnoreMusl() {
+        assertThat(Environment.buildClassifier("mac os x", "x86_64", true)).isEqualTo("osx-x86_64");
+        assertThat(Environment.buildClassifier("windows", "x86_64", true)).isEqualTo("windows-x86_64");
+    }
+
+    @Test
+    public void testIsMuslOverride() {
+        final String key = "org.apache.opendal.libc";
+        final String previous = System.getProperty(key);
+        try {
+            System.setProperty(key, "musl");
+            assertThat(Environment.isMusl("x86_64")).isTrue();
+
+            System.setProperty(key, "gnu");
+            assertThat(Environment.isMusl("x86_64")).isFalse();
+        } finally {
+            if (previous == null) {
+                System.clearProperty(key);
+            } else {
+                System.setProperty(key, previous);
+            }
+        }
+    }
+}
+
diff --git a/bindings/java/tools/build.py b/bindings/java/tools/build.py
index 0eedaa65ea4c..c0fa55121a27 100755
--- a/bindings/java/tools/build.py
+++ b/bindings/java/tools/build.py
@@ -30,8 +30,12 @@ def classifier_to_target(classifier: str) -> str:
         return "x86_64-apple-darwin"
     if classifier == "linux-aarch_64":
         return "aarch64-unknown-linux-gnu"
+    if classifier == "linux-aarch_64-musl":
+        return "aarch64-unknown-linux-musl"
     if classifier == "linux-x86_64":
         return "x86_64-unknown-linux-gnu"
+    if classifier == "linux-x86_64-musl":
+        return "x86_64-unknown-linux-musl"
     if classifier == "windows-x86_64":
         return "x86_64-pc-windows-msvc"
     raise Exception(f"Unsupported classifier: {classifier}")
@@ -82,8 +86,11 @@ def get_cargo_artifact_name(classifier: str) -> str:
         cmd += ["--features", args.features]
 
     if enable_zigbuild:
-        # Pin glibc to 2.17 if zigbuild has been enabled.
-        cmd += ["--target", f"{target}.2.17"]
+        # Pin glibc to 2.17 for gnu builds.
+        #
+        # Note: The `.2.17` suffix is a zig target detail and is only valid for gnu.
+        zig_target = f"{target}.2.17" if target.endswith("-gnu") else target
+        cmd += ["--target", zig_target]
     else:
         cmd += ["--target", target]
 

From e465a2f6aeec528a136df44039417175fb4f141b Mon Sep 17 00:00:00 2001
From: Xuanwo <github@xuanwo.io>
Date: Tue, 23 Dec 2025 00:02:03 +0800
Subject: [PATCH 02/11] Revert not needed changes

---
 .../java/org/apache/opendal/Environment.java  |  22 ++--
 .../org/apache/opendal/NativeLibrary.java     | 100 ++++++------------
 .../org/apache/opendal/EnvironmentTest.java   |  67 ------------
 bindings/java/tools/build.py                  |   9 +-
 4 files changed, 44 insertions(+), 154 deletions(-)
 delete mode 100644 bindings/java/src/test/java/org/apache/opendal/EnvironmentTest.java

diff --git a/bindings/java/src/main/java/org/apache/opendal/Environment.java b/bindings/java/src/main/java/org/apache/opendal/Environment.java
index 5f6edc65d49e..8ac9ac56d211 100644
--- a/bindings/java/src/main/java/org/apache/opendal/Environment.java
+++ b/bindings/java/src/main/java/org/apache/opendal/Environment.java
@@ -33,7 +33,6 @@ public enum Environment {
     INSTANCE;
 
     public static final String UNKNOWN = "<unknown>";
-    private static final String LIBC_PROPERTY = "org.apache.opendal.libc";
     private String classifier = UNKNOWN;
     private String projectVersion = UNKNOWN;
 
@@ -47,18 +46,8 @@ public enum Environment {
             throw new UncheckedIOException("cannot load environment properties file", e);
         }
 
-        INSTANCE.classifier = detectClassifier(System.getProperty("os.name"), System.getProperty("os.arch"));
-    }
-
-    static String detectClassifier(String osName, String osArch) {
-        final String os = osName == null ? "" : osName.toLowerCase();
-        final String arch = osArch == null ? "" : osArch.toLowerCase();
-        final boolean musl = !os.startsWith("windows") && !os.startsWith("mac") && isMusl(arch);
-        return buildClassifier(os, arch, musl);
-    }
-
-    static String buildClassifier(String os, String arch, boolean musl) {
         final StringBuilder classifier = new StringBuilder();
+        final String os = System.getProperty("os.name").toLowerCase();
         if (os.startsWith("windows")) {
             classifier.append("windows");
         } else if (os.startsWith("mac")) {
@@ -67,19 +56,20 @@ static String buildClassifier(String os, String arch, boolean musl) {
             classifier.append("linux");
         }
         classifier.append("-");
+        final String arch = System.getProperty("os.arch").toLowerCase();
         if (arch.equals("aarch64")) {
             classifier.append("aarch_64");
         } else {
             classifier.append("x86_64");
         }
-        if (classifier.toString().startsWith("linux-") && musl) {
+        if (classifier.toString().startsWith("linux-") && isMusl(arch)) {
             classifier.append("-musl");
         }
-        return classifier.toString();
+        INSTANCE.classifier = classifier.toString();
     }
 
-    static boolean isMusl(String osArch) {
-        final String override = System.getProperty(LIBC_PROPERTY);
+    private static boolean isMusl(String osArch) {
+        final String override = System.getProperty("org.apache.opendal.libc");
         if (override != null) {
             final String libc = override.trim().toLowerCase();
             if (libc.equals("musl")) {
diff --git a/bindings/java/src/main/java/org/apache/opendal/NativeLibrary.java b/bindings/java/src/main/java/org/apache/opendal/NativeLibrary.java
index 4e65c59d010a..f16d2d2678f8 100644
--- a/bindings/java/src/main/java/org/apache/opendal/NativeLibrary.java
+++ b/bindings/java/src/main/java/org/apache/opendal/NativeLibrary.java
@@ -59,8 +59,6 @@ private enum LibraryState {
      *         <ul>
      *             <li>org.apache.opendal:opendal-{version}-linux-x86_64</li>
      *             <li>org.apache.opendal:opendal-{version}-linux-aarch_64</li>
-     *             <li>org.apache.opendal:opendal-{version}-linux-x86_64-musl</li>
-     *             <li>org.apache.opendal:opendal-{version}-linux-aarch_64-musl</li>
      *             <li>org.apache.opendal:opendal-{version}-osx-x86_64</li>
      *             <li>org.apache.opendal:opendal-{version}-osx-aarch_64</li>
      *             <li>org.apache.opendal:opendal-{version}-windows-x86_64</li>
@@ -79,7 +77,7 @@ public static void loadLibrary() {
             } catch (IOException e) {
                 libraryLoaded.set(LibraryState.NOT_LOADED);
                 throw new UncheckedIOException("Unable to load the OpenDAL shared library", e);
-            } catch (RuntimeException | Error e) {
+            } catch (UnsatisfiedLinkError e) {
                 libraryLoaded.set(LibraryState.NOT_LOADED);
                 throw e;
             }
@@ -108,89 +106,61 @@ private static void doLoadLibrary() throws IOException {
     }
 
     private static void doLoadBundledLibrary() throws IOException {
-        final String libraryName = System.mapLibraryName("opendal_java");
-        final String[] libraryPaths = bundledLibraryPaths(libraryName);
-
-        final UnsatisfiedLinkError[] linkErrors = new UnsatisfiedLinkError[libraryPaths.length];
-        for (int i = 0; i < libraryPaths.length; i++) {
-            final String libraryPath = libraryPaths[i];
-            try (final InputStream is = NativeObject.class.getResourceAsStream(libraryPath)) {
-                if (is == null) {
-                    continue;
-                }
-
-                final File tmpFile = createTempLibraryFile(libraryName);
+        final String libraryPath = bundledLibraryPath();
+        UnsatisfiedLinkError linkError = null;
+        try (final InputStream is = NativeObject.class.getResourceAsStream(libraryPath)) {
+            if (is != null) {
+                final int dot = libraryPath.indexOf('.');
+                final File tmpFile = File.createTempFile(libraryPath.substring(0, dot), libraryPath.substring(dot));
                 tmpFile.deleteOnExit();
                 Files.copy(is, tmpFile.toPath(), StandardCopyOption.REPLACE_EXISTING);
                 try {
                     System.load(tmpFile.getAbsolutePath());
                     return;
                 } catch (UnsatisfiedLinkError e) {
-                    linkErrors[i] = e;
+                    linkError = e;
                 }
             }
         }
 
-        final StringBuilder attempted = new StringBuilder();
-        for (int i = 0; i < libraryPaths.length; i++) {
-            if (i > 0) {
-                attempted.append(", ");
+        final String fallbackLibraryPath = fallbackBundledLibraryPath();
+        if (fallbackLibraryPath == null) {
+            if (linkError != null) {
+                throw linkError;
             }
-            attempted.append(libraryPaths[i]);
+            throw new IOException("cannot find " + libraryPath);
         }
-
-        final UnsatisfiedLinkError last = lastNonNull(linkErrors);
-        if (last != null) {
-            final UnsatisfiedLinkError e = new UnsatisfiedLinkError(
-                    "Unable to load the OpenDAL shared library from classpath. Tried: " + attempted);
-            for (UnsatisfiedLinkError err : linkErrors) {
-                if (err != null) {
-                    e.addSuppressed(err);
+        try (final InputStream is = NativeObject.class.getResourceAsStream(fallbackLibraryPath)) {
+            if (is == null) {
+                if (linkError != null) {
+                    throw linkError;
                 }
+                throw new IOException("cannot find " + libraryPath);
             }
-            throw e;
+            final int dot = fallbackLibraryPath.indexOf('.');
+            final File tmpFile = File.createTempFile(fallbackLibraryPath.substring(0, dot), fallbackLibraryPath.substring(dot));
+            tmpFile.deleteOnExit();
+            Files.copy(is, tmpFile.toPath(), StandardCopyOption.REPLACE_EXISTING);
+            System.load(tmpFile.getAbsolutePath());
         }
-        throw new IOException("cannot find bundled OpenDAL shared library in classpath. Tried: " + attempted);
     }
 
-    private static String[] bundledLibraryPaths(String libraryName) {
+    private static String bundledLibraryPath() {
         final String classifier = Environment.getClassifier();
-        if (classifier.startsWith("linux-") && classifier.endsWith("-musl")) {
-            final String gnu = classifier.substring(0, classifier.length() - "-musl".length());
-            return new String[] {
-                "/native/" + classifier + "/" + libraryName,
-                "/native/" + gnu + "/" + libraryName,
-            };
-        }
-        if (classifier.startsWith("linux-")) {
-            return new String[] {
-                "/native/" + classifier + "/" + libraryName,
-                "/native/" + classifier + "-musl/" + libraryName,
-            };
-        }
-        return new String[] {"/native/" + classifier + "/" + libraryName};
+        final String libraryName = System.mapLibraryName("opendal_java");
+        return "/native/" + classifier + "/" + libraryName;
     }
 
-    private static File createTempLibraryFile(String libraryName) throws IOException {
-        final int dot = libraryName.lastIndexOf('.');
-        final String prefix;
-        final String suffix;
-        if (dot >= 0) {
-            prefix = libraryName.substring(0, dot);
-            suffix = libraryName.substring(dot);
-        } else {
-            prefix = libraryName;
-            suffix = null;
+    private static String fallbackBundledLibraryPath() {
+        final String classifier = Environment.getClassifier();
+        if (!classifier.startsWith("linux-")) {
+            return null;
         }
-        return File.createTempFile(prefix + "-", suffix);
-    }
-
-    private static UnsatisfiedLinkError lastNonNull(UnsatisfiedLinkError[] errors) {
-        for (int i = errors.length - 1; i >= 0; i--) {
-            if (errors[i] != null) {
-                return errors[i];
-            }
+        final String libraryName = System.mapLibraryName("opendal_java");
+        if (classifier.endsWith("-musl")) {
+            final String gnu = classifier.substring(0, classifier.length() - "-musl".length());
+            return "/native/" + gnu + "/" + libraryName;
         }
-        return null;
+        return "/native/" + classifier + "-musl/" + libraryName;
     }
 }
diff --git a/bindings/java/src/test/java/org/apache/opendal/EnvironmentTest.java b/bindings/java/src/test/java/org/apache/opendal/EnvironmentTest.java
deleted file mode 100644
index 3eeb264fb481..000000000000
--- a/bindings/java/src/test/java/org/apache/opendal/EnvironmentTest.java
+++ /dev/null
@@ -1,67 +0,0 @@
-/*
- * Licensed to the Apache Software Foundation (ASF) under one
- * or more contributor license agreements.  See the NOTICE file
- * distributed with this work for additional information
- * regarding copyright ownership.  The ASF licenses this file
- * to you 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.
- */
-
-package org.apache.opendal;
-
-import static org.assertj.core.api.Assertions.assertThat;
-
-import org.junit.jupiter.api.Test;
-
-public class EnvironmentTest {
-    @Test
-    public void testBuildClassifierLinuxGnuX8664() {
-        assertThat(Environment.buildClassifier("linux", "x86_64", false)).isEqualTo("linux-x86_64");
-    }
-
-    @Test
-    public void testBuildClassifierLinuxMuslX8664() {
-        assertThat(Environment.buildClassifier("linux", "x86_64", true)).isEqualTo("linux-x86_64-musl");
-    }
-
-    @Test
-    public void testBuildClassifierLinuxMuslAarch64() {
-        assertThat(Environment.buildClassifier("linux", "aarch64", true)).isEqualTo("linux-aarch_64-musl");
-    }
-
-    @Test
-    public void testBuildClassifierNonLinuxIgnoreMusl() {
-        assertThat(Environment.buildClassifier("mac os x", "x86_64", true)).isEqualTo("osx-x86_64");
-        assertThat(Environment.buildClassifier("windows", "x86_64", true)).isEqualTo("windows-x86_64");
-    }
-
-    @Test
-    public void testIsMuslOverride() {
-        final String key = "org.apache.opendal.libc";
-        final String previous = System.getProperty(key);
-        try {
-            System.setProperty(key, "musl");
-            assertThat(Environment.isMusl("x86_64")).isTrue();
-
-            System.setProperty(key, "gnu");
-            assertThat(Environment.isMusl("x86_64")).isFalse();
-        } finally {
-            if (previous == null) {
-                System.clearProperty(key);
-            } else {
-                System.setProperty(key, previous);
-            }
-        }
-    }
-}
-
diff --git a/bindings/java/tools/build.py b/bindings/java/tools/build.py
index c0fa55121a27..3bf19f0036af 100755
--- a/bindings/java/tools/build.py
+++ b/bindings/java/tools/build.py
@@ -85,12 +85,9 @@ def get_cargo_artifact_name(classifier: str) -> str:
     if args.features:
         cmd += ["--features", args.features]
 
-    if enable_zigbuild:
-        # Pin glibc to 2.17 for gnu builds.
-        #
-        # Note: The `.2.17` suffix is a zig target detail and is only valid for gnu.
-        zig_target = f"{target}.2.17" if target.endswith("-gnu") else target
-        cmd += ["--target", zig_target]
+    if enable_zigbuild and target.endswith("-gnu"):
+        # Pin glibc to 2.17 if zigbuild has been enabled.
+        cmd += ["--target", f"{target}.2.17"]
     else:
         cmd += ["--target", target]
 

From e91a7234d31fa0a8b0f61b9d92ee7235403d199e Mon Sep 17 00:00:00 2001
From: Xuanwo <github@xuanwo.io>
Date: Tue, 23 Dec 2025 01:05:56 +0800
Subject: [PATCH 03/11] try fix musl build

---
 .github/workflows/release_java.yml                    |  4 ++++
 .../src/main/java/org/apache/opendal/Environment.java | 11 -----------
 bindings/java/tools/build.py                          |  7 +++++--
 3 files changed, 9 insertions(+), 13 deletions(-)

diff --git a/.github/workflows/release_java.yml b/.github/workflows/release_java.yml
index fea5d57226a5..b7b59a3f835c 100644
--- a/.github/workflows/release_java.yml
+++ b/.github/workflows/release_java.yml
@@ -80,6 +80,10 @@ jobs:
         if: ${{ contains(matrix.os, 'ubuntu') }}
         run: pip install cargo-zigbuild
 
+      - name: Setup linux for musl
+        if: ${{ contains(matrix.os, 'ubuntu') && contains(matrix.classifier, 'musl') }}
+        run: sudo apt-get install musl-tools
+
       - name: Local staging
         working-directory: bindings/java
         shell: bash
diff --git a/bindings/java/src/main/java/org/apache/opendal/Environment.java b/bindings/java/src/main/java/org/apache/opendal/Environment.java
index 8ac9ac56d211..59d7c1924b51 100644
--- a/bindings/java/src/main/java/org/apache/opendal/Environment.java
+++ b/bindings/java/src/main/java/org/apache/opendal/Environment.java
@@ -69,17 +69,6 @@ public enum Environment {
     }
 
     private static boolean isMusl(String osArch) {
-        final String override = System.getProperty("org.apache.opendal.libc");
-        if (override != null) {
-            final String libc = override.trim().toLowerCase();
-            if (libc.equals("musl")) {
-                return true;
-            }
-            if (libc.equals("gnu") || libc.equals("glibc")) {
-                return false;
-            }
-        }
-
         final String loader = muslLoaderName(osArch);
         if (loader == null) {
             return false;
diff --git a/bindings/java/tools/build.py b/bindings/java/tools/build.py
index 3bf19f0036af..6eeae93e3fcd 100755
--- a/bindings/java/tools/build.py
+++ b/bindings/java/tools/build.py
@@ -72,8 +72,11 @@ def get_cargo_artifact_name(classifier: str) -> str:
     print("$ " + subprocess.list2cmdline(command))
     subprocess.run(command, cwd=basedir, check=True)
 
-    # Enable zigbuild if flag enabled and we are building linux target
-    enable_zigbuild = args.enable_zigbuild == "true" and "linux" in target
+    # Enable zigbuild if flag enabled and we are building linux gnu target.
+    #
+    # For musl targets, prefer using the system musl toolchain (e.g. `musl-tools` on Ubuntu)
+    # instead of zigbuild.
+    enable_zigbuild = args.enable_zigbuild == "true" and "linux" in target and not target.endswith("-musl")
 
     cmd = [
         "cargo",

From f7751e1f553b9a21ca967a75b46defee821a3d78 Mon Sep 17 00:00:00 2001
From: Xuanwo <github@xuanwo.io>
Date: Tue, 23 Dec 2025 01:11:21 +0800
Subject: [PATCH 04/11] format code

---
 .../java/src/main/java/org/apache/opendal/NativeLibrary.java   | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/bindings/java/src/main/java/org/apache/opendal/NativeLibrary.java b/bindings/java/src/main/java/org/apache/opendal/NativeLibrary.java
index f16d2d2678f8..f062ad1aa758 100644
--- a/bindings/java/src/main/java/org/apache/opendal/NativeLibrary.java
+++ b/bindings/java/src/main/java/org/apache/opendal/NativeLibrary.java
@@ -138,7 +138,8 @@ private static void doLoadBundledLibrary() throws IOException {
                 throw new IOException("cannot find " + libraryPath);
             }
             final int dot = fallbackLibraryPath.indexOf('.');
-            final File tmpFile = File.createTempFile(fallbackLibraryPath.substring(0, dot), fallbackLibraryPath.substring(dot));
+            final File tmpFile =
+                    File.createTempFile(fallbackLibraryPath.substring(0, dot), fallbackLibraryPath.substring(dot));
             tmpFile.deleteOnExit();
             Files.copy(is, tmpFile.toPath(), StandardCopyOption.REPLACE_EXISTING);
             System.load(tmpFile.getAbsolutePath());

From 378bef4025a4395ad9a83a5e7ab52cc59e09aef9 Mon Sep 17 00:00:00 2001
From: Xuanwo <github@xuanwo.io>
Date: Tue, 23 Dec 2025 06:06:43 +0800
Subject: [PATCH 05/11] fix

---
 bindings/java/Cargo.toml     |  2 +-
 bindings/java/tools/build.py | 26 ++++++++++++++++++++++++++
 core/src/lib.rs              |  2 ++
 3 files changed, 29 insertions(+), 1 deletion(-)

diff --git a/bindings/java/Cargo.toml b/bindings/java/Cargo.toml
index a671f6c6136f..ff723ace4a5d 100644
--- a/bindings/java/Cargo.toml
+++ b/bindings/java/Cargo.toml
@@ -27,7 +27,7 @@ repository = "https://github.com/apache/opendal"
 rust-version = "1.85"
 
 [lib]
-crate-type = ["cdylib"]
+crate-type = ["cdylib", "staticlib"]
 doc = false
 
 [features]
diff --git a/bindings/java/tools/build.py b/bindings/java/tools/build.py
index 6eeae93e3fcd..15b7ddf45472 100755
--- a/bindings/java/tools/build.py
+++ b/bindings/java/tools/build.py
@@ -50,6 +50,11 @@ def get_cargo_artifact_name(classifier: str) -> str:
         return "opendal_java.dll"
     raise Exception(f"Unsupported classifier: {classifier}")
 
+def get_static_artifact_name(classifier: str) -> str:
+    if classifier.startswith("windows"):
+        return "opendal_java.lib"
+    return "libopendal_java.a"
+
 
 if __name__ == "__main__":
     basedir = Path(__file__).parent.parent
@@ -103,6 +108,27 @@ def get_cargo_artifact_name(classifier: str) -> str:
 
     # History reason of cargo profiles.
     profile = "debug" if args.profile in ["dev", "test", "bench"] else args.profile
+
+    if target.endswith("-musl"):
+        static_artifact = get_static_artifact_name(args.classifier)
+        src = output / target / profile / static_artifact
+        artifact = get_cargo_artifact_name(args.classifier)
+        dst = basedir / "target" / "classes" / "native" / args.classifier / artifact
+        dst.parent.mkdir(exist_ok=True, parents=True)
+
+        link_cmd = [
+            "musl-gcc",
+            "-shared",
+            "-o",
+            str(dst),
+            "-Wl,--whole-archive",
+            str(src),
+            "-Wl,--no-whole-archive",
+        ]
+        print("$ " + subprocess.list2cmdline(link_cmd))
+        subprocess.run(link_cmd, cwd=basedir, check=True)
+        raise SystemExit(0)
+
     artifact = get_cargo_artifact_name(args.classifier)
     src = output / target / profile / artifact
     dst = basedir / "target" / "classes" / "native" / args.classifier / artifact
diff --git a/core/src/lib.rs b/core/src/lib.rs
index c58e39325ca1..67b93454f515 100644
--- a/core/src/lib.rs
+++ b/core/src/lib.rs
@@ -140,6 +140,8 @@ pub mod services {
     pub use opendal_service_tikv::*;
     #[cfg(feature = "services-upyun")]
     pub use opendal_service_upyun::*;
+    #[cfg(feature = "services-vercel-artifacts")]
+    pub use opendal_service_vercel_artifacts::*;
     #[cfg(feature = "services-vercel-blob")]
     pub use opendal_service_vercel_blob::*;
     #[cfg(feature = "services-webdav")]

From 034370dd2451c411bf1e79c36b9773d821e32f07 Mon Sep 17 00:00:00 2001
From: Xuanwo <github@xuanwo.io>
Date: Tue, 23 Dec 2025 19:04:32 +0800
Subject: [PATCH 06/11] refactor

---
 bindings/java/tools/build.py | 13 ++++++-------
 1 file changed, 6 insertions(+), 7 deletions(-)

diff --git a/bindings/java/tools/build.py b/bindings/java/tools/build.py
index 15b7ddf45472..94a2f9e91f7c 100755
--- a/bindings/java/tools/build.py
+++ b/bindings/java/tools/build.py
@@ -127,10 +127,9 @@ def get_static_artifact_name(classifier: str) -> str:
         ]
         print("$ " + subprocess.list2cmdline(link_cmd))
         subprocess.run(link_cmd, cwd=basedir, check=True)
-        raise SystemExit(0)
-
-    artifact = get_cargo_artifact_name(args.classifier)
-    src = output / target / profile / artifact
-    dst = basedir / "target" / "classes" / "native" / args.classifier / artifact
-    dst.parent.mkdir(exist_ok=True, parents=True)
-    shutil.copy2(src, dst)
+    else:
+        artifact = get_cargo_artifact_name(args.classifier)
+        src = output / target / profile / artifact
+        dst = basedir / "target" / "classes" / "native" / args.classifier / artifact
+        dst.parent.mkdir(exist_ok=True, parents=True)
+        shutil.copy2(src, dst)

From 729ced3d495eecfd1f23c462ab51cc8c3df217c2 Mon Sep 17 00:00:00 2001
From: Xuanwo <github@xuanwo.io>
Date: Fri, 26 Dec 2025 22:53:44 +0800
Subject: [PATCH 07/11] Build dyn lib via docker

---
 .github/workflows/release_java.yml            | 34 ++++++++++++++-
 .../java/org/apache/opendal/Environment.java  | 28 -------------
 bindings/java/tools/build.py                  | 42 +++++++------------
 3 files changed, 46 insertions(+), 58 deletions(-)

diff --git a/.github/workflows/release_java.yml b/.github/workflows/release_java.yml
index b7b59a3f835c..eb083f6b0eaa 100644
--- a/.github/workflows/release_java.yml
+++ b/.github/workflows/release_java.yml
@@ -80,20 +80,50 @@ jobs:
         if: ${{ contains(matrix.os, 'ubuntu') }}
         run: pip install cargo-zigbuild
 
-      - name: Setup linux for musl
+      - name: Build linux musl JNI library in Alpine
         if: ${{ contains(matrix.os, 'ubuntu') && contains(matrix.classifier, 'musl') }}
-        run: sudo apt-get install musl-tools
+        shell: bash
+        run: |
+          set -euo pipefail
+          UID="$(id -u)"
+          GID="$(id -g)"
+
+          docker run --rm \
+            -e HOST_UID="$UID" \
+            -e HOST_GID="$GID" \
+            -v "$GITHUB_WORKSPACE":/work \
+            -w /work/bindings/java \
+            rust:1.85-alpine3.20 \
+            sh -lc '
+              set -eu
+              apk add --no-cache python3 build-base cmake pkgconfig git protobuf sqlite-dev zlib-dev
+              export PATH=/usr/local/cargo/bin:$PATH
+
+              python3 tools/build.py \
+                --classifier "${{ matrix.classifier }}" \
+                --profile release \
+                --features services-all \
+                --enable-zigbuild false
+
+              chown -R "$HOST_UID:$HOST_GID" /work/bindings/java/target
+            '
 
       - name: Local staging
         working-directory: bindings/java
         shell: bash
         run: |
+          EXTRA_MVN_ARGS=""
+          if [[ "${{ matrix.classifier }}" == *"musl" ]]; then
+            EXTRA_MVN_ARGS="-Dexec.skip=true"
+          fi
+
           ./mvnw -Papache-release package verify org.sonatype.plugins:nexus-staging-maven-plugin:deploy \
             -DskipTests=true \
             -Djni.classifier=${{ matrix.classifier }} \
             -Dcargo-build.profile=release \
             -Dcargo-build.features=services-all \
             -Dcargo-build.enableZigbuild=${{ env.CARGO_BUILD_ENABLE_ZIGBUILD }} \
+            $EXTRA_MVN_ARGS \
             -DaltStagingDirectory=local-staging \
             -DskipRemoteStaging=true \
             -DserverId=apache.releases.https \
diff --git a/bindings/java/src/main/java/org/apache/opendal/Environment.java b/bindings/java/src/main/java/org/apache/opendal/Environment.java
index 59d7c1924b51..ccdaab8caab7 100644
--- a/bindings/java/src/main/java/org/apache/opendal/Environment.java
+++ b/bindings/java/src/main/java/org/apache/opendal/Environment.java
@@ -22,8 +22,6 @@
 import java.io.IOException;
 import java.io.InputStream;
 import java.io.UncheckedIOException;
-import java.nio.file.Files;
-import java.nio.file.Paths;
 import java.util.Properties;
 
 /**
@@ -62,35 +60,9 @@ public enum Environment {
         } else {
             classifier.append("x86_64");
         }
-        if (classifier.toString().startsWith("linux-") && isMusl(arch)) {
-            classifier.append("-musl");
-        }
         INSTANCE.classifier = classifier.toString();
     }
 
-    private static boolean isMusl(String osArch) {
-        final String loader = muslLoaderName(osArch);
-        if (loader == null) {
-            return false;
-        }
-        return Files.exists(Paths.get("/lib", loader)) || Files.exists(Paths.get("/usr/lib", loader));
-    }
-
-    private static String muslLoaderName(String osArch) {
-        if (osArch == null) {
-            return null;
-        }
-        switch (osArch) {
-            case "aarch64":
-                return "ld-musl-aarch64.so.1";
-            case "x86_64":
-            case "amd64":
-                return "ld-musl-x86_64.so.1";
-            default:
-                return null;
-        }
-    }
-
     /**
      * Returns the classifier of the compiled environment.
      *
diff --git a/bindings/java/tools/build.py b/bindings/java/tools/build.py
index 94a2f9e91f7c..fdf4ece2cfbd 100755
--- a/bindings/java/tools/build.py
+++ b/bindings/java/tools/build.py
@@ -19,6 +19,7 @@
 
 from argparse import ArgumentDefaultsHelpFormatter, ArgumentParser
 from pathlib import Path
+import glob
 import shutil
 import subprocess
 
@@ -50,10 +51,8 @@ def get_cargo_artifact_name(classifier: str) -> str:
         return "opendal_java.dll"
     raise Exception(f"Unsupported classifier: {classifier}")
 
-def get_static_artifact_name(classifier: str) -> str:
-    if classifier.startswith("windows"):
-        return "opendal_java.lib"
-    return "libopendal_java.a"
+def is_musl_runtime() -> bool:
+    return len(glob.glob("/lib/ld-musl-*.so.1")) > 0 or len(glob.glob("/usr/lib/ld-musl-*.so.1")) > 0
 
 
 if __name__ == "__main__":
@@ -109,27 +108,14 @@ def get_static_artifact_name(classifier: str) -> str:
     # History reason of cargo profiles.
     profile = "debug" if args.profile in ["dev", "test", "bench"] else args.profile
 
-    if target.endswith("-musl"):
-        static_artifact = get_static_artifact_name(args.classifier)
-        src = output / target / profile / static_artifact
-        artifact = get_cargo_artifact_name(args.classifier)
-        dst = basedir / "target" / "classes" / "native" / args.classifier / artifact
-        dst.parent.mkdir(exist_ok=True, parents=True)
-
-        link_cmd = [
-            "musl-gcc",
-            "-shared",
-            "-o",
-            str(dst),
-            "-Wl,--whole-archive",
-            str(src),
-            "-Wl,--no-whole-archive",
-        ]
-        print("$ " + subprocess.list2cmdline(link_cmd))
-        subprocess.run(link_cmd, cwd=basedir, check=True)
-    else:
-        artifact = get_cargo_artifact_name(args.classifier)
-        src = output / target / profile / artifact
-        dst = basedir / "target" / "classes" / "native" / args.classifier / artifact
-        dst.parent.mkdir(exist_ok=True, parents=True)
-        shutil.copy2(src, dst)
+    artifact = get_cargo_artifact_name(args.classifier)
+    src = output / target / profile / artifact
+    dst = basedir / "target" / "classes" / "native" / args.classifier / artifact
+    dst.parent.mkdir(exist_ok=True, parents=True)
+
+    if target.endswith("-musl") and not is_musl_runtime():
+        raise Exception(
+            "Building musl artifacts requires running inside a musl environment (e.g. Alpine)."
+        )
+
+    shutil.copy2(src, dst)

From 7e26316a26ba54528f57c3d0c992643d8bb9d9e3 Mon Sep 17 00:00:00 2001
From: Xuanwo <github@xuanwo.io>
Date: Mon, 12 Jan 2026 22:23:48 +0800
Subject: [PATCH 08/11] Fix CI

---
 .github/workflows/release_java.yml | 13 +++++++++----
 1 file changed, 9 insertions(+), 4 deletions(-)

diff --git a/.github/workflows/release_java.yml b/.github/workflows/release_java.yml
index eb083f6b0eaa..777781ffc59e 100644
--- a/.github/workflows/release_java.yml
+++ b/.github/workflows/release_java.yml
@@ -85,12 +85,17 @@ jobs:
         shell: bash
         run: |
           set -euo pipefail
-          UID="$(id -u)"
-          GID="$(id -g)"
+          HOST_UID="$(id -u)"
+          HOST_GID="$(id -g)"
+          PLATFORM="linux/amd64"
+          if [[ "${{ matrix.classifier }}" == *"aarch_64"* ]]; then
+            PLATFORM="linux/arm64"
+          fi
 
           docker run --rm \
-            -e HOST_UID="$UID" \
-            -e HOST_GID="$GID" \
+            --platform "$PLATFORM" \
+            -e HOST_UID="$HOST_UID" \
+            -e HOST_GID="$HOST_GID" \
             -v "$GITHUB_WORKSPACE":/work \
             -w /work/bindings/java \
             rust:1.85-alpine3.20 \

From 3333798516dd042ee5e5a22c349a41744acf6cae Mon Sep 17 00:00:00 2001
From: Xuanwo <github@xuanwo.io>
Date: Wed, 13 May 2026 22:59:49 +0800
Subject: [PATCH 09/11] ci(bindings/java): use multi-arch alpine for musl smoke

---
 .github/workflows/release_java.yml | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/.github/workflows/release_java.yml b/.github/workflows/release_java.yml
index ca2185a69ad5..e761869d99dd 100644
--- a/.github/workflows/release_java.yml
+++ b/.github/workflows/release_java.yml
@@ -149,9 +149,10 @@ jobs:
             --platform "$PLATFORM" \
             -v "$GITHUB_WORKSPACE":/work \
             -w /work/bindings/java \
-            eclipse-temurin:17-jdk-alpine \
+            alpine:3.20 \
             sh -lc '
               set -eu
+              apk add --no-cache openjdk17-jdk
               BASE_JAR="$(find target -maxdepth 1 -name "opendal-*.jar" ! -name "*-linux-*.jar" ! -name "*-sources.jar" ! -name "*-javadoc.jar" | head -n 1)"
               NATIVE_JAR="$(find target -maxdepth 1 -name "opendal-*-${{ matrix.classifier }}.jar" | head -n 1)"
               test -n "$BASE_JAR"

From 36e4199ac1f9b4fe5bfdd8a4137d4417e4f6cc54 Mon Sep 17 00:00:00 2001
From: Xuanwo <github@xuanwo.io>
Date: Thu, 14 May 2026 10:47:19 +0800
Subject: [PATCH 10/11] ci(bindings/java): skip nexus staging on pull requests

---
 .github/workflows/release_java.yml | 20 ++++++++++++++------
 1 file changed, 14 insertions(+), 6 deletions(-)

diff --git a/.github/workflows/release_java.yml b/.github/workflows/release_java.yml
index e761869d99dd..12f4cc0e66a9 100644
--- a/.github/workflows/release_java.yml
+++ b/.github/workflows/release_java.yml
@@ -121,16 +121,22 @@ jobs:
             EXTRA_MVN_ARGS="-Dexec.skip=true"
           fi
 
-          ./mvnw -Papache-release package verify org.sonatype.plugins:nexus-staging-maven-plugin:deploy \
+          MVN_GOALS="package verify"
+          if [[ "${{ github.event_name }}" != "pull_request" ]]; then
+            MVN_GOALS="$MVN_GOALS org.sonatype.plugins:nexus-staging-maven-plugin:deploy"
+            EXTRA_MVN_ARGS="$EXTRA_MVN_ARGS \
+              -DaltStagingDirectory=local-staging \
+              -DskipRemoteStaging=true \
+              -DserverId=apache.releases.https \
+              -DnexusUrl=https://repository.apache.org"
+          fi
+
+          ./mvnw -Papache-release $MVN_GOALS \
             -DskipTests=true \
             -Djni.classifier=${{ matrix.classifier }} \
             -Dcargo-build.profile=release \
             -Dcargo-build.enableZigbuild=${{ env.CARGO_BUILD_ENABLE_ZIGBUILD }} \
-            $EXTRA_MVN_ARGS \
-            -DaltStagingDirectory=local-staging \
-            -DskipRemoteStaging=true \
-            -DserverId=apache.releases.https \
-            -DnexusUrl=https://repository.apache.org
+            $EXTRA_MVN_ARGS
         env:
           MAVEN_USERNAME: ${{ secrets.NEXUS_STAGE_DEPLOYER_USER }}
           MAVEN_CENTRAL_TOKEN: ${{ secrets.NEXUS_STAGE_DEPLOYER_PW }}
@@ -170,6 +176,7 @@ jobs:
               java -cp "$BASE_JAR:$NATIVE_JAR" /tmp/OpenDALSmoke.java
             '
       - name: Upload local staging directory
+        if: ${{ github.event_name != 'pull_request' }}
         uses: actions/upload-artifact@v6
         with:
           name: ${{ matrix.classifier }}-local-staging
@@ -178,6 +185,7 @@ jobs:
           include-hidden-files: true
 
   deploy-staged-snapshots:
+    if: ${{ github.event_name != 'pull_request' }}
     runs-on: ubuntu-latest
     needs: [stage-snapshot]
     steps:

From 275a017d0dcccc0bf3c0ba09c9a8a9884d0a6ee5 Mon Sep 17 00:00:00 2001
From: Xuanwo <github@xuanwo.io>
Date: Thu, 14 May 2026 11:07:39 +0800
Subject: [PATCH 11/11] ci(bindings/java): install musl runtime dependency

---
 .github/workflows/release_java.yml | 2 +-
 bindings/java/README.md            | 4 ++++
 2 files changed, 5 insertions(+), 1 deletion(-)

diff --git a/.github/workflows/release_java.yml b/.github/workflows/release_java.yml
index 12f4cc0e66a9..067816325367 100644
--- a/.github/workflows/release_java.yml
+++ b/.github/workflows/release_java.yml
@@ -158,7 +158,7 @@ jobs:
             alpine:3.20 \
             sh -lc '
               set -eu
-              apk add --no-cache openjdk17-jdk
+              apk add --no-cache openjdk17-jdk libgcc
               BASE_JAR="$(find target -maxdepth 1 -name "opendal-*.jar" ! -name "*-linux-*.jar" ! -name "*-sources.jar" ! -name "*-javadoc.jar" | head -n 1)"
               NATIVE_JAR="$(find target -maxdepth 1 -name "opendal-*-${{ matrix.classifier }}.jar" | head -n 1)"
               test -n "$BASE_JAR"
diff --git a/bindings/java/README.md b/bindings/java/README.md
index 6e06afa09b55..6d4d1fe2966a 100644
--- a/bindings/java/README.md
+++ b/bindings/java/README.md
@@ -80,6 +80,8 @@ On musl-based Linux distributions such as Alpine, use the musl classified artifa
 
 Use `linux-aarch_64-musl` for aarch64 Linux musl environments.
 
+The musl native library is dynamically linked against musl libc and the GCC runtime. On Alpine Linux, install `libgcc` before loading the native library.
+
 ### Gradle
 
 For Gradle, you can first add the `com.google.osdetector` for automatically detect the classifier based on your platform:
@@ -101,6 +103,8 @@ dependencies {
 
 On musl-based Linux distributions such as Alpine, use `linux-x86_64-musl` or `linux-aarch_64-musl` as the classifier.
 
+The musl native library is dynamically linked against musl libc and the GCC runtime. On Alpine Linux, install `libgcc` before loading the native library.
+
 ### Classified library
 
 Note that the dependency without classifier ships all classes and resources except the "opendal_java" shared library. And those with classifier bundle only the shared library.