<!-- SPDX-License-Identifier: MIT --> <!-- SPDX-FileCopyrightText: 2026 The LumoSQL Authors --> <!-- SPDX-ArtifactOfProjectName: LumoSQL --> <!-- SPDX-FileType: Documentation --> <!-- SPDX-FileComment: Original by Dan Shearer, June 2026 -->

Fossil backed by LumoSQL

LumoSQL is an SQL database library, intended to be identical in purpose and use to SQLite. Fossil is a demanding SQLite application developed together with SQLite, so Fossil often exercises the latest SQLite features (sometimes even unreleased features.) This makes it ideal for showing that LumoSQL works, and of course is very useful for Fossil users wanting better performance, encryption or online backups. This directory builds and tests Fossil and libfossil against LumoSQL.

In this directory you will find:

• A Makefile so users can build Fossil against LumoSQL (which is just libsqlite3 from the point of view of Fossil) If you do not already have Fossil installed, the Makefile uses git from the GitHub mirror to fetch LumoSQL. The resulting fossil binary will work exactly as a normal fossil binary, only usually faster. The Makefile autodetects the version of SQLite that the current Fossil wants to build against, and builds a corresponding version of LumoSQL.
• Manual Fossil and libfossil build notes for configurations not automatically handled by the Makefile such as encryption, plus generally a lot more detail.
• correctness and speed testing suites for Fossil and libfossil. These are to ensure that LumoSQL isn't either breaking Fossil or making it less useful.
• Brief notes for building LumoSQL/Fossil on NixOS, which is a little fussy

Quick Fossil build from scratch

Install the normal LumoSQL build dependencies from the top-level README. For the Fossil build you also need Git and OpenSSL development headers.

Debian/Ubuntu: sudo apt install git pkg-config libssl-dev tcl-dev .

Fedora/RHEL: sudo dnf install git pkgconf openssl-devel tcl-devel .

If fossil clone below fails with "426 Upgrade Required", use the commented-out git clone alternative instead.

fossil clone https://lumosql.org/src/lumosql
# git clone https://codeberg.org/lumosql/lumosql

after that we build:

cd lumosql
make doctor  # this will pick up any remaining dependency problems; iterate until fixed
cd examples/fossil
make

The Fossil binary is: lumosql/examples/fossil/build/fossil/fossil .

The Makefile follows current Fossil by default, detecting which SQLite version Fossil embeds and building that with LumoSQL.

Following SQLite versions that are ahead of the latest release

Fossil is developed alongside SQLite and often requires SQLite versions that are ahead of the latest release tag. Fossil checks the SQLite version via commit has at startup and stops with Unsuitable SQLite version when its requirement is unmet.

LumoSQL needs to fetch the correct SQLite version, and so follows with the version_from_branch directive in not-fork.d/sqlite3/upstream.conf, which exposes the tip of the SQLite development branch as a version number that can be built:

branch = master
version_from_branch = 3.54.0    # <-- this version number does not yet exist

This needs not-forking 0.7 or later. The same directive appears in not-fork.d/lmdbv1/upstream.conf.

We need to move the number forward as upstream tags releases, because a synthetic version takes priority over a tag of the same name. When the number is behind what Fossil asks for, make stops and prints the lines to add to upstream.conf. Set ALLOW_SQLITE_FALLBACK=1 to build against LumoSQL's newest available SQLite instead, which may give a Fossil binary that stops at startup even if it is a useful build test.

Speed and correctness tests

Run the Fossil-specific correctness test with the built binary:

FOSSIL="$PWD/build/fossil/fossil" \
CLONE_URL=https://lumosql.org/src/lumosql \
sh test/correctness-fossil-lmdb.sh

Run the Fossil-specific speed test, comparing the built binary to the native fossil in PATH:

NATIVE="$(command -v fossil)" \
CANDIDATES="lmdbv1:$PWD/build/fossil/fossil:" \
sh test/speed-fossil.sh