zeus
137 lines
5.9 KiB
Markdown
137 lines
5.9 KiB
Markdown
Custom SQLite Builds
|
|
====================
|
|
|
|
By default, GRDB uses the version of SQLite that ships with the target operating system.
|
|
|
|
**You can build GRDB with a custom build of [SQLite 3.44.0](https://www.sqlite.org/changes.html).**
|
|
|
|
A custom SQLite build can activate extra SQLite features, and extra GRDB features as well, such as support for the [FTS5 full-text search engine](../../../#full-text-search), and [SQLite Pre-Update Hooks](https://swiftpackageindex.com/groue/grdb.swift/documentation/grdb/transactionobserver).
|
|
|
|
GRDB builds SQLite with [swiftlyfalling/SQLiteLib](https://github.com/swiftlyfalling/SQLiteLib), which uses the same SQLite configuration as the one used by Apple in its operating systems, and lets you add extra compilation options that leverage the features you need.
|
|
|
|
**To install GRDB with a custom SQLite build:**
|
|
|
|
1. Clone the GRDB git repository, checkout the latest tagged version:
|
|
|
|
```sh
|
|
cd [GRDB directory]
|
|
git checkout [latest tag]
|
|
git submodule update --init SQLiteCustom/src
|
|
```
|
|
|
|
2. Choose your [extra compilation options](https://www.sqlite.org/compile.html). For example, `SQLITE_ENABLE_FTS5`, `SQLITE_ENABLE_PREUPDATE_HOOK`.
|
|
|
|
It is recommended that you enable the `SQLITE_ENABLE_SNAPSHOT` option. It allows GRDB to optimize [ValueObservation](https://swiftpackageindex.com/groue/grdb.swift/documentation/grdb/valueobservation) when you use a [Database Pool](https://swiftpackageindex.com/groue/grdb.swift/documentation/grdb/databasepool).
|
|
|
|
3. Create a folder named `GRDBCustomSQLite` somewhere in your project directory.
|
|
|
|
4. Create four files in the `GRDBCustomSQLite` folder:
|
|
|
|
- `SQLiteLib-USER.xcconfig`: this file sets the extra SQLite compilation flags.
|
|
|
|
```xcconfig
|
|
// As many -D options as there are custom SQLite compilation options
|
|
// Note: there is no space between -D and the option name.
|
|
CUSTOM_SQLLIBRARY_CFLAGS = -DSQLITE_ENABLE_SNAPSHOT -DSQLITE_ENABLE_FTS5
|
|
```
|
|
|
|
- `GRDBCustomSQLite-USER.xcconfig`: this file lets GRDB know about extra compilation flags, and enables extra GRDB APIs.
|
|
|
|
```xcconfig
|
|
// As many -D options as there are custom SQLite compilation options
|
|
// Note: there is one space between -D and the option name.
|
|
CUSTOM_OTHER_SWIFT_FLAGS = -D SQLITE_ENABLE_SNAPSHOT -D SQLITE_ENABLE_FTS5
|
|
```
|
|
|
|
- `GRDBCustomSQLite-USER.h`: this file lets your application know about extra compilation flags.
|
|
|
|
```c
|
|
// As many #define as there are custom SQLite compilation options
|
|
#define SQLITE_ENABLE_SNAPSHOT
|
|
#define SQLITE_ENABLE_FTS5
|
|
```
|
|
|
|
- `GRDBCustomSQLite-INSTALL.sh`: this file installs the three other files.
|
|
|
|
```sh
|
|
# License: MIT License
|
|
# https://github.com/swiftlyfalling/SQLiteLib/blob/master/LICENSE
|
|
#
|
|
#######################################################
|
|
# PROJECT PATHS
|
|
# !! MODIFY THESE TO MATCH YOUR PROJECT HIERARCHY !!
|
|
#######################################################
|
|
|
|
# The path to the folder containing GRDBCustom.xcodeproj:
|
|
GRDB_SOURCE_PATH="${PROJECT_DIR}/GRDB"
|
|
|
|
# The path to your custom "SQLiteLib-USER.xcconfig":
|
|
SQLITELIB_XCCONFIG_USER_PATH="${PROJECT_DIR}/GRDBCustomSQLite/SQLiteLib-USER.xcconfig"
|
|
|
|
# The path to your custom "GRDBCustomSQLite-USER.xcconfig":
|
|
CUSTOMSQLITE_XCCONFIG_USER_PATH="${PROJECT_DIR}/GRDBCustomSQLite/GRDBCustomSQLite-USER.xcconfig"
|
|
|
|
# The path to your custom "GRDBCustomSQLite-USER.h":
|
|
CUSTOMSQLITE_H_USER_PATH="${PROJECT_DIR}/GRDBCustomSQLite/GRDBCustomSQLite-USER.h"
|
|
|
|
#######################################################
|
|
#
|
|
#######################################################
|
|
|
|
|
|
if [ ! -d "$GRDB_SOURCE_PATH" ];
|
|
then
|
|
echo "error: Path to GRDB source (GRDB_SOURCE_PATH) missing/incorrect: $GRDB_SOURCE_PATH"
|
|
exit 1
|
|
fi
|
|
|
|
SyncFileChanges () {
|
|
SOURCE=$1
|
|
DESTINATIONPATH=$2
|
|
DESTINATIONFILENAME=$3
|
|
DESTINATION="${DESTINATIONPATH}/${DESTINATIONFILENAME}"
|
|
|
|
if [ ! -f "$SOURCE" ];
|
|
then
|
|
echo "error: Source file missing: $SOURCE"
|
|
exit 1
|
|
fi
|
|
|
|
rsync -a "$SOURCE" "$DESTINATION"
|
|
}
|
|
|
|
SyncFileChanges $SQLITELIB_XCCONFIG_USER_PATH "${GRDB_SOURCE_PATH}/SQLiteCustom/src" "SQLiteLib-USER.xcconfig"
|
|
SyncFileChanges $CUSTOMSQLITE_XCCONFIG_USER_PATH "${GRDB_SOURCE_PATH}/SQLiteCustom" "GRDBCustomSQLite-USER.xcconfig"
|
|
SyncFileChanges $CUSTOMSQLITE_H_USER_PATH "${GRDB_SOURCE_PATH}/SQLiteCustom" "GRDBCustomSQLite-USER.h"
|
|
|
|
echo "Finished syncing"
|
|
```
|
|
|
|
Modify the top of `GRDBCustomSQLite-INSTALL.sh` file so that it contains correct paths.
|
|
|
|
5. Embed the `GRDBCustom.xcodeproj` project in your own project.
|
|
|
|
6. Add the `GRDBCustom` target in the **Target Dependencies** section of the **Build Phases** tab of your **application target**.
|
|
|
|
7. Add the `GRDBCustom.framework` from the targeted platform to the **Embedded Binaries** section of the **General** tab of your **application target**.
|
|
|
|
8. Add a Run Script phase for your target in the **Pre-actions** section of the **Build** tab of your **application scheme**:
|
|
|
|
```sh
|
|
source "${PROJECT_DIR}/GRDBCustomSQLite/GRDBCustomSQLite-INSTALL.sh"
|
|
```
|
|
|
|
The path should be the path to your `GRDBCustomSQLite-INSTALL.sh` file.
|
|
|
|
Select your application target in the "Provide build settings from" menu.
|
|
|
|
9. Check the "Shared" checkbox of your application scheme (this lets you commit the pre-action in your Version Control System).
|
|
|
|
Now you can use GRDB with your custom SQLite build:
|
|
|
|
```swift
|
|
import GRDB
|
|
|
|
let dbQueue = try DatabaseQueue(...)
|
|
```
|