SQLite Android Bindings
Check-in [985ad0e6f2]
Not logged in

Many hyperlinks are disabled.
Use anonymous login to enable hyperlinks.

Overview
Comment:Update the installation instructions to reflect the new support for API level 9. And that building the native libraries is now integrated with gradle.
Downloads: Tarball | ZIP archive | SQL archive
Timelines: family | ancestors | descendants | both | trunk
Files: files | file ages | folders
SHA1: 985ad0e6f280e048aa0bb6103e4690720920efa4
User & Date: dan 2017-04-29 09:24:04
Context
2017-05-01
15:14
Define HAVE_USLEEP to avoid 1 second delays when sleep() is called check-in: efde9e0e44 user: pjw tags: trunk
2017-04-29
09:24
Update the installation instructions to reflect the new support for API level 9. And that building the native libraries is now integrated with gradle. check-in: 985ad0e6f2 user: dan tags: trunk
2017-04-27
18:00
Upgrade this branch to use the enhanced test program from the api-level-9 branch. check-in: 7275688aed user: dan tags: trunk
Changes
Hide Diffs Side-by-Side Diffs Ignore Whitespace Patch

Changes to www/install.wiki.

    14     14   
    15     15     <li> By adding the SQLite Android bindings source code to and building it 
    16     16          along with the other application code.
    17     17   </ol>
    18     18   
    19     19   <p> By default, the SQLite Android bindings support Android API levels 16 
    20     20   and greater (Android versions 4.1 and up). There is also a separate version
    21         -that supports Android API levels 15 and greater (Android version 4.0.2 and 
           21  +that supports Android API levels 9 and greater (Android version 2.3 and 
    22     22   up). Please note the extra step involved in [#obtaincode|obtaining the code] 
    23         -if you wish to use the version compatible with API level 15.
           23  +if you wish to use the version compatible with API level 9.
    24     24   
    25     25   <h2> <a name=prebuilt></a> 1. Using a Pre-Built aar File</h2>
    26     26   
    27     27   <p>
    28     28     This is the most straightforward option. An "aar" file is similar to a 
    29     29     jar file, except that it may contain both compiled java classes and 
    30     30     native code. An aar file for the latest SQLite release usable with
................................................................................
    90     90     <p>
    91     91     Alternatively, the latest code may be downloaded as a 
    92     92     <a href=http://www.sqlite.org/android/zip/SQLite+Android+Bindings.zip?uuid=trunk>zip archive</a>. 
    93     93     In this case, the "project directory" is the
    94     94     <code>SQLite_Android_Bindings/</code> directory created by unzipping the
    95     95     downloaded archive.
    96     96     <p>
    97         -  <i>API level 15 users:</i> The code for the version that is
    98         -  compatible with Android API level 15 may be obtained as a zip
           97  +  <i>API level 9-15 users:</i> The code for the version that is
           98  +  compatible with Android API level 9 and greater may be obtained as a zip
    99     99     file 
   100         -  <a href=http://www.sqlite.org/android/zip/SQLite+Android+Bindings.zip?uuid=api-level-15>from here</a>.
          100  +  <a href=http://www.sqlite.org/android/zip/SQLite+Android+Bindings.zip?uuid=api-level-9>from here</a>.
   101    101     Or, if using fossil, the <code>fossil open</code> command above should be
   102    102     replaced with: 
   103    103     <verbatim>
   104         -    $ fossil open ../android.fossil api-level-15</verbatim>
          104  +    $ fossil open ../android.fossil api-level-9</verbatim>
          105  +
          106  +  <li><a name=buildnative></a> <b>Configure the native libraries.</b>
          107  +  <p> 
          108  +  The latest release of the public domain SQLite library is bundled 
          109  +  with the SQLite Android bindings code downloaded in step 1. If you wish
          110  +  to use a different version of SQLite, for example one that contains the
          111  +  proprietry [./see.wiki | SEE extension], then replace the <code>sqlite3.c</code>
          112  +  and <code>sqlite3.h</code> files at the following locations:
          113  +<verbatim>
          114  +    sqlite3/src/main/jni/sqlite/sqlite3.c
          115  +    sqlite3/src/main/jni/sqlite/sqlite3.h</verbatim>
          116  +  <p> 
          117  +  By default, SQLite is built with the following options:
          118  +<verbatim>
          119  +    -DSQLITE_ENABLE_FTS5
          120  +    -DSQLITE_ENABLE_RTREE
          121  +    -DSQLITE_ENABLE_JSON1
          122  +    -DSQLITE_ENABLE_FTS3</verbatim>
          123  +  To build the SQLite library with some other combination of command line
          124  +  switches, edit the <code>Android.mk</code> file at this location:
          125  +<verbatim>
          126  +    sqlite3/src/main/jni/sqlite/Android.mk</verbatim>
   105    127   
   106         -  <li><a name=buildnative></a> <b>Build the native libraries.</b>
          128  +<li><a name=buildnative2></a> <b>Build the native libraries.</b>
          129  +<p>
          130  +This step is <b>optional. It will be run automatically by the
          131  +</b><code>gradlew</code><b> command in step 4.</b> Running it separately
          132  +is primarily useful for for debugging broken builds.
   107    133     <p> To build the native libraries, navigate to the
   108    134         <code>sqlite3/src/main/</code> directory of the project directory and
   109    135         run the <code>ndk-build</code> command. For example, on Linux if 
   110    136         Android Studio and the NDK are installed using their default paths:
   111    137   <verbatim>
   112    138       $ cd sqlite3/src/main
   113    139       $ ~/Android/Sdk/ndk-bundle/ndk-build</verbatim>
   114         -  <p> On modern hardware, this command takes roughly 2 minutes to build the
          140  +  <p> On modern hardware, this command takes roughly 3 minutes to build the
   115    141         native libraries for all Android architectures.
   116         -  <p> 
   117         -  The latest release of the public domain SQLite library comes bundled 
   118         -  with the SQLite Android bindings code downloaded in step 1. If you wish
   119         -  to use a different version of SQLite, for example one that contains the
   120         -  proprietry [./see.wiki | SEE extension], then replace the <code>sqlite3.c</code>
   121         -  and <code>sqlite3.h</code> files at the following locations before running
   122         -  the <code>ndk-build</code> command:
   123         -
   124         -<verbatim>
   125         -    sqlite3/src/main/jni/sqlite/sqlite3.c
   126         -    sqlite3/src/main/jni/sqlite/sqlite3.h</verbatim>
   127         -  <p> 
   128         -  If you wish to build the SQLite library with non-standard command line
   129         -  switches, for example the -DSQLITE_ENABLE_FTS5 switch used to enable 
   130         -  <a href=http://www.sqlite.org/fts5.html>FTS5</a>, they should be added to
   131         -  the <code>Android.mk</code> file at this location:
   132         -
   133         -<verbatim>
   134         -    sqlite3/src/main/jni/sqlite/Android.mk</verbatim>
   135    142     <p>
   136         -  If the <code>Android.mk</code> or <code>sqlite3.&#91;ch&#93;</code> files
   137         -  are edited after <code>ndk-build</code> is run, it may be necessary to run
   138         -  the <code>ndk-build clean</code> command before rerunning 
   139         -  <code>ndk-build</code> to ensure a correct build.
   140         -  <p>
   141         -  Once <code>ndk-build</code> has been run successfully, unless you modify
   142         -  the <code>Android.mk</code> or <code>sqlite3.&#91;ch&#93;</code> files,
   143         -  it should not be necessary to run it again. It <i>does not</i> have to be 
   144         -  run each time the application is rebuilt.
          143  +  If the <code>Android.mk</code> file is edited after <code>ndk-build</code> is
          144  +  run, it may be necessary to run the <code>ndk-build clean</code> command
          145  +  before rerunning <code>ndk-build</code> to ensure a correct build.
   145    146   
   146    147     <li> <b>Assemble the aar file</b>. To assemble the aar file using the 
   147    148     command line, first set environment variable ANDROID_HOME to the SDK
   148    149     directory, then run the gradle "assembleRelease" target from within the
   149    150     "sqlite3" sub-directory of the project directory. For example:
   150    151   <verbatim>
   151    152       $ export ANDROID_HOME=~/Android/Sdk/
................................................................................
   162    163     <p>
   163    164     Once the custom aar file has been created, it may be used in an Android
   164    165     Studio application as described above. The aar file should be roughly
   165    166     4.5MB in size. If it is much smaller than this (closer to 100KB), this
   166    167     indicates that the aar file is missing the native libraries. The usual
   167    168     cause of this is an unnoticed error while building the native libraries 
   168    169     (step 2 above).
          170  +  <p>
          171  +  If the <code>Android.mk</code> file described in step 2 above is edited 
          172  +  after a build has been run, it may be necessary to run the 
          173  +  gradle "clean" target (either with <code>../gradlew clean</code> or through
          174  +  Android Studio) before rebuilding the aar file to ensure a correct build.
   169    175   </ol>
   170    176   
   171    177   <h2> <a name=directint></a> 3. Adding Source Code Directly to the Application</h2>
   172    178   
   173    179   <p>
   174    180   The SQLite Android bindings code may also be added directly to the 
   175    181   application project, so that it is built and deployed in the same way