Skip to content

Building from Source

Instructions for building DecentDb from source code.

Prerequisites

Required

  • Nim >= 1.6.0
  • libpg_query (PostgreSQL parser library)
  • git (for cloning)

Optional

  • Python >= 3.8 (for test harness)
  • libpg_query development headers (for building)

Installing Nim

curl https://nim-lang.org/choosenim/init.sh -sSf | sh

Or on Windows: 

. (Invoke-WebRequest -Uri https://nim-lang.org/choosenim/init.ps1 -UseBasicParsing).Content

Using Package Manager

Ubuntu/Debian: 

sudo apt-get install nim

macOS: 

brew install nim

Arch Linux: 

sudo pacman -S nim

Verify Installation

nim --version
# Should show >= 1.6.0

Installing libpg_query

Ubuntu/Debian

sudo apt-get install libpg-query-dev

macOS

brew install libpg_query

From Source

If your distribution doesn't have it:

git clone https://github.com/pganalyze/libpg_query.git
cd libpg_query
make
sudo make install

Verify

ldconfig -p | grep pg_query
# Should show libpg_query.so

Cloning the Repository

git clone https://github.com/sphildreth/decentdb.git
cd decentdb

Building

Standard Build

nimble build

This creates the decentdb executable.

Release Build

Optimized for performance:

nimble build -d:release

Debug Build

With debug symbols and assertions:

nimble build -d:debug

Static Build

Self-contained binary (Linux only):

nimble build --passL:"-static" --passL:"-lpg_query -lstdc++"

Running Tests

All Tests

nimble test

This runs: - All Nim unit tests - Python harness tests

Nim Tests Only

nimble test_nim

Python Tests Only

nimble test_py

Specific Test

nim c -r tests/nim/test_wal.nim

Installation

Local Install

nimble install

Installs to ~/.nimble/bin/

System Install

sudo cp decentdb /usr/local/bin/
sudo chmod +x /usr/local/bin/decentdb

Verify

decentdb --help

Development Build

For active development with fast rebuilds:

# Compile without optimization
nim c -d:development src/decentdb.nim

# Or use the debug task
nimble build -d:debug

Cross-Compilation

Windows from Linux

Requires mingw-w64:

nim c -d:release --os:windows --cpu:amd64 src/decentdb.nim

macOS from Linux

Requires macOS SDK (complex setup).

ARM64 from x64

nim c -d:release --cpu:arm64 src/decentdb.nim

Docker Build

Build Image

docker build -t decentdb:latest .

Run Container

docker run -v $(pwd):/data decentdb:latest \
  exec --db=/data/my.ddb --sql="SELECT 1"

Troubleshooting

"libpg_query not found"

Problem: 

Error: cannot find -lpg_query

Solution: 

# Find the library
find /usr -name "libpg_query*" 2>/dev/null

# Add to library path
export LIBRARY_PATH=/usr/local/lib:$LIBRARY_PATH
export LD_LIBRARY_PATH=/usr/local/lib:$LD_LIBRARY_PATH

# Rebuild
nimble build

"nim not found"

Problem: 

bash: nim: command not found

Solution: 

# Add nimble bin to PATH
export PATH=$HOME/.nimble/bin:$PATH

# Or reinstall choosenim
curl https://nim-lang.org/choosenim/init.sh -sSf | sh

Tests Fail

Problem: Some tests fail after build.

Solution: 

# Run specific test for details
nim c -r tests/nim/test_wal.nim

# Check Python tests separately
python -m pytest tests/harness/test_runner.py -v

Slow Build

Problem: Build takes too long.

Solution: 

# Use release flags (faster compilation)
nimble build -d:release

# Or parallel compilation
nim c --parallelBuild:4 src/decentdb.nim

IDE Setup

VS Code

Install extensions: - Nim (by kosz78) - Syntax highlighting, compilation - nim-lsp - Language server support

Configuration: 

{
  "nim.buildCommand": "nimble build",
  "nim.runOutput": "./decentdb"
}

Vim/Neovim

Using nimlsp: 

" With coc.nvim
:CocInstall coc-nim

" With native LSP
lua require'lspconfig'.nimls.setup{}

Emacs

Using nim-mode: 

(use-package nim-mode
  :hook (nim-mode . lsp))

Continuous Integration

The project uses GitHub Actions:

  • Build: Compiles on Linux, macOS, Windows
  • Test: Runs all tests
  • Lint: Static analysis
  • Docs: Builds documentation

See .github/workflows/ for details.

Release Checklist

Before creating a release:

  1. [ ] All tests pass
  2. [ ] Version updated in decentdb.nimble
  3. [ ] CHANGELOG.md updated
  4. [ ] Documentation built
  5. [ ] Binaries built for all platforms
  6. [ ] Version bumped (e.g. 0.0.1 -> 0.0.2) and changelog updated
  7. [ ] Git tag created: git tag -a v0.0.1 -m "Release 0.0.1"
  8. [ ] Tag pushed: git push origin v0.0.1

Next Steps