fluffos/docs/build.mdx

---
title: Build from Source
---

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

# 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](build-wasm).

**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`):

| Platform | Toolchain | Build types |
|----------|-----------|-------------|
| Ubuntu 24.04 | GCC and Clang (plus Clang + sanitizers) | Debug / RelWithDebInfo |
| macOS 14 (Apple Silicon) | Clang | Debug / RelWithDebInfo |
| Windows (MSYS2/MINGW64) | GCC | Debug / RelWithDebInfo |
| Alpine Linux | GCC, static linking | Docker 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

<Tabs groupId="platform" queryString>
<TabItem value="ubuntu" label="Ubuntu / WSL" default>

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

### Install dependencies

```shell
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:

```shell
sudo apt install -y libdw-dev libbz2-dev
```

### Check out the git repo

```shell
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:

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

### Build

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

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

Common variants:

```shell
# 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 ..
```

</TabItem>
<TabItem value="macos" label="macOS">

Requires macOS 10.15+. Tested on macOS 14 (both Intel and Apple Silicon).

### Install Homebrew

If not already installed, go to [https://brew.sh](https://brew.sh/) and follow the instructions.

### Install dependencies

```shell
brew install cmake pkg-config mysql pcre libgcrypt openssl jemalloc icu4c \
  sqlite3 googletest libffi
```

:::tip
Set `HOMEBREW_NO_INSTALLED_DEPENDENTS_CHECK=1` to speed up brew installs if needed.
:::

### Build

You need to pass environment variables for the OpenSSL and ICU locations:

```shell
mkdir build && cd build
OPENSSL_ROOT_DIR="/usr/local/opt/openssl" ICU_ROOT="/opt/homebrew/opt/icu4c" \
  cmake -DCMAKE_BUILD_TYPE=RelWithDebInfo -DPACKAGE_DB_SQLITE=2 ..
make -j $(sysctl -n hw.ncpu) install
```

This works for both Apple Silicon and Intel Macs with recent Homebrew installations. On **older
Homebrew installations** (if you get ICU-related errors), use `ICU_ROOT="/usr/local/opt/icu4c"`
instead.

:::note
If you encounter issues, check the latest CI configuration in
[`.github/workflows/ci.yml`](https://github.com/fluffos/fluffos/blob/master/.github/workflows/ci.yml).
:::

</TabItem>
<TabItem value="windows" label="Windows (MSYS2)">

**Supported environment**: Windows 10+ with MSYS2/MINGW64. The binary produced can run on Windows 7+.

:::info
The FluffOS LPC VM is always 64-bit! You can't use more than 4GB memory in 32-bit builds.
:::

For the most up-to-date commands, check
[`.github/workflows/ci.yml`](https://github.com/fluffos/fluffos/blob/master/.github/workflows/ci.yml).

### Install MSYS2

1. Download MSYS2 from the official website: [https://www.msys2.org](https://www.msys2.org/)
2. Pick the X86_64 version for 64-bit Windows.

### Update MSYS2

Open **msys2.exe** and sync/update MSYS2:

```shell
pacman -Syu
```

You may need to close and reopen the MSYS2 window. Keep running the update command until there's
nothing left to upgrade.

### Install build dependencies

```shell
pacman --noconfirm -S --needed \
  git mingw-w64-x86_64-toolchain mingw-w64-x86_64-cmake \
  mingw-w64-x86_64-zlib mingw-w64-x86_64-pcre \
  mingw-w64-x86_64-icu mingw-w64-x86_64-sqlite3 \
  mingw-w64-x86_64-jemalloc mingw-w64-x86_64-gtest \
  mingw-w64-x86_64-pkgconf mingw-w64-x86_64-libffi \
  bison make
```

**Optional**: for MySQL/MariaDB support:

```shell
pacman -S mingw-w64-x86_64-libmariadbclient
```

:::warning[Critical]
After installation, close the MSYS2 window and open **MINGW64.exe** instead! All build commands
must run in the MINGW64 shell.
:::

### Build

In the **MINGW64** shell:

```shell
git clone https://github.com/fluffos/fluffos.git
cd fluffos
mkdir build && cd build
cmake -G "MSYS Makefiles" -DCMAKE_BUILD_TYPE=Debug \
  -DMARCH_NATIVE=OFF -DPACKAGE_CRYPTO=OFF \
  -DPACKAGE_DB_MYSQL="" -DPACKAGE_DB_SQLITE=1 ..
make -j $(nproc) install
```

Notes:

- `-DMARCH_NATIVE=OFF`: ensures portability across different CPUs.
- `-DPACKAGE_CRYPTO=OFF`: the crypto package is typically disabled on Windows.
- `-DPACKAGE_DB_SQLITE=1`: enable SQLite (set to 2 for API version 2).
- `-DPACKAGE_DB_MYSQL=""`: disable MySQL (or set to enable).

</TabItem>
<TabItem value="alpine" label="Alpine / Docker">

Alpine Linux is used for building static binaries suitable for Docker containers.

### Install dependencies

```shell
apk add --no-cache linux-headers gcc g++ clang-dev make cmake bash \
    mariadb-dev mariadb-static postgresql-dev sqlite-dev sqlite-static \
    openssl-dev openssl-libs-static zlib-dev zlib-static icu-dev icu-static \
    pcre-dev bison git musl-dev libelf-static elfutils-dev \
    pkgconf libffi-dev zstd-static bzip2-static xz-static
```

### Install jemalloc

jemalloc must be installed manually on Alpine:

```shell
wget -O - https://github.com/jemalloc/jemalloc/releases/download/5.3.0/jemalloc-5.3.0.tar.bz2 | tar -xj
cd jemalloc-5.3.0
./configure --prefix=/usr
make && make install
```

### Build

```shell
git clone https://github.com/fluffos/fluffos.git
cd fluffos
mkdir build && cd build
cmake .. -DMARCH_NATIVE=OFF -DSTATIC=ON
make install
```

Verify the result is a static executable:

```shell
$ ldd bin/driver
    not a dynamic executable
```

### Using Docker

FluffOS provides an official Docker image built automatically on every push to master:

```shell
# Pull and run the official image
docker pull ghcr.io/fluffos/fluffos:master
docker run -it ghcr.io/fluffos/fluffos:master /path/to/config.cfg

# Or build your own
docker build -t fluffos:local .
docker run -it fluffos:local /path/to/config.cfg
```

The `Dockerfile` in the repository root uses a multi-stage build: a builder stage compiles FluffOS
statically on Alpine, and the runtime stage creates a minimal image with just the binary.

</TabItem>
</Tabs>

## Build Configuration Options

### Packages

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

```shell
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`:

```shell
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:

```shell
cmake .. -DSTATIC=ON
```

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

### Sanitizer builds

Enable AddressSanitizer for memory debugging:

```shell
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:

```shell
# 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.