Installation

Table of contents

• Overview
• Windows
• Linux / OSX
• WebAssembly
• Support for ICU (International Components for Unicode)
• Default settings
• Optional features
• TCL Interface

Overview

Build files for the supported platforms - Windows, Linux, and OSX - are provided.

The build files for Windows platforms are generated with Premake 5. For regenerating the build files it is recommended to use Premake 5.0 alpha 15 or later.

For Linux and OSX build files based on the autoconf/automake toolchain are provided.

Note

An archive with the amalgamated source code, pre-built binaries for Windows and Android (see SQLite Android Bindings) are usually provided with every release.

Windows

Ready to use project files are provided for Visual C++ 2010, 2012, 2013, 2015, 2017, and 2019. Additionally, GNU Makefiles are provided supporting GCC (for example, Mingw-w64 or recent versions of tdm-gcc).

For Visual Studio 2010+ solutions it is possible to customize the build by creating a wx_local.props file in the build directory which is used by the projects, if it exists. The settings in that file override the default values for the properties. The typical way to make the file is to copy wx_setup.props to wx_local.props and then edit locally.

For GNU Makefiles the file config.gcc serves the same purpose as the file wx_setup.props for Visual C++ projects.

The customization files wx_setup.props resp. config.gcc allow to customize certain settings like for example the default cipher scheme.

For adjusting the build configuration edit file premake5.lua in the root directory, and then run

premake5 [action]

where action is one of the following: vs2010, vs2012, vs2013, vs2015, vs2017, vs2019, or gmake2.

When building on Win32 or Win64, you can use the makefiles or one of the Microsoft Visual Studio solution files in the build folder.

For Visual C++ the debugging properties are set up in such a way that debugging the sample applications should work right out of the box.

Linux / OSX

When building on Linux or OSX, the first setup is to recreate the configure script doing:

  autoreconf

Thereafter you should create a build directory

  mkdir build-gtk [or any other suitable name]
  cd build-gtk
  ../configure
  make

Type ../configure --help for more info.

The autoconf-based system also supports a make install target which builds the library and then copies the headers of the component to /usr/local/include and the lib to /usr/local/lib.

WebAssembly

Starting with version 3.40 the SQLite project provides WebAssembly- and JavaScript-related APIs, which enable the use of SQLite3 in modern WASM-capable browsers.

SQLite3 Multiple Ciphers can add encryption support to WASM-based applications. In principle, building JS/WASM support for SQLite3 Multiple Ciphers follows closely the documentation given on the SQLite website.

The build process is very similar to the description of Building for SQLite Encryption Extension (SEE), the official (commercial) SQLite Encryption Extension.

The following steps describe the preliminary actions:

1. Generate or download the amalgamation source code of SQLite3 Multiple Ciphers, matching the SQLite version, you want to build WASM support for,
2. Copy the file sqlite3mc_amalgamation.c to the top-most directory of the SQLite source tree,
3. Rename sqlite3mc_amalgamation.c to sqlite3-see.c, or pass sqlite3.c=/path/to/sqlite3mc_amalgamation.c when running make or gmake from the ext/wasm directory,
4. Adjust the file ext/wasm/GNUmakefile by adding the compile time flag -D__WASM__ (2 places),
5. (Optional) Add support for the SQLite3 Multiple Ciphers C API:
   • Add the SQLite3 Multiple Ciphers API function names to file ext/wasm/api/EXPORTED_FUNCTIONS.sqlite3-see, prefixing them with an underscore character,
   • Add the signatures of the SQLite3 Multiple Ciphers API functions to ext/wasm/api/sqlite3-api-glue.js (search for sqlite3_activate_see).

Thereafter WASM support can be built according to the SQLite documentation.

Support for ICU (International Components for Unicode)

On Windows the SQLite3 Multiple Ciphers library can be built with or without ICU support. ICU support for SQLite3 is currently based on pre-built ICU Libraries, which were compiled with Visual Studio 2019. The required ICU DLLs are not included in the repository, but can be downloaded from the latest ICU release. However, the pre-built binary packages for Windows include the required ICU DLLs.

Using the build files coming with SQLite3 Multiple Ciphers for building the library with ICU support, requires to define the environment variable LIBICU_PATH that must point to the directory to which the archive with the pre-built ICU libraries was extracted.

In addition, the Visual C++ 2019 runtime is required to be installed, because the ICU DLLs depend on it.

In principle, the ICU DLLs should be compatible with Visual C++ 2015 and Visual C++ 2017 as well.

Default settings

Currently the cipher scheme sqleet: ChaCha20 is set as the default. However, this can be changed by setting the preprocessor symbol CODEC_TYPE to one of the values listed in the following table:

Notes

• If compatibility with legacy sqleet is required, it is necessary to explicitly define the preprocessor symbol SQLITE3MC_USE_SQLEET_LEGACY.
• If compatibility with legacy SQLCipher is required, it is necessary to explicitly define the preprocessor symbol SQLITE3MC_USE_SQLCIPHER_LEGACY. If not the latest SQLCipher version, but a specific older one, should be selected, then the preprocessor symbol SQLCIPHER_VERSION_DEFAULT=version needs to be defined, where version can have one of the values 1, 2, 3, or 4.

Optional features

SQLite has many optional features and offers a vast number of optional extensions. The below table lists the features that are enabled for SQLite3 Multiple Ciphers as default. For details, please see SQLite Compile Time Options.

Note

• In case of memory constraints it is of course possible to disable unneeded features. However, this will require to modify the build files.

The source code of 3 extensions that require ZLIB support is also included, but is not enabled by default:

• COMPRESS
• SQLAR
• ZIPFILE

To enable one or more of those extensions, it is required to specify the corresponding preprocessor symbol:

To successfully compile these extensions it is required to specify for the compiler, where the ZLIB header can be found, and for the linker, the name and location of the ZLIB library. Alternatively, it is possible to use the included MINIZ library, a subset of ZLIB, by specifying the preprocessor symbol SQLITE3MC_USE_MINIZ=1. This allows to remove the external dependency on the ZLIB library.

TCL Interface

SQLite offers an implementation of a TCL interface and a TCL command shell. The source code of this interface is included with SQLite3 Multiple Ciphers.

Please consult the original SQLite documentation Compiling the TCL interface for further information, how to build the TCL interface and TCL command shell, since SQLite3 Multiple Ciphers does not contain build support for this feature.