<h1>Installation</h1>
<p> There are three ways to add the SQLite Android bindings to an application:
<ol>
<li> By adding a pre-built aar file to the applications
<a href=https://developer.android.com/studio/index.html>Android Studio</a>
project.
<li> By building an aar file, then adding it to the applications Android
Studio project as in (1).
<li> By adding the SQLite Android bindings source code to and building it
along with the other application code.
</ol>
<p> By default, the SQLite Android bindings support Android API levels 16
and greater (Android versions 4.1 and up). There is also a separate version
that supports Android API levels 9 and greater (Android version 2.3 and
up). Please note the extra step involved in [#obtaincode|obtaining the code]
if you wish to use the version compatible with API level 9.
<h2> <a name=prebuilt></a> 1. Using a Pre-Built aar File</h2>
<p>
This is the most straightforward option. An "aar" file is similar to a
jar file, except that it may contain both compiled java classes and
native code. An aar file for the latest SQLite release usable with
API levels 16 and up is available from
<a href=http://sqlite.org/download.html>this page</a>.
<p>
There are two steps involved in adding an aar file to an Android Studio
project:
<p>
<ol>
<li> <b>Import the module</b>. In Android Studio 2.1 this is
accomplished by selecting the <code>"File" -> "New" -> "New
Module..."</code> menu and then choosing <code>"Import JAR/AAR
Package"</code>.
<li> <b>Add a dependency on the new module to the main application</b>
module (or to all modules that will use the SQLite Android bindings). In
Android Studio 2.1 the dependency may be created using the project
structure dialog (select <code>"File" -> "Project Structure..."</code>) or
by adding code similar to the following to the application modules
<code>build.gradle</code> file: <verbatim>
dependencies {
// Change "sqlite-android-3130000" to the name of the new module!
compile project(':sqlite-android-3130000')
}</verbatim>
</ol>
<p> A more detailed description of using the steps above to create a very
simple applictation is [./verysimpleapp.wiki | available here].
<p>
At time of writing, aar files may only be used directly in Android Studio
projects, not projects created using other IDEs (e.g. Eclipse, IntelliJ
IDEA). However, an aar is just a zip archive containing a
<code>classes.jar</code> file that in turn contains the SQLite Android
binding java classes and a <code>jni/</code> directory that contains the
native library for each platform. By extracting these two things from the
aar file and adding them to the project separately it is often possible to
use an aar file in non-Android Studio projects.
<h2>2. <a name=customaar></a> Building a Custom aar File</h2>
<p>
Building a custom aar file requires both the Android SDK and NDK.
<ol>
<li><a name=obtaincode></a><b>Obtain the code</b>. The code for the SQLite Android bindings may
be obtained either by checking out
the <a href=http://fossil-scm.org>fossil</a> repository, or by downloading
a zip file.
<p>
To obtain the code using fossil, use the following series of commands.
In this case, the "project directory" refered to in subsequent steps is
the <code>sqlite</code> directory created by the second command below:
<p>
<verbatim>
$ fossil clone http://www.sqlite.org/android android.fossil
$ mkdir sqlite
$ cd sqlite
$ fossil open ../android.fossil</verbatim>
<p>
Alternatively, the latest code may be downloaded as a
<a href=http://www.sqlite.org/android/zip/SQLite+Android+Bindings.zip?uuid=trunk>zip archive</a>.
In this case, the "project directory" is the
<code>SQLite_Android_Bindings/</code> directory created by unzipping the
downloaded archive.
<p>
<i>API level 9-15 users:</i> The code for the version that is
compatible with Android API level 9 and greater may be obtained as a zip
file
<a href=http://www.sqlite.org/android/zip/SQLite+Android+Bindings.zip?uuid=api-level-9>from here</a>.
Or, if using fossil, the <code>fossil open</code> command above should be
replaced with:
<verbatim>
$ fossil open ../android.fossil api-level-9</verbatim>
<li><a name=buildnative></a> <b>Configure the native libraries.</b>
<p>
The latest release of the public domain SQLite library is bundled
with the SQLite Android bindings code downloaded in step 1. If you wish
to use a different version of SQLite, for example one that contains the
proprietry [./see.wiki | SEE extension], then replace the <code>sqlite3.c</code>
and <code>sqlite3.h</code> files at the following locations:
<verbatim>
sqlite3/src/main/jni/sqlite/sqlite3.c
sqlite3/src/main/jni/sqlite/sqlite3.h</verbatim>
<p>
By default, SQLite is built with the following options:
<verbatim>
-DSQLITE_ENABLE_FTS5
-DSQLITE_ENABLE_RTREE
-DSQLITE_ENABLE_JSON1
-DSQLITE_ENABLE_FTS3</verbatim>
To build the SQLite library with some other combination of command line
switches, edit the <code>Android.mk</code> file at this location:
<verbatim>
sqlite3/src/main/jni/sqlite/Android.mk</verbatim>
<li><a name=buildnative2></a> <b>Build the native libraries.</b>
<p>
This step is <b>optional. It will be run automatically by the
</b><code>gradlew</code><b> command in step 4.</b> Running it separately
is primarily useful for for debugging broken builds.
<p> To build the native libraries, navigate to the
<code>sqlite3/src/main/</code> directory of the project directory and
run the <code>ndk-build</code> command. For example, on Linux if
Android Studio and the NDK are installed using their default paths:
<verbatim>
$ cd sqlite3/src/main
$ ~/Android/Sdk/ndk-bundle/ndk-build</verbatim>
<p> On modern hardware, this command takes roughly 3 minutes to build the
native libraries for all Android architectures.
<p>
If the <code>Android.mk</code> file is edited after <code>ndk-build</code> is
run, it may be necessary to run the <code>ndk-build clean</code> command
before rerunning <code>ndk-build</code> to ensure a correct build.
<li> <b>Assemble the aar file</b>. To assemble the aar file using the
command line, first set environment variable ANDROID_HOME to the SDK
directory, then run the gradle "assembleRelease" target from within the
"sqlite3" sub-directory of the project directory. For example:
<verbatim>
$ export ANDROID_HOME=~/Android/Sdk/
$ cd sqlite3
$ ../gradlew assembleRelease</verbatim>
<p>
Assembling an aar file using Android Studio is similar. Open the SQLite
Android bindings project using Android Studio, run a "gradle sync", then
run the "assembleRelease" gradle task within the "sqlite3" module.
<p>
Using either the command line or Android Studio to run the gradle task
causes the aar file to be created at:
<code>sqlite3/build/outputs/aar/sqlite3-release.aar</code>.
<p>
Once the custom aar file has been created, it may be used in an Android
Studio application as described above. The aar file should be roughly
4.5MB in size. If it is much smaller than this (closer to 100KB), this
indicates that the aar file is missing the native libraries. The usual
cause of this is an unnoticed error while building the native libraries
(step 2 above).
<p>
If the <code>Android.mk</code> file described in step 2 above is edited
after a build has been run, it may be necessary to run the
gradle "clean" target (either with <code>../gradlew clean</code> or through
Android Studio) before rebuilding the aar file to ensure a correct build.
</ol>
<h2> <a name=directint></a> 3. Adding Source Code Directly to the Application</h2>
<p>
The SQLite Android bindings code may also be added directly to the
application project, so that it is built and deployed in the same way
as all other application code.
<p>
To copy the SQLite Android bindings code into an application:
<ol>
<li> Obtain the code in the same way as [#obtaincode | described above].
<li> Recursively copy the contents of the <code>sqlite3/main/src/jni/</code>
directory into the application or application modules <code>jni/</code>
directory. Then, from the parent of the <code>jni/</code> directory, run
the <code>ndk-build</code> command, as [#buildnative | described here].
<li> Recursively copy the contents of the <code>sqlite3/main/src/java/</code>
directory to whereever the application java code is.
</ol>