feat: update build scripts for native JRE creation and improve Dockerfile for Linux compatibility

Author: tae898

bindings/python/docs/development/build-architecture.md

@@ -179,7 +179,7 @@ arcadedb-ha-raft-*.jar
 
 1. `.github/workflows/test-python-bindings.yml` (download-jars job)
 2. `bindings/python/scripts/Dockerfile.build` (Docker builds)
-3. `bindings/python/scripts/setup_jars.py` (documentation/validation)
+3. `bindings/python/scripts/build-native.sh` (native builds)
 
 **Result:** The wheel excludes optional Java components that are not part of the default Python distribution.
 
@@ -189,7 +189,6 @@ arcadedb-ha-raft-*.jar
 
 - `scripts/build-native.sh`: Filtered with bash on macOS
 - `scripts/Dockerfile.build`: Filtered with bash on Linux
-- `scripts/setup_jars.py`: Filtered with Python glob
 - **Problem:** Glob patterns varied across shells, causing duplication and inconsistency
 
 **After (Fixed):** Single upstream filter
@@ -264,22 +263,27 @@ else
   download_jars_from_docker
 fi
 
-# 2. Create platform-specific JRE via jlink
+# 2. Apply jar_exclusions.txt (CRLF-safe on Windows)
+
+# 3. Create platform-specific JRE via jlink
 jlink --output jre \
   --add-modules "$MODULES" \
   --strip-debug \
   --no-man-pages \
   --no-header-files \
   --compress zip-6
 
-# 3. Copy JARs and JRE to package
-python scripts/setup_jars.py
+# 4. Remove Windows-only non-runtime artifacts when needed
+
+# 5. Stage JRE into src/arcadedb_embedded/jre
 
-# 4. Build wheel
+# 6. Build wheel
 python -m build --wheel
 ```
 
-**Simplification:** Removed ~30 lines of JAR filtering logic (now uses pre-filtered artifact)
+**Current behavior:** Native builds prefer the pre-filtered JAR artifact from CI, but still
+re-apply `jar_exclusions.txt` locally so fallback Docker downloads and Windows checkouts remain
+consistent.
 
 ## GitHub ARM64 Runners (linux/arm64)
 

bindings/python/docs/development/contributing.md

@@ -173,7 +173,7 @@ arcadedb/bindings/python/
 
 ```bash
 # Build the current package
-./scripts/build.sh base
+./scripts/build.sh
 
 # Output: dist/*.whl
 ```
@@ -182,18 +182,19 @@ arcadedb/bindings/python/
 
 1. Extracts ArcadeDB version from parent `pom.xml`
 2. Downloads appropriate JAR files with custom filtering
-3. Packages Python code with optimized JARs (see `scripts/jar_exclusions.txt`)
+3. Creates a bundled platform-specific JRE and stages optimized JARs (see `scripts/jar_exclusions.txt`)
 4. Runs tests in isolated Docker environment
 5. Creates wheel file in `dist/`
 
 ### Local Build
 
 ```bash
-# Download JARs with custom filtering
-python scripts/setup_jars.py
+# Build for the current platform
+./scripts/build.sh
 
-# Build wheel
-python -m build
+# Or target a specific supported platform on matching native hardware
+./scripts/build.sh darwin/arm64 3.12
+./scripts/build.sh windows/amd64 3.12
 
 # Install locally
 uv pip install dist/*.whl

bindings/python/scripts/Dockerfile.build

@@ -6,12 +6,12 @@
 #   PYTHON_VERSION - Python version for wheel (e.g., 3.11, 3.12, 3.13, 3.14)
 #   PACKAGE_NAME - always: arcadedb-embedded
 #   PACKAGE_DESCRIPTION - package description
-#   TARGET_PLATFORM - target platform for JRE (e.g., linux-x64, linux-arm64, darwin-x64)
+#   TARGET_PLATFORM - Linux target platform for bundled JRE (linux-x64, linux-arm64)
 
 ARG PYTHON_VERSION=3.12
 ARG PACKAGE_NAME=arcadedb-embedded
 ARG PACKAGE_DESCRIPTION="ArcadeDB embedded multi-model database with bundled JRE - no Java installation required"
-ARG ARCADEDB_TAG
+ARG ARCADEDB_TAG=latest
 ARG TARGET_PLATFORM=linux-x64
 # When set to 1, prefer jars provided in bindings/python/local-jars/lib from the build context.
 # If no local jars are present, the build fails fast to avoid silently falling back.
@@ -25,6 +25,7 @@ FROM arcadedata/arcadedb:${ARCADEDB_TAG} AS java-builder
 # nothing to do here; jars will be copied from /home/arcadedb/lib in the python-builder stage
 
 # Stage 2: Build minimal JRE with jlink
+# Docker builds are Linux-only. macOS/Windows JREs must be created on matching native hosts.
 FROM amazoncorretto:25 AS jre-builder
 
 # Install required tooling (findutils for jar exclusion, binutils for jlink)
@@ -34,6 +35,11 @@ ARG TARGET_PLATFORM
 ARG USE_LOCAL_JARS
 ARG LOCAL_JARS_HASH
 
+RUN case "$TARGET_PLATFORM" in \
+        linux-x64|linux-arm64) ;; \
+        *) echo "❌ Dockerfile.build only supports Linux TARGET_PLATFORM values (got: $TARGET_PLATFORM)" && exit 1 ;; \
+    esac
+
 WORKDIR /build
 
 # Stash upstream jars from the ArcadeDB image
@@ -145,8 +151,6 @@ FROM python:${PYTHON_VERSION}-slim AS python-builder
 RUN apt-get update && apt-get install -y \
     build-essential \
     curl \
-    file \
-    patchelf \
     && rm -rf /var/lib/apt/lists/*
 
 # Install uv for faster, deterministic installs
@@ -156,7 +160,6 @@ RUN curl -LsSf https://astral.sh/uv/install.sh | sh && uv --version
 WORKDIR /build
 
 # Copy filtered JARs from jre-builder (already has exclusions applied)
-RUN mkdir -p /build/jars
 COPY --from=jre-builder /build/jars /build/jars/
 
 # Copy JRE from jre-builder stage
@@ -170,15 +173,14 @@ COPY bindings/python/scripts/setup_jars.py ./scripts/
 COPY bindings/python/scripts/extract_version.py ./scripts/
 COPY bindings/python/scripts/write_version.py ./scripts/
 COPY bindings/python/scripts/verify_wheel_platform_tag.py ./scripts/
-COPY bindings/python/scripts/jar_exclusions.txt .
 COPY bindings/python/pyproject.toml ./
 COPY bindings/python/README.md ./
 
 # Also copy repository pom.xml so scripts/extract_version.py can read it
 COPY ../../pom.xml /arcadedb/pom.xml
 
 # Install Python build dependencies
-RUN uv pip install --system build wheel setuptools jpype1 auditwheel
+RUN uv pip install --system build wheel setuptools jpype1
 
 # Re-declare build args for this stage (required after FROM)
 ARG PACKAGE_NAME

bindings/python/scripts/build-native.sh

@@ -57,6 +57,8 @@ apply_jar_exclusions() {
     echo -e "${CYAN}📋 JAR count before exclusion: ${YELLOW}$(count_jars "$jars_dir")${NC}"
 
     while IFS= read -r pattern; do
+        pattern="${pattern%$'\r'}"
+
         if [[ -z "$pattern" ]] || [[ "${pattern#\#}" != "$pattern" ]]; then
             continue
         fi
@@ -113,33 +115,6 @@ shutil.copytree(src, dest, symlinks=True)
 PY
 }
 
-print_windows_jre_diagnostics() {
-    local jre_dir="$1"
-    local python_bin="$2"
-    local label="$3"
-
-    echo -e "${CYAN}🔎 Windows JRE diagnostics (${label})...${NC}"
-
-    "$python_bin" - "$jre_dir" << 'PY'
-import os
-import sys
-from pathlib import Path
-
-jre_dir = Path(sys.argv[1])
-files = [path for path in jre_dir.rglob('*') if path.is_file()]
-symlinks = [path for path in jre_dir.rglob('*') if path.is_symlink()]
-
-print(f"   Files: {len(files)}")
-print(f"   Symlinks: {len(symlinks)}")
-
-largest = sorted(files, key=lambda path: path.stat().st_size, reverse=True)[:15]
-for path in largest:
-    size_mb = path.stat().st_size / 1024 / 1024
-    rel_path = path.relative_to(jre_dir)
-    print(f"   {size_mb:8.1f} MB  {rel_path}")
-PY
-}
-
 # Check for Java (needed for jlink and JPype build)
 if ! command -v java &> /dev/null; then
     echo -e "${RED}❌ Java not found${NC}"
@@ -292,21 +267,14 @@ if [[ "$PLATFORM" == windows/* ]]; then
     prune_windows_jre_artifacts "$PY_BINDINGS_DIR/temp_jre"
     JRE_SIZE=$(du -sh "$PY_BINDINGS_DIR/temp_jre" | cut -f1)
     echo -e "${CYAN}📊 JRE size after Windows cleanup: ${YELLOW}${JRE_SIZE}${NC}"
-    print_windows_jre_diagnostics "$PY_BINDINGS_DIR/temp_jre" "$PYTHON_WITH_BUILD" "temp_jre"
 fi
 
 # Step 3: Copy JRE to package (JARs already filtered in place)
 echo -e "${CYAN}📦 Preparing package...${NC}"
 
 # Build and copy JRE
-rm -rf "$PY_BINDINGS_DIR/src/arcadedb_embedded/jre"
-mkdir -p "$PY_BINDINGS_DIR/src/arcadedb_embedded/jre"
 copy_tree_with_symlinks "$PY_BINDINGS_DIR/temp_jre" "$PY_BINDINGS_DIR/src/arcadedb_embedded/jre" "$PYTHON_WITH_BUILD"
 
-if [[ "$PLATFORM" == windows/* ]]; then
-    print_windows_jre_diagnostics "$PY_BINDINGS_DIR/src/arcadedb_embedded/jre" "$PYTHON_WITH_BUILD" "staged package jre"
-fi
-
 JAR_COUNT=$(ls -1 "$JARS_DIR"/*.jar | wc -l)
 echo -e "${GREEN}✅ Package prepared (${JAR_COUNT} JARs + JRE)${NC}"
 

bindings/python/scripts/build.sh

@@ -33,7 +33,7 @@ JAR_LIB_DIR="${3:-}"
 
 print_header() {
     echo -e "${BLUE}╔════════════════════════════════════════════════════════════╗${NC}"
-    echo -e "${BLUE}║  🎮 ArcadeDB Python Package - Docker Build Script          ║${NC}"
+    echo -e "${BLUE}║  🎮 ArcadeDB Python Package - Build Script                 ║${NC}"
     echo -e "${BLUE}╚════════════════════════════════════════════════════════════╝${NC}"
     echo ""
 }
@@ -60,7 +60,7 @@ print_usage() {
     echo "  If omitted, JARs are pulled from arcadedata/arcadedb:<version>"
     echo ""
     echo "Build Methods:"
-    echo "  Native: macOS builds natively on its platform"
+    echo "  Native: macOS/Windows build on matching native host architecture"
     echo "  Docker: Linux uses Docker for manylinux compliance"
     echo ""
     echo "Examples:"
@@ -74,10 +74,24 @@ print_usage() {
     echo "  ✅ Bundled platform-specific JRE (no Java required)"
     echo "  ✅ Optimized JAR selection (see scripts/jar_exclusions.txt)"
     echo "  ✅ Multi-platform support (4 platforms)"
-    echo "  📦 Size: ~215MB (compressed), ~289MB (installed)"
+    echo "  📦 Size varies by platform/version; see CI summaries for current numbers"
     echo ""
 }
 
+normalize_arch() {
+    case "$1" in
+        x86_64 | amd64)
+            echo "amd64"
+            ;;
+        aarch64 | arm64)
+            echo "arm64"
+            ;;
+        *)
+            echo "$1"
+            ;;
+    esac
+}
+
 # Check for help flag
 if [[ "${1:-}" == "-h" || "${1:-}" == "--help" ]]; then
     print_header
@@ -176,15 +190,35 @@ fi
 # Use native build if we're already on the target platform
 CURRENT_OS="$(uname -s)"
 CURRENT_ARCH="$(uname -m)"
+CURRENT_ARCH_NORMALIZED="$(normalize_arch "$CURRENT_ARCH")"
+TARGET_OS="${PLATFORM%%/*}"
+TARGET_ARCH="${PLATFORM##*/}"
 
 USE_NATIVE=false
-if [[ "$PLATFORM" == "darwin/"* ]] && [[ "$CURRENT_OS" == "Darwin" ]]; then
+if [[ "$TARGET_OS" == "darwin" ]]; then
+    if [[ "$CURRENT_OS" != "Darwin" ]]; then
+        echo -e "${RED}❌ ${PLATFORM} builds require a native macOS host${NC}"
+        echo -e "${YELLOW}💡 jlink can only create a macOS JRE when run on macOS${NC}"
+        exit 1
+    fi
+    if [[ "$CURRENT_ARCH_NORMALIZED" != "$TARGET_ARCH" ]]; then
+        echo -e "${RED}❌ ${PLATFORM} builds require a matching native macOS architecture${NC}"
+        echo -e "${YELLOW}💡 Host architecture: ${CURRENT_ARCH_NORMALIZED}; target architecture: ${TARGET_ARCH}${NC}"
+        exit 1
+    fi
     USE_NATIVE=true
-elif [[ "$PLATFORM" == "windows/"* ]] && [[ "$CURRENT_OS" == MINGW* || "$CURRENT_OS" == MSYS* || "$CURRENT_OS" == CYGWIN* ]]; then
+elif [[ "$TARGET_OS" == "windows" ]]; then
+    if [[ "$CURRENT_OS" != MINGW* && "$CURRENT_OS" != MSYS* && "$CURRENT_OS" != CYGWIN* ]]; then
+        echo -e "${RED}❌ ${PLATFORM} builds require a native Windows host${NC}"
+        echo -e "${YELLOW}💡 jlink can only create a Windows JRE when run on Windows${NC}"
+        exit 1
+    fi
+    if [[ "$CURRENT_ARCH_NORMALIZED" != "$TARGET_ARCH" ]]; then
+        echo -e "${RED}❌ ${PLATFORM} builds require a matching native Windows architecture${NC}"
+        echo -e "${YELLOW}💡 Host architecture: ${CURRENT_ARCH_NORMALIZED}; target architecture: ${TARGET_ARCH}${NC}"
+        exit 1
+    fi
     USE_NATIVE=true
-elif [[ "$PLATFORM" == "linux/amd64" ]] && [[ "$CURRENT_OS" == "Linux" ]] && [[ "$CURRENT_ARCH" == "x86_64" ]]; then
-    # For Linux, still use Docker for reproducibility (manylinux compliance)
-    USE_NATIVE=false
 fi
 
 BUILD_METHOD="Docker"
@@ -258,13 +292,6 @@ else
     # Determine Docker build platform (always Linux for cross-compilation)
     # We build ON linux/amd64 or linux/arm64, but FOR any target platform
     DOCKER_PLATFORM="${PLATFORM}"
-    if [[ "$PLATFORM" == darwin/* ]] || [[ "$PLATFORM" == windows/* ]]; then
-        # Cross-compiling for macOS/Windows - build on Linux
-        DOCKER_PLATFORM="linux/amd64"
-        echo -e "${CYAN}🔧 Cross-compiling: Building on linux/amd64 for ${YELLOW}${PLATFORM}${NC}"
-        echo ""
-    fi
-
     # Build Docker image
     echo -e "${CYAN}📦 Building Docker image...${NC}"