Build from source

For working on fenecdb, or for a build the releases do not have. To use it, install a release instead: Install has the image, the binaries and the packages.

Clone and build

You need Rust from rustup and make; the repository's rust-toolchain.toml picks the stable channel and asks for the wasm32 target. Node runs the JS tests and Python 3 serves the console and builds this site.

  1. Clone the repository.

    git clone https://github.com/fenecdb/fenecdb
cd fenecdb

  2. Build the shell and the server.

    cargo build --release -p fenec-cli -p fenec-server
    produces
    target/release/fenec          the shell
target/release/fenec-server   the server

  3. Build the browser module.

    make wasm
    produces
    web/fenec.wasm    the engine, every feature
web/collate/      the collation data it fetches beside it

  4. Run the tests.

    make test

The wasm32 target comes from rustup. Homebrew's cargo ships no wasm32 standard library. The Makefile prefers ~/.cargo/bin/cargo; building by hand needs rustup target add wasm32-unknown-unknown first.

Which profile builds which binary

The binaries come from cargo build, not from make test: that builds with the debug profile, leaves target/debug/fenec-server for the JS tests, and makes nothing under target/release. The release workflow builds fenec in the cli profile (cargo build --profile cli -p fenec-cli, target/cli/fenec), the smaller one that aborts on a panic rather than unwind: a single process has nothing to recover from. fenec-server stays on release, where a panicking connection thread drops only its own request.

What make test runs

The Rust suites first, then the JS ones, on purpose: cargo test builds the fenec-server binary, and the JS sync tests run against it.

  • every crate's tests and doc tests, but fenec-bench's, whose SQLite and PostgreSQL clients are the heaviest thing a build compiles;
  • fenec-core again without its indexes, and without any feature, which is how the small browser modules are made;
  • the JS suites with node --test: the query builder and the module, the sync layer against a real server, persistence, files, schema in code, the client and the replica reads, and the studio's statements;
  • the sync scenarios, held to both the native core and the browser's.

The JS suites that need web/fenec.wasm or the server binary skip themselves when it is missing, so run make wasm first to have the end-to-end cases actually run. A narrower run, by crate, file or name:

cargo test -p fenec-core --test all persist::   # one file of a crate's integration tests
cargo test -p fenec-ql near                      # by name substring
node --test web/fenec.test.js                    # one JS suite

Make targets worth knowing

The Makefile wraps the commands you will run most. make with no target runs the tests and builds the module; the comments in the Makefile say what the rest do.

CommandWhat it does
make testRust suite, then the JS suite
make wasmBuild for wasm32 and copy to web/fenec.wasm
make wasm FEATURES="text sorted"The same with those features alone (A smaller module)
make serveBuild the wasm and serve the browser console on http://localhost:8787 (PORT=3000 for another)
make server TOKEN=secretRun the server over ./data.fenec on 127.0.0.1:8080
make siteBuild this site into site/dist (make site-serve to read it on http://localhost:8788)
make benchScale measurement
make memoryMemory footprint, for calibrating --max-memory
make sweepThe ef/recall trade-off
make compareAgainst SQLite and pgvector (run make pgvector-up first)
make smallThe 1880 KB binary: --profile cli --no-default-features

make serve serves web/index.html, a full console: a FenecQL editor, a sample data generator, live statistics and IndexedDB persistence.

Contributing

CONTRIBUTING.md is the short version of what a change has to respect: no dependencies in the engine, the crates' dependency direction, limits that error rather than truncate, an append-only file format. The reasoning behind each is in these docs, starting with How it works and File format.