SQLite3 Multiple Ciphers Documentation

To support builds that produce multiple deliverables, this project avoids modifying global flags like CFLAGS, LDFLAGS, or LIBS during feature tests. Instead, feature tests export their results into specific, well-defined variables.

Example Pattern:

• Instead of modifying global LDFLAGS, the zlib test exports LDFLAGS_ZLIB.
• Makefile.in and main.mk then expose this as LDFLAGS.zlib.
• The Makefile is responsible for applying and ordering these specific flags as needed.

This prevents one feature test from implicitly breaking another by polluting the global state.

The build process uses TCL scripts that must remain compatible with both canonical TCL and JimTCL. To ensure your scripts work in JimTCL (the interpreter provided by Autosetup), avoid JimTCL-specific features.

How to force JimTCL usage during configuration

1. System Isolation: Build on a system where no tclsh is installed in the $PATH. The process will fall back to building the in-tree JimTCL.
2. Manual Build: Manually compile the in-tree JimTCL shell before running configure:

cc -o jimsh0 autosetup/jimsh0.c

Note: ./jimsh0 is different from ./jimsh (used for code generation). Use [file-normalize] (the Autosetup implementation) instead of [file normalize] in configure scripts to ensure portability.

This project uses a dual-naming convention for feature flags to bridge the gap between Makefiles and C code:

1. Makefile Variables (X.y): Used within Makefiles for readability (e.g., CFLAGS.readline, LDFLAGS.zlib).
2. C Preprocessor Defines (X_Y): Used when exporting flags to Makefile.in and sqlite_cfg.h (e.g., SQLITE_ENABLE_COLUMN_METADATA).

In Makefile.in, flags are typically translated from the @X_Y@ format into the X.y format used by the rest of the build system.

The Autosetup API documentation is extensive. You can view it directly in the terminal by running the configure script with the --reference flag. This command will include documentation from any TCL files in the ./autosetup directory that use Autosetup's internal markup.

Key configuration files in this project include:

• proj.tcl: Project-agnostic utility code shared across the SQLite/Hwaci umbrella.
• sqlite-config.tcl: Project-specific utility code.
• auto.def: The primary driver for the ./configure process.
• autoconf/auto.def: A trimmed-down version of auto.def used for the 'autoconf' bundle.

#!/bin/bash
./configure --reference | less

To build this package on POSIX-compliant systems, use the provided configure script and make. This method is useful if you want to avoid installing TCL, as the configure script uses an embedded copy of JimTCL.

By default, CFLAGS includes debugging symbols, which results in larger binaries. To produce a smaller installation footprint, override CFLAGS during the configuration step.

Output Artifacts:

• Library name: libsqlite3mc
• SQLite shell executable: sqlite3mc

# Standard build
./configure
make

# Build with optimization for a smaller footprint
CFLAGS="-Os" ./configure
make

# Build with optimization and specific preprocessor defines
CFLAGS="-Os -DSQLITE_OMIT_DEPRECATED" ./configure
make

For detailed information regarding supported cipher schemes and the specific C and SQL interfaces, visit the official documentation website:

https://utelle.github.io/SQLite3MultipleCiphers/

To compile for Windows using Microsoft Visual C++ (version 2005 or later is recommended), use nmake with the provided Makefile.msc.

You can specify preprocessor defines using the OPTS macro on the command line. Note that some defines (like SQLITE_ENABLE_UPDATE_DELETE_LIMIT) require the amalgamation to have been built with them enabled and cannot be added via OPTS at this stage.

# Standard build
nmake /f Makefile.msc

# Build with preprocessor defines
nmake /f Makefile.msc OPTS="-DSQLITE_ENABLE_STAT4=1 -DSQLITE_OMIT_JSON=1"

To avoid merge conflicts in sqlite-config.tcl when managing vendor-specific branches, use a custom file named autosetup/sqlite-custom.tcl in your branch. This file allows you to override flag defaults and handle custom flags.

Implementation Pattern

Create autosetup/sqlite-custom.tcl with the following structure:

# Define custom flag defaults and new flags
proc sqlite-custom-flags {} {
  options-defaults {
    flag-name new-default-value
  }

  return {
    {*} {
      new-flag-name => {Help text}
    }
  };
}

# Define custom flag handling logic
proc sqlite-custom-handle-flags {} {
  # Custom logic goes here
}

sqlite-custom-handle-flags is called late in the configure process, after significant processing but before filtered files are generated.

To update the Autosetup infrastructure, follow these steps:

1. Clone/Update Autosetup:

   git clone https://github.com/msteveb/autosetup
   cd autosetup
   # Or if already checked out:
   git pull

2. Install to Project: From the top-level directory of your SQLite checkout, run:

   /path/to/autosetup-checkout/autosetup --install .

3. Verify and Patch: Run fossil status to see modified files. Crucially, you must apply the project-specific patch for --autosetup-debug (to avoid conflicts with Autosetup's internal --debug flag) before checking in your changes.

# 1. Update autosetup repo
cd /path/to/autosetup
git pull

# 2. Install into the SQLite project
cd /path/to/sqlite-project
/path/to/autosetup/autosetup --install .

To learn how to build and install the extension, refer to the installation guide:

https://utelle.github.io/SQLite3MultipleCiphers/docs/installation/install_overview/

The SQLite3 Multiple Ciphers amalgamation is a single-file source distribution that integrates multiple encryption ciphers into the SQLite source code.

Note: The original, unmodified SQLite sources are not included in this archive. If you require the original SQLite source files, you must download them separately from the official SQLite website using the version information provided in the release notes.