Setup

LightnerX is a C++17 library built statically by default. CMake provides the LightnerX target. The application supplies its own executable.

Dependencies and toolchain

Use CMake 3.22 or newer, a C++17 compiler, and a build tool such as Ninja. The CI matrix builds with GCC 14 and Clang 19 on Linux in Debug and Release.

LightnerX uses three pinned Git submodules.

Dependency Path
GameNetworkingSockets external/GameNetworkingSockets
tcbrindle/span external/span
zeus-cpp/expected v1.4.0 external/expected

Initialize or update them from the repository root.

git submodule update --init --recursive

Install the OpenSSL and Protobuf development packages and the Protobuf compiler. Running the regression suite also requires Python 3, Bash and a GCC- or Clang-compatible compiler driver. On Debian 13, install these packages.

sudo apt-get install cmake g++-14 clang-19 ninja-build libssl-dev libprotobuf-dev protobuf-compiler python3-venv pkg-config
cmake --version

Use a distribution package providing CMake 3.22 or newer. To reproduce the minimum-version check independently of the system package:

python3 -m venv .venv
.venv/bin/pip install cmake==3.22.0
export PATH="$PWD/.venv/bin:$PATH"

If dependencies live in a separate prefix, pass -DCMAKE_PREFIX_PATH=/path/to/prefix when configuring.

Build

cmake -S . -B build/debug -G Ninja -DCMAKE_BUILD_TYPE=Debug
cmake --build build/debug --parallel 2

To select a compiler, pass -DCMAKE_C_COMPILER=gcc-14 -DCMAKE_CXX_COMPILER=g++-14, or -DCMAKE_C_COMPILER=clang-19 -DCMAKE_CXX_COMPILER=clang++-19, in a fresh build directory. Use -DCMAKE_BUILD_TYPE=Release for a release build.

LightnerX uses the shared GNS target when available. Configure with -DBUILD_SHARED_LIB=OFF -DBUILD_STATIC_LIB=ON to use static GNS. These options select the GNS variant independently of LightnerX.

Consuming with CMake

The target propagates C++17, LightnerX and dependency headers, compile definitions and link requirements. Consumers link LightnerX:

cmake_minimum_required(VERSION 3.22)
set(CMAKE_CXX_EXTENSIONS OFF)
project(MyGame LANGUAGES C CXX)

add_subdirectory(external/LightnerX)
add_executable(game main.cpp)
target_link_libraries(game PRIVATE LightnerX)
#include <lightnerx/network/client.hpp>

int main() {
    lightnerx::network::Client client;
    return client.start() ? 0 : 1;
}

Use ordinary headers and sources with compatible compiler and standard-library ABIs. Each former module has a corresponding header, for example <lightnerx/network/server.hpp>, with definitions in network/server.cpp. The independent tests/consumer project checks propagated requirements and shared network/queue state across translation units. All public headers also compile in isolation.

Byte views use tcb::span from <tcb/span.hpp> and results use zeus::expected from <zeus/expected.hpp>. Both dependencies are header-only and available to consumers through the LightnerX target. See C++17 byte views and results for examples.

For a host application that loads multiple plugins, configure with -DLIGHTNERX_BUILD_SHARED=ON and link each plugin to the same LightnerX target from the host build. Ship one shared library instance with the application. Static linking is supported for consumers that link LightnerX once into the process. Separate static copies embedded in plugins have separate state and can interfere with the same GNS runtime.

Regression tests

cmake -S . -B build/tests -G Ninja -DCMAKE_BUILD_TYPE=Debug -DLIGHTNERX_BUILD_TESTS=ON
cmake --build build/tests --parallel 2
ctest --test-dir build/tests --output-on-failure

Tests cover deterministic protocol characterization, routing and allocation failures, the complete client ID domain, callbacks, ownership and multi-file consumers. They also compile the documentation's C++ examples. Checks remain active in Release. Network integration requires local UDP socket access. Shared LightnerX builds on Unix also test that two loaded modules share ownership of the runtime. The byte-for-byte comparison with the historical fixture runs on little-endian hosts. On big-endian hosts, that test checks the symbolic error results and parser call count.

For cross-version UDP tests, also pass -DLIGHTNERX_REFERENCE_BINARY=/absolute/path/to/original/lightnerx_test_lifecycle. CTest then pairs the old server with the new client and the new server with the old client. Migration validation identifies the original revision and build requirements. The CI workflow builds it separately.

Sanitizers

cmake -S . -B build/sanitizers -G Ninja -DCMAKE_BUILD_TYPE=Debug \
  -DLIGHTNERX_BUILD_TESTS=ON -DLIGHTNERX_SANITIZERS=address,undefined
cmake --build build/sanitizers --parallel 2
ASAN_OPTIONS=detect_leaks=1:halt_on_error=1 UBSAN_OPTIONS=halt_on_error=1 \
  ctest --test-dir build/sanitizers --output-on-failure

This instruments LightnerX and its consumers, including tests and any dependency templates instantiated in their code. The GameNetworkingSockets build disables RTTI, so GNS-linked targets disable UBSan's vptr check. The standalone mock tests enable both ASan and UBSan when sanitizers are requested. The lifecycle fault test uses the selected sanitizer list and links to the configured GNS target. Enabled sanitizer diagnostics fail tests immediately. LeakSanitizer may require execution outside a ptrace-restricted sandbox.