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: 120
     strategy:
       fail-fast: false
@@ -69,7 +69,7 @@ jobs:
           - os: ubuntu-22.04
             arch: arm64-v8a
             name: android
-            make: PLATFORM=android ARCH=arm64-v8a LLAMA="-DGGML_CPU_ARM_ARCH=armv8.2-a+dotprod"
+            make: PLATFORM=android ARCH=arm64-v8a
           - os: macos-15
             name: ios
             make: PLATFORM=ios LLAMA="-DGGML_NATIVE=OFF -DGGML_METAL=ON -DGGML_ACCELERATE=ON -DGGML_BLAS=ON -DGGML_BLAS_VENDOR=Apple" WHISPER="-DWHISPER_COREML=ON -DWHISPER_COREML_ALLOW_FALLBACK=ON"
@@ -79,6 +79,9 @@ jobs:
           - os: macos-15
             name: apple-xcframework
             make: xcframework LLAMA="-DGGML_NATIVE=OFF -DGGML_METAL=ON -DGGML_ACCELERATE=ON -DGGML_BLAS=ON -DGGML_BLAS_VENDOR=Apple" WHISPER="-DWHISPER_COREML=ON -DWHISPER_COREML_ALLOW_FALLBACK=ON"
+          - os: ubuntu-22.04
+            name: android-aar
+            make: aar
 
     defaults:
       run:
@@ -94,6 +97,13 @@ jobs:
         with:
           submodules: true
 
+      - name: android setup java
+        if: matrix.name == 'android-aar'
+        uses: actions/setup-java@v4
+        with:
+          distribution: 'temurin'
+          java-version: '17'
+
       - name: calculate cache version hashes for modules and dependencies
         id: submodule-hashes
         env:
@@ -377,12 +387,64 @@ 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" != "ai-apple-xcframework" && "$name" != "ai-android-aar" ]]; then
+                tar -czf "${name}-${VERSION}.tar.gz" -C "$folder" .
+              fi
+              if [[ "$name" != "ai-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 sqlite-ai.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 ai-*-${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
@@ -393,24 +455,20 @@ jobs:
           echo "❌ SQLITE_AI_VERSION not found in sqlite-ai.h"
           exit 1
           
-      - name: zip artifacts
-        run: |
-          for folder in "artifacts"/*; do
-            if [ -d "$folder" ]; then
-              name=$(basename "$folder")
-              if [[ "$name" != "ai-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: |
-            ai-*-${{ steps.tag.outputs.version }}.zip
-            ai-*-${{ steps.tag.outputs.version }}.tar.gz
+          files: ai-*-${{ steps.tag.outputs.version }}.*
           make_latest: true

.gitignore

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

Makefile

@@ -94,9 +94,12 @@ else ifeq ($(PLATFORM),android)
 	CXX = $(CC)++
 	TARGET := $(DIST_DIR)/ai.so
 	LDFLAGS += -static-libstdc++ -shared
-	ANDROID_OPTIONS = -DCMAKE_TOOLCHAIN_FILE=$(ANDROID_NDK)/build/cmake/android.toolchain.cmake -DANDROID_ABI=$(if $(filter aarch64,$(ARCH)),arm64-v8a,$(ARCH)) -DANDROID_PLATFORM=android-26 -DCMAKE_C_FLAGS="-march=$(if $(filter aarch64,$(ARCH)),armv8.7a,x86-64)" -DCMAKE_CXX_FLAGS="-march=$(if $(filter aarch64,$(ARCH)),armv8.7a,x86-64)" -DCMAKE_POSITION_INDEPENDENT_CODE=ON
-	LLAMA_OPTIONS += $(ANDROID_OPTIONS) -DGGML_OPENMP=OFF -DGGML_LLAMAFILE=OFF
-	WHISPER_OPTIONS += $(ANDROID_OPTIONS) -DGGML_OPENMP=OFF -DGGML_LLAMAFILE=OFF
+	ANDROID_OPTIONS = -DCMAKE_TOOLCHAIN_FILE=$(ANDROID_NDK)/build/cmake/android.toolchain.cmake -DANDROID_ABI=$(if $(filter aarch64,$(ARCH)),arm64-v8a,$(ARCH)) -DANDROID_PLATFORM=android-26 -DCMAKE_C_FLAGS="-march=$(if $(filter aarch64,$(ARCH)),armv8.7a,x86-64)" -DCMAKE_CXX_FLAGS="-march=$(if $(filter aarch64,$(ARCH)),armv8.7a,x86-64)" -DCMAKE_POSITION_INDEPENDENT_CODE=ON -DGGML_OPENMP=OFF -DGGML_LLAMAFILE=OFF
+	ifneq (,$(filter $(ARCH),aarch64))
+		ANDROID_OPTIONS += -DGGML_CPU_ARM_ARCH=armv8.2-a+dotprod
+	endif
+	LLAMA_OPTIONS += $(ANDROID_OPTIONS)
+	WHISPER_OPTIONS += $(ANDROID_OPTIONS)
 	MINIAUDIO_OPTIONS += $(ANDROID_OPTIONS)
 	STRIP = $(BIN)/llvm-strip --strip-unneeded $@
 else ifeq ($(PLATFORM),ios)
@@ -303,6 +306,17 @@ $(DIST_DIR)/%.xcframework: $(LIB_NAMES)
 
 xcframework: $(DIST_DIR)/ai.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)/ai.so $(AAR_ARM)
+	$(MAKE) clean && $(MAKE) PLATFORM=android ARCH=x86_64
+	mv $(DIST_DIR)/ai.so $(AAR_X86)
+	cd packages/android && ./gradlew clean assembleRelease
+	cp packages/android/build/outputs/aar/android-release.aar $(DIST_DIR)/ai.aar
+
 # Help message
 help:
 	@echo "SQLite AI Extension Makefile"
@@ -323,5 +337,6 @@ help:
 	@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 clean test extension help version xcframework
+.PHONY: all clean test extension 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 ./ai
+
+-- In SQL
+SELECT load_extension('./ai');
+```
+
 ### 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,6 +63,86 @@ log("ai_version(): \(String(cString: sqlite3_column_text(stmt, 0)))")
 sqlite3_close(db)
 ```
 
+### Android Package
+
+You can [add this project as a dependency to your Android project](https://central.sonatype.com/artifact/ai.sqlite/ai).
+
+**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:ai:0.7.55' // Maven Central
+    // implementation 'com.github.sqliteai:sqlite-ai:0.7.55' // JitPack (alternative)
+}
+```
+
+**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:ai:0.7.55") // Maven Central
+    // implementation("com.github.sqliteai:sqlite-ai:0.7.55") // JitPack (alternative)
+}
+```
+
+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 aiExtension() {
+        try {
+            SQLiteCustomExtension aiExtension = new SQLiteCustomExtension(getApplicationInfo().nativeLibraryDir + "/ai", null);
+            SQLiteDatabaseConfiguration config = new SQLiteDatabaseConfiguration(
+                getCacheDir().getPath() + "/ai_test.db",
+                SQLiteDatabase.CREATE_IF_NECESSARY | SQLiteDatabase.OPEN_READWRITE,
+                Collections.emptyList(),
+                Collections.emptyList(),
+                Collections.singletonList(aiExtension)
+            );
+
+            SQLiteDatabase db = SQLiteDatabase.openDatabase(config, null, null);
+
+            Cursor cursor = db.rawQuery("SELECT ai_version()", null);
+            if (cursor.moveToFirst()) {
+                String version = cursor.getString(0);
+                Log.i("sqlite-ai", "ai_version(): " + version);
+            }
+            cursor.close();
+            db.close();
+
+        } catch (Exception e) {
+            Log.e("sqlite-ai", "Error: " + e.getMessage());
+        }
+    }
+```
+
 ### Python Package
 
 Python developers can quickly get started using the ready-to-use `sqlite-ai` package available on PyPI:
@@ -63,16 +153,6 @@ pip install sqlite-ai
 
 For usage details and examples, see the [Python package documentation](./packages/python/README.md).
 
-### Loading the Extension
-
-```sql
--- In SQLite CLI
-.load ./ai
-
--- In SQL
-SELECT load_extension('./ai');
-```
-
 ## Getting Started
 
 Here's a quick example to get started with SQLite Sync:

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"