feat(android): add AAR package build, release and documentation

Author: Gioee

.github/workflows/main.yml

@@ -10,7 +10,7 @@ jobs:
   build:
     runs-on: ${{ matrix.os }}
     container: ${{ matrix.container && matrix.container || '' }}
-    name: ${{ matrix.name }}${{ matrix.arch && format('-{0}', matrix.arch) || '' }} build${{ matrix.arch != 'arm64-v8a' && matrix.name != 'ios-sim' && matrix.name != 'ios' && matrix.name != 'apple-xcframework' && ' + test' || ''}}
+    name: ${{ matrix.name }}${{ matrix.arch && format('-{0}', matrix.arch) || '' }} build${{ matrix.arch != 'arm64-v8a' && matrix.name != 'ios-sim' && matrix.name != 'ios' && matrix.name != 'apple-xcframework' && matrix.name != 'android-aar' && ' + test' || ''}}
     timeout-minutes: 20
     strategy:
       fail-fast: false
@@ -52,6 +52,9 @@ jobs:
           - os: macos-15
             name: apple-xcframework
             make: xcframework
+          - os: ubuntu-22.04
+            name: android-aar
+            make: aar
 
     defaults:
       run:
@@ -61,6 +64,13 @@ jobs:
 
       - uses: actions/[email protected]
 
+      - name: android setup java
+        if: matrix.name == 'android-aar'
+        uses: actions/setup-java@v4
+        with:
+          distribution: 'temurin'
+          java-version: '17'
+
       - name: windows install dependencies
         if: matrix.name == 'windows'
         run: choco install sqlite -y
@@ -188,12 +198,65 @@ jobs:
         with:
           path: artifacts
 
+      - name: zip artifacts
+        run: |
+          VERSION=$(make version)
+          for folder in "artifacts"/*; do
+            if [ -d "$folder" ]; then
+              name=$(basename "$folder")
+              if [[ "$name" != "js-apple-xcframework" && "$name" != "js-android-aar" ]]; then
+                tar -czf "${name}-${VERSION}.tar.gz" -C "$folder" .
+              fi
+              if [[ "$name" != "js-android-aar" ]]; then
+                (cd "$folder" && zip -rq "../../${name}-${VERSION}.zip" .)
+              else
+                cp "$folder"/*.aar "${name}-${VERSION}.aar"
+              fi
+            fi
+          done
+
       - name: release tag version from sqlitejs.h
         id: tag
         run: |
           VERSION=$(make version)
           if [[ "$VERSION" =~ ^[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
-            LATEST=$(curl -s -H "Authorization: token ${{ secrets.GITHUB_TOKEN }}" https://api.github.com/repos/${{ github.repository }}/releases/latest | jq -r '.name')
+            LATEST_RELEASE=$(curl -s -H "Authorization: token ${{ secrets.GITHUB_TOKEN }}" https://api.github.com/repos/${{ github.repository }}/releases/latest)
+            LATEST=$(echo "$LATEST_RELEASE" | jq -r '.name')
+            # Check artifact sizes against previous release
+            if [ -n "$LATEST" ] && [ "$LATEST" != "null" ]; then
+              echo "Checking artifact sizes against previous release: $LATEST"
+              FAILED=0
+              for artifact in js-*-${VERSION}.*; do
+                if [ ! -f "$artifact" ]; then
+                  continue
+                fi
+                # Get current artifact size
+                NEW_SIZE=$(stat -c%s "$artifact" 2>/dev/null || stat -f%z "$artifact")
+                # Get artifact name for previous release
+                ARTIFACT_NAME=$(echo "$artifact" | sed "s/${VERSION}/${LATEST}/")
+                # Get previous artifact size from GitHub API
+                OLD_SIZE=$(echo "$LATEST_RELEASE" | jq -r ".assets[] | select(.name == \"$(basename "$ARTIFACT_NAME")\") | .size")
+                if [ -z "$OLD_SIZE" ] || [ "$OLD_SIZE" = "null" ]; then
+                  echo "⚠️  Previous artifact not found: $(basename "$ARTIFACT_NAME"), skipping comparison"
+                  continue
+                fi
+                # Calculate percentage increase
+                INCREASE=$(awk "BEGIN {printf \"%.2f\", (($NEW_SIZE - $OLD_SIZE) / $OLD_SIZE) * 100}")
+                echo "📦 $artifact: $OLD_SIZE → $NEW_SIZE bytes (${INCREASE}% change)"
+                # Check if increase is more than 5%
+                if (( $(echo "$INCREASE > 5" | bc -l) )); then
+                  echo "❌ ERROR: $artifact size increased by ${INCREASE}% (limit: 5%)"
+                  FAILED=1
+                fi
+              done
+              if [ $FAILED -eq 1 ]; then
+                echo ""
+                echo "❌ One or more artifacts exceeded the 5% size increase limit"
+                exit 1
+              fi
+              echo "✅ All artifacts within 5% size increase limit"
+            fi
+
             if [[ "$VERSION" != "$LATEST" || "$GITHUB_EVENT_NAME" == "workflow_dispatch" ]]; then
               echo "version=$VERSION" >> $GITHUB_OUTPUT
             else
@@ -203,25 +266,21 @@ jobs:
           fi
           echo "❌ SQLITE_JS_VERSION not found in sqlitejs.h"
           exit 1
-          
-      - name: zip artifacts
-        run: |
-          for folder in "artifacts"/*; do
-            if [ -d "$folder" ]; then
-              name=$(basename "$folder")
-              if [[ "$name" != "js-apple-xcframework" ]]; then
-                tar -czf "${name}-${{ steps.tag.outputs.version }}.tar.gz" -C "$folder" .
-              fi
-              (cd "$folder" && zip -rq "../../${name}-${{ steps.tag.outputs.version }}.zip" .)
-            fi
-          done
+
+      - uses: actions/setup-java@v4
+        if: steps.tag.outputs.version != ''
+        with:
+          distribution: 'temurin'
+          java-version: '17'
+
+      - name: release android aar to maven central
+        if: steps.tag.outputs.version != ''
+        run: make aar && cd packages/android && ./gradlew publishAggregationToCentralPortal -PSIGNING_KEY="${{ secrets.SIGNING_KEY }}" -PSIGNING_PASSWORD="${{ secrets.SIGNING_PASSWORD }}" -PSONATYPE_USERNAME="${{ secrets.MAVEN_CENTRAL_USERNAME }}" -PSONATYPE_PASSWORD="${{ secrets.MAVEN_CENTRAL_TOKEN }}" -PVERSION="${{ steps.tag.outputs.version }}"
 
       - uses: softprops/[email protected]
         if: steps.tag.outputs.version != ''
         with:
           generate_release_notes: true
           tag_name: ${{ steps.tag.outputs.version }}
-          files: |
-            js-*-${{ steps.tag.outputs.version }}.zip
-            js-*-${{ steps.tag.outputs.version }}.tar.gz
+          files: js-*-${{ steps.tag.outputs.version }}.*
           make_latest: true

.gitignore

@@ -1,9 +1,29 @@
-.DS_Store
+# Build artifacts
+build/
+/dist
+.build
+*.a
+*.sqlite
+
+# iOS/macOS
 *.xcworkspacedata
 *.xcuserstate
 *.xcbkptlist
 *.plist
-/build
-/dist
-*.sqlite
-.build
+
+# Android
+.gradle/
+*.aar
+local.properties
+jniLibs/
+*.apk
+*.ap_
+*.dex
+
+# IDE
+.vscode
+.idea/
+*.iml
+
+# System
+.DS_Store

Makefile

@@ -216,6 +216,17 @@ $(DIST_DIR)/%.xcframework: $(LIB_NAMES)
 
 xcframework: $(DIST_DIR)/js.xcframework
 
+AAR_ARM = packages/android/src/main/jniLibs/arm64-v8a/
+AAR_X86 = packages/android/src/main/jniLibs/x86_64/
+aar:
+	mkdir -p $(AAR_ARM) $(AAR_X86)
+	$(MAKE) clean && $(MAKE) PLATFORM=android ARCH=arm64-v8a
+	mv $(DIST_DIR)/js.so $(AAR_ARM)
+	$(MAKE) clean && $(MAKE) PLATFORM=android ARCH=x86_64
+	mv $(DIST_DIR)/js.so $(AAR_X86)
+	cd packages/android && ./gradlew clean assembleRelease
+	cp packages/android/build/outputs/aar/android-release.aar $(DIST_DIR)/js.aar
+
 version:
 	@echo $(shell sed -n 's/^#define SQLITE_JS_VERSION[[:space:]]*"\([^"]*\)".*/\1/p' src/sqlitejs.h)
 
@@ -234,10 +245,12 @@ help:
 	@echo "  ios-sim (only on macOS)"
 	@echo ""
 	@echo "Targets:"
-	@echo "  all		- Build the extension (default)"
-	@echo "  clean		- Remove built files"
-	@echo "  install	- Install the extension"
-	@echo "  test		- Test the extension"
-	@echo "  help		- Display this help message"
+	@echo "  all			- Build the extension (default)"
+	@echo "  clean			- Remove built files"
+	@echo "  install		- Install the extension"
+	@echo "  test			- Test the extension"
+	@echo "  help			- Display this help message"
+	@echo "  xcframework	- Build the Apple XCFramework"
+	@echo "  aar			- Build the Android AAR package"
 
-.PHONY: all extension clean install test help version xcframework
+.PHONY: all extension clean install test help version xcframework aar

README.md

@@ -30,6 +30,16 @@ Download the appropriate pre-built binary for your platform from the official [R
 - Android
 - iOS
 
+### Loading the Extension
+
+```sql
+-- In SQLite CLI
+.load ./js
+
+-- In SQL
+SELECT load_extension('./js');
+```
+
 ### Swift Package
 
 You can [add this repository as a package dependency to your Swift project](https://developer.apple.com/documentation/xcode/adding-package-dependencies-to-your-app#Add-a-package-dependency). After adding the package, you'll need to set up SQLite with extension loading by following steps 4 and 5 of [this guide](https://github.com/sqliteai/sqlite-extensions-guide/blob/main/platforms/ios.md#4-set-up-sqlite-with-extension-loading).
@@ -53,14 +63,84 @@ log("js_version(): \(String(cString: sqlite3_column_text(stmt, 0)))")
 sqlite3_close(db)
 ```
 
-### Loading the Extension
+### Android Package
+
+You can [add this project as a dependency to your Android project](https://central.sonatype.com/artifact/ai.sqlite/js).
+
+**Groovy:**
+```gradle
+repositories {
+    google()
+    mavenCentral()
+    maven { url 'https://jitpack.io' }
+}
+dependencies {
+    // ...
+    // Use requery's SQLite instead of Android's built-in SQLite to support loading custom extensions
+    implementation 'com.github.requery:sqlite-android:3.49.0'
+    // Both packages below are identical - use either one
+    implementation 'ai.sqlite:js:0.9.32' // Maven Central
+    // implementation 'com.github.sqliteai:sqlite-js:0.9.32' // JitPack (alternative)
+}
+```
 
-```sql
--- In SQLite CLI
-.load ./js
+**Kotlin:**
+```kotlin
+repositories {
+    google()
+    mavenCentral()
+    maven(url = "https://jitpack.io")
+}
+
+dependencies {
+    // ...
+
+    // Use requery's SQLite instead of Android's built-in SQLite to support loading custom extensions
+    implementation("com.github.requery:sqlite-android:3.49.0")
+    // Both packages below are identical - use either one
+    implementation("ai.sqlite:js:0.9.32") // Maven Central
+    // implementation("com.github.sqliteai:sqlite-js:0.9.32") // JitPack (alternative)
+}
+```
 
--- In SQL
-SELECT load_extension('./js');
+After adding the package, you'll need to [enable extractNativeLibs](https://github.com/sqliteai/sqlite-extensions-guide/blob/18acfc56d6af8791928f3ac8df7dc0e6a9741dd4/examples/android/src/main/AndroidManifest.xml#L6).
+
+Here's an example of how to use the package:
+```java
+import android.database.Cursor;
+import android.util.Log;
+import io.requery.android.database.sqlite.SQLiteCustomExtension;
+import io.requery.android.database.sqlite.SQLiteDatabase;
+import io.requery.android.database.sqlite.SQLiteDatabaseConfiguration;
+import java.util.Collections;
+
+...
+
+    private void jsExtension() {
+        try {
+            SQLiteCustomExtension jsExtension = new SQLiteCustomExtension(getApplicationInfo().nativeLibraryDir + "/js", null);
+            SQLiteDatabaseConfiguration config = new SQLiteDatabaseConfiguration(
+                getCacheDir().getPath() + "/js_test.db",
+                SQLiteDatabase.CREATE_IF_NECESSARY | SQLiteDatabase.OPEN_READWRITE,
+                Collections.emptyList(),
+                Collections.emptyList(),
+                Collections.singletonList(jsExtension)
+            );
+
+            SQLiteDatabase db = SQLiteDatabase.openDatabase(config, null, null);
+
+            Cursor cursor = db.rawQuery("SELECT js_version()", null);
+            if (cursor.moveToFirst()) {
+                String version = cursor.getString(0);
+                Log.i("sqlite-js", "js_version(): " + version);
+            }
+            cursor.close();
+            db.close();
+
+        } catch (Exception e) {
+            Log.e("sqlite-js", "Error: " + e.getMessage());
+        }
+    }
 ```
 
 ## Functions Overview

jitpack.yml

@@ -0,0 +1,6 @@
+jdk:
+  - openjdk17
+install:
+  - make aar ANDROID_NDK=$ANDROID_HOME/ndk-bundle
+  - export VERSION=$(make version 2>/dev/null | tail -1)
+  - cd packages/android && ./gradlew publishToMavenLocal -PVERSION="$VERSION"