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

Author: Gioee

.github/workflows/main.yml

@@ -12,7 +12,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
@@ -55,6 +55,9 @@ jobs:
           - os: macos-15
             name: apple-xcframework
             make: xcframework
+          - os: ubuntu-22.04
+            name: android-aar
+            make: aar
 
     defaults:
       run:
@@ -69,6 +72,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'
+
       - uses: msys2/[email protected]
         if: matrix.name == 'windows'
         with:
@@ -224,12 +234,67 @@ jobs:
       - name: deploy coverage to GitHub Pages
         uses: actions/[email protected]
 
+      - name: zip artifacts
+        run: |
+          VERSION=$(make version)
+          for folder in "artifacts"/*; do
+            if [ -d "$folder" ]; then
+              name=$(basename "$folder")
+              if [[ "$name" != "github-pages" ]]; then
+                if [[ "$name" != "cloudsync-apple-xcframework" && "$name" != "cloudsync-android-aar" ]]; then
+                  tar -czf "${name}-${VERSION}.tar.gz" -C "$folder" .
+                fi
+                if [[ "$name" != "cloudsync-android-aar" ]]; then
+                  (cd "$folder" && zip -rq "../../${name}-${VERSION}.zip" .)
+                else
+                  cp "$folder"/*.aar "${name}-${VERSION}.aar"
+                fi
+              fi
+            fi
+          done
+
       - name: release tag version from cloudsync.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 cloudsync-*-${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
@@ -261,29 +326,22 @@ jobs:
           git commit -m "Bump sqlite-sync version to ${{ steps.tag.outputs.version }}"
           git push origin main
           
-      - name: zip artifacts
+      - uses: actions/setup-java@v4
         if: steps.tag.outputs.version != ''
-        run: |
-          for folder in "artifacts"/*; do
-            if [ -d "$folder" ]; then
-              name=$(basename "$folder")
-              if [[ "$name" != "github-pages" ]]; then
-                if [[ "$name" != "cloudsync-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
-            fi
-          done
+        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: |
-            cloudsync-*-${{ steps.tag.outputs.version }}.zip
-            cloudsync-*-${{ steps.tag.outputs.version }}.tar.gz
-            CloudSync-*-${{ steps.tag.outputs.version }}.zip
-            CloudSync-*-${{ steps.tag.outputs.version }}.tar.gz
+            cloudsync-*-${{ steps.tag.outputs.version }}.*
+            CloudSync-*-${{ steps.tag.outputs.version }}.*
           make_latest: true

.gitignore

@@ -1,17 +1,38 @@
-.DS_Store
-*.xcworkspacedata
-*.xcuserstate
-*.xcbkptlist
-*.plist
-/build
+# Build artifacts
+build/
+/dist
+.build
+*.a
+*.sqlite
+/curl/src
 **/dist/**
+
+# Test artifacts
 /coverage
-*.sqlite
-*.a
 unittest
-/curl/src
-.vscode
 **/node_modules/**
 .env
 package-lock.json
-.build
+
+# iOS/macOS
+*.xcworkspacedata
+*.xcuserstate
+*.xcbkptlist
+*.plist
+
+# Android
+.gradle/
+*.aar
+local.properties
+jniLibs/
+*.apk
+*.ap_
+*.dex
+
+# IDE
+.vscode
+.idea/
+*.iml
+
+# System
+.DS_Store

Makefile

@@ -346,6 +346,17 @@ $(DIST_DIR)/%.xcframework: $(LIB_NAMES)
 
 xcframework: $(DIST_DIR)/CloudSync.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)/cloudsync.so $(AAR_ARM)
+	$(MAKE) clean && $(MAKE) PLATFORM=android ARCH=x86_64
+	mv $(DIST_DIR)/cloudsync.so $(AAR_X86)
+	cd packages/android && ./gradlew clean assembleRelease
+	cp packages/android/build/outputs/aar/android-release.aar $(DIST_DIR)/cloudsync.aar
+
 # Tools
 version:
 	@echo $(shell sed -n 's/^#define CLOUDSYNC_VERSION[[:space:]]*"\([^"]*\)".*/\1/p' src/cloudsync.h)
@@ -373,5 +384,7 @@ help:
 	@echo "  clean	 				- Remove built files"
 	@echo "  test [COVERAGE=true]	- Test the extension with optional coverage output"
 	@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

@@ -116,6 +116,16 @@ Download the appropriate pre-built binary for your platform from the official [R
 - Android
 - iOS
 
+### Loading the Extension
+
+```sql
+-- In SQLite CLI
+.load ./cloudsync
+
+-- In SQL
+SELECT load_extension('./cloudsync');
+```
+
 ### WASM Version
 
 You can download the WebAssembly (WASM) version of SQLite with the SQLite Sync extension enabled from: https://www.npmjs.com/package/@sqliteai/sqlite-wasm
@@ -143,14 +153,84 @@ log("cloudsync_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/sync).
+
+**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:sync:0.8.39' // Maven Central
+    // implementation 'com.github.sqliteai:sqlite-sync:0.8.39' // JitPack (alternative)
+}
+```
 
-```sql
--- In SQLite CLI
-.load ./cloudsync
+**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:sync:0.8.39") // Maven Central
+    // implementation("com.github.sqliteai:sqlite-sync:0.8.39") // JitPack (alternative)
+}
+```
 
--- In SQL
-SELECT load_extension('./cloudsync');
+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 cloudsyncExtension() {
+        try {
+            SQLiteCustomExtension cloudsyncExtension = new SQLiteCustomExtension(getApplicationInfo().nativeLibraryDir + "/cloudsync", null);
+            SQLiteDatabaseConfiguration config = new SQLiteDatabaseConfiguration(
+                getCacheDir().getPath() + "/cloudsync_test.db",
+                SQLiteDatabase.CREATE_IF_NECESSARY | SQLiteDatabase.OPEN_READWRITE,
+                Collections.emptyList(),
+                Collections.emptyList(),
+                Collections.singletonList(cloudsyncExtension)
+            );
+
+            SQLiteDatabase db = SQLiteDatabase.openDatabase(config, null, null);
+
+            Cursor cursor = db.rawQuery("SELECT cloudsync_version()", null);
+            if (cursor.moveToFirst()) {
+                String version = cursor.getString(0);
+                Log.i("sqlite-sync", "cloudsync_version(): " + version);
+            }
+            cursor.close();
+            db.close();
+
+        } catch (Exception e) {
+            Log.e("sqlite-sync", "Error: " + e.getMessage());
+        }
+    }
 ```
 
 ## Getting Started

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"