by Marty Schoch ([email protected]) + Traun Leyden ([email protected])
Couchbase-Lite-Android is the Android port of Couchbase Lite iOS.
For information on the high-level goals of the project see the Couchbase Lite iOS Readme.
If you just want to use Couchbase-Lite-Android in your app, you may not need to even clone or build the code as described in this document. See Getting Started or jump straight to the Grocery-Sync demo application.
Otherwise, if you need to hack on Couchbase-Lite-Android, or just want to read through the code, then this document is for you. Read on!
-
Under Tools / Android / Android SDK Manager and install "Extras/Google Repository" and "Extras/Android Support Repository" (future versions of Android Studio may make this step unnecessary)
Use Git to clone the Couchbase Lite repository to your local disk:
$ git clone git://github.com/couchbase/couchbase-lite-android.git
You should be able to open the project directly in Android Studio:
cp local.properties.example local.properties
- Customize
local.properties
according to your SDK installation directory - Start Android Studio
- Choose File / Open and choose the CouchbaseLiteProject directory
After opening the project, it should look like this
The tests require Sync Gateway to be installed and running.
- Sync-Gateway
First copy the test.properties -> local-test.properties, eg:
By default, the tests will try to connect to a CouchDB or Sync-Gateway running on your local workstation, and will not pass any username or password as credentials.
Note: this step below of copying local-test.properties will need to be repeated for the all of the library projects that contain tests (eg, CBLite, CBLiteEktorp, CBLiteJavascript)
$ cd CBLite/src/instrumentTest/assets/
$ cp test.properties local-test.properties
Now customize local-test.properties to point to your database (URL and db name)
Note: If you are running the tests on the android emulator, then you can use the special 10.0.2.2
address, which will have it use the IP address of the workstation which launched the emulator. (assuming that's where your server is)
$ ./gradlew clean && ./gradlew connectedInstrumentTest
Warning: the full test suite takes a long time (10mins?) because of some 1 minute waits in the Ektorp tests. You can tell it to just run the core tests (which are much faster) by running ./gradlew :CBLite:clean && ./gradlew :CBLite:connectedInstrumentTest
instead.
Note: there's not yet a known way to run the tests via Android Studio. At the time of writing, was not yet supported by Android Studio.
Warning: this is a complicated process due to the issues mentioned on this thread
Preparation:
- You will need to have a maven repository installed and running
- Delete all three archives from your repo: CBLite, CBLiteEktorp, and CBLiteJavascript
- rm -rf ~/.gradle to delete any gradle cache files
Building and deploying:
- In the build.gradle file for CBLite, CBLiteEktorp, and CBLiteJavascript, set apply from: 'dependencies-test.gradle'
- Run
./gradlew clean && ./gradlew :CBLite:uploadArchives
- Modify CBLiteEktorp/build.gradle to set apply from: 'dependencies-archive.gradle'
- Run
./gradlew clean && ./gradlew :CBLiteEktorp:uploadArchives
- Modify CBLiteJavacript/build.gradle to set apply from: 'dependencies-archive.gradle'
- Run
./gradlew clean && ./gradlew :CBLiteJavascript:uploadArchives
The end result: you will have three .aar archives in your maven repository.
See the wiki
- Ported core functionality present in Couchbase-Lite-iOS as of approximately 1 year ago (May 2012).
- Unit tests pass
- Android 3.0 Honeycomb (API level 11)
Note: this was recently bumped up from Android 2.2, due to Ektorp issue #88
- Apache License 2.0
- Cannot deal with large attachments without running out of memory.
- If the device goes offline, replications will stop and will not be automatically restarted.
- Exception Handling in the current implementation makes things less readable. This was a deliberate decision that was made to make it more of a literal port of the iOS version. Once the majority of code is in place and working I would like to revisit this and handle exceptions in more natural Android/Java way.
- Finish porting all of TDRouter so that all operations are supported