---
layout: doc
title: Build
---

# Getting Started

[[toc]]

## Supported Environment

The best platform to build LODOS is Gentoo.

**Compilers**: LODOS uses C++17 and C11, which requires at least GCC 7+ or LLVM clang 4+.  CMake 3.22+ is required.

**System Library Requirements** (Must install):

1. **ICU**: FluffOS uses ICU for UTF-8 and transcoding support.
2. **jemalloc**: Release build use JEMALLOC by default, and is highly recommended in production.
3. **libxcrypt**: Provides the Unix password hashing algorithms used by `crypt()`. Static builds require its static archive.
4. **libfmt**: Provides C++ string formatting support.
5. **nlohmann_json**: JSON for Modern C++, used for object serialization.
6. **libevent** (2.1+): event-driven network I/O core.
7. **utf8cpp** (4.0+; `dev-libs/utfcpp` on Gentoo): UTF-8 validation and sanitization.
8. **libwebsockets** (4.2+): WebSocket server support. On Gentoo, enable the
   `libevent extensions ssl ipv6` USE flags; HTTP/2 is not required.
9. **gulrak-filesystem** (1.5+; `dev-libs/gulrak-filesystem` on Gentoo): header-only `std::filesystem` polyfill.
10. **OpenSSL** (if PACKAGE_CRYPTO enabled) - Note: typically disabled on Windows
11. **PCRE** (if PACKAGE_PCRE enabled)
12. **MysqlClient** (if PACKAGE_DB enabled with MySQL support)
13. **SQLite3** (if PACKAGE_DB_SQLITE enabled)
14. **PostgreSQL** (if PACKAGE_DB enabled with PostgreSQL support)
15. **GoogleTest** (for running unit tests)

Bundled thirdparty library (no need to install):

1. libtelnet: telnet protocol support
2. utf8_decoder_dfa: fast utf8 validation.
3. widecharwidth: wcwidth with unicode 11

### Build (Standard)

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

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

### Build Types

**Debug Build** (for development):
```shell
$ cmake -DCMAKE_BUILD_TYPE=Debug -DPACKAGE_DB_SQLITE=2 ..
$ make -j $(nproc) install
```

**Release Build with Info** (recommended for testing):
```shell
$ cmake -DCMAKE_BUILD_TYPE=RelWithDebInfo -DPACKAGE_DB_SQLITE=2 ..
$ make -j $(nproc) install
```

**Sanitizer Build** (for memory debugging):
```shell
$ export CC=clang CXX=clang++
$ cmake -DCMAKE_BUILD_TYPE=Debug -DPACKAGE_DB_SQLITE=2 -DENABLE_SANITIZER=ON ..
$ make -j $(nproc) install
```

### Running Tests

After building, run the test suite:
```shell
# Unit tests
$ cd build
$ make test
# or with verbose output
$ CTEST_OUTPUT_ON_FAILURE=1 make test

# LPC testsuite
$ cd testsuite
$ ../build/bin/driver etc/config.test -ftest
```

## Build Configuration Options

### Packages

By default, the driver has a default list of builtin packages to build.

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 crypto package (typical on Windows)
- `PACKAGE_PCRE=OFF`: Disable PCRE package

### Build Types

LODOS supports 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

**By default**, driver built in release mode will optimize for the current system 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
```

Note that this is not tested or supported, so you're on your own.  Make sure you have all the necessary .a files from the various system dependencies installed.

### Sanitizer Builds

Enable AddressSanitizer for memory debugging:

```shell
$ cmake .. -DENABLE_SANITIZER=ON
```

**Requirements**:
- Use Clang compiler (recommended)
- Install additional dependencies on Ubuntu: `libdw-dev libbz2-dev`
- Build in Debug or RelWithDebInfo mode

## Testing

### Unit Tests

LODOS includes C++ unit tests using GoogleTest:

```shell
$ cd build
$ make test
# or with verbose output
$ CTEST_OUTPUT_ON_FAILURE=1 make test
```

### LPC Testsuite

The LPC testsuite tests the driver with actual LPC code:

```shell
$ cd testsuite
$ ../build/bin/driver etc/config.test -ftest
```
