Files in directory examples/fossil from the latest check-in

patches
test
tools
FOSSIL-ON-LUMOSQL.md
importing-massive-trees-to-fossil-lumosql.md
Makefile
README.md

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.

Here 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 works as a normal fossil binary. 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 libfossil, which the Makefile does not yet build
correctness and speed testing suites for Fossil and libfossil.
tools/, the shell helpers for the Makefile calls. As a special case tools/nixos-fossil.sh builds Fossil on NixOS, which is quite fussy (see doc/lumo-build-nixos.md).

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 .

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

fossil clone https://lumosql.org/src/lumosql
# if your fossil fails with "426 Upgrade Required" it's out of date, use git instead
# 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.

An encrypted Fossil

make fossil LUMO_ENCRYPT=on          # needs libsodium
export LUMO_KEY="correct-horse-battery-staple"
./build/fossil/fossil init /tmp/sec.fossil

The build adds OPTION_LMDBV1_ENCRYPT=on to the LumoSQL target, and the backend reads LUMO_KEY from the environment, so ordinary fossil commands work unchanged on an encrypted repository. The first open writes a <repo>-salt sibling; a wrong or absent passphrase fails the open with authorization denied. The checkout database .fslckout is encrypted too; a patch opens the global configuration database with an empty lumo_key, which keeps it plaintext.

Other things the Makefile does

LUMOSQL_TARGET - build against one named target, in place of autodetecting from the Fossil checkout
LUMO_ENCRYPT=on - the encrypted build above
FOSSIL_FETCH - git clones the mirror, fossil clones fossil-scm.org
FOSSIL_BRANCH -- which branch to check out
LUMO_IGNORE_FLOOR=1 - build even when the chosen SQLite is below the minimum Fossil enforces at startup
ALLOW_SQLITE_FALLBACK=1 - build against LumoSQL's newest available SQLite, as below

Following an SQLite version 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.8 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

The speed tests convert the stock Fossil repositories to WAL mode before timing. Fossil's SQLite build defaults WAL databases to synchronous NORMAL, matching this example binary's fixed LMDB normal durability level. See test/README.md for the workloads and the exclusions needed for fresh repository creation.

Lumosql