Skip to main content

Getting Started

Supported Environment​

The best platforms to build FluffOS are Ubuntu 22.04+ (including WSL), the latest macOS (both Intel and Apple Silicon), and Windows on MSYS2/MINGW64. A WebAssembly cross-build is also supported — see Build for WebAssembly.

Compilers: FluffOS uses C++17 and C11, which requires at least GCC 7+ or LLVM clang 4+.

Tested configurations (validated by CI, see .github/workflows/ci.yml):

PlatformToolchainBuild types
Ubuntu 24.04GCC and Clang (plus Clang + sanitizers)Debug / RelWithDebInfo
macOS 14 (Apple Silicon)ClangDebug / RelWithDebInfo
Windows (MSYS2/MINGW64)GCCDebug / RelWithDebInfo
Alpine LinuxGCC, static linkingDocker image builds

System library requirements (must install):

  1. ICU: FluffOS uses ICU for UTF-8 and transcoding support.
  2. jemalloc: Release builds use jemalloc by default; highly recommended in production.
  3. OpenSSL (if PACKAGE_CRYPTO enabled) — typically disabled on Windows.
  4. PCRE (if PACKAGE_PCRE enabled)
  5. MySQL client (if PACKAGE_DB enabled with MySQL support)
  6. SQLite3 (if PACKAGE_DB_SQLITE enabled)
  7. PostgreSQL (if PACKAGE_DB enabled with PostgreSQL support)
  8. GoogleTest (for running unit tests)

Bundled third-party libraries (no need to install): libevent 2.0+, libtelnet, libwebsockets, ghc::filesystem, backward-cpp, utf8_decoder_dfa, widecharwidth.

Platform Guides​

This is the best Linux distro to build & run FluffOS; support for other distros is best-effort only.

Install dependencies​

sudo apt update
sudo apt install -y build-essential autoconf automake bison expect \
  libmysqlclient-dev libpcre3-dev libpq-dev libsqlite3-dev \
  libssl-dev libtool libz-dev telnet libjemalloc-dev libicu-dev \
  libgtest-dev pkg-config libffi-dev
note

flex is only needed if you modify the LPC lexer (src/compiler/internal/lexer.l). Otherwise the build uses the pre-committed generated lexer.

For sanitizer builds (memory debugging), also install:

sudo apt install -y libdw-dev libbz2-dev

Check out the git repo​

git clone https://github.com/fluffos/fluffos.git
cd fluffos
git checkout master  # or a release tag like v2019

Ensure CMake 3.22+​

FluffOS requires CMake 3.22 or higher. Ubuntu 22.04+ includes this by default. If needed:

sudo apt install cmake  # or
sudo pip install --upgrade cmake

Build​

mkdir build && cd build
cmake ..
make -j $(nproc) install

Binary files and support files will be in ./bin/.

Common variants:

# Debug build (for development)
cmake -DCMAKE_BUILD_TYPE=Debug -DPACKAGE_DB_SQLITE=2 ..

# Optimized with debug info (recommended for testing)
cmake -DCMAKE_BUILD_TYPE=RelWithDebInfo -DPACKAGE_DB_SQLITE=2 ..

# Sanitizer build (memory debugging)
export CC=clang CXX=clang++
cmake -DCMAKE_BUILD_TYPE=Debug -DPACKAGE_DB_SQLITE=2 -DENABLE_SANITIZER=ON ..

Build Configuration Options​

Packages​

By default, the driver builds a default list of built-in packages. To disable specific packages:

cmake .. -DPACKAGE_CRYPTO=OFF -DPACKAGE_DB=OFF

Common package options:

  • PACKAGE_DB_SQLITE=1 or =2: enable SQLite support
    • =1 enables SQLite3 API version 1
    • =2 enables SQLite3 API version 2 (recommended, includes newer features)
  • PACKAGE_DB_MYSQL="": disable MySQL (or set to enable)
  • PACKAGE_CRYPTO=OFF: disable the crypto package (typical on Windows)
  • PACKAGE_PCRE=OFF: disable the PCRE package

Build types​

FluffOS supports the standard CMake build types:

  • Debug: no optimization, full debug symbols (-DCMAKE_BUILD_TYPE=Debug)
  • Release: full optimization, no debug symbols (-DCMAKE_BUILD_TYPE=Release)
  • RelWithDebInfo: optimized with debug symbols (-DCMAKE_BUILD_TYPE=RelWithDebInfo) — recommended for testing

CPU compatibility​

warning

By default, a driver built in release mode is optimized for the current CPU only, using -march=native. Copying the driver to another machine with a different CPU may not work!

If you need portable drivers, turn off MARCH_NATIVE:

cmake .. -DMARCH_NATIVE=OFF

This is automatically disabled in CI for Windows, Docker, and when building for distribution.

Static linking​

You can force static linking for all libraries:

cmake .. -DSTATIC=ON

This only works in specialized environments like Alpine Linux and Windows/MSYS2.

Sanitizer builds​

Enable AddressSanitizer for memory debugging:

cmake .. -DENABLE_SANITIZER=ON

Requirements:

  • Use the Clang compiler (recommended).
  • Install additional dependencies on Ubuntu: libdw-dev libbz2-dev.
  • Build in Debug or RelWithDebInfo mode.

Testing​

After building, run both test layers:

# C++ unit tests (GoogleTest)
cd build
CTEST_OUTPUT_ON_FAILURE=1 make test

# LPC testsuite (tests the driver with actual LPC code)
cd ../testsuite
../build/bin/driver etc/config.test -ftest

Continuous integration​

FluffOS uses GitHub Actions for automated testing on every push and pull request — Ubuntu (GCC and Clang), Ubuntu with sanitizers, macOS (Apple Silicon), Windows (MSYS2/MINGW64), and a WebAssembly job that runs the LPC testsuite inside the wasm driver under node. All CI workflows run both unit tests and the LPC testsuite; CodeQL and Coverity Scan provide static analysis. See .github/workflows/ for the exact configuration.