Configure the Core Build

Core adjusts its defaults depending on whether it is the top-level CMake project or embedded below another project. An application that uses the recommended submodule layout therefore receives a small consumer build by default.

CMake Options

Core build options
Option	Top level	Embedded	Purpose
`ERBSLAND_CORE_ENABLE_TESTS`	On	Off	Builds and registers the Core unit-test executable.
`ERBSLAND_CORE_ENABLE_DEMOS`	On	Off	Configures the Core demo applications as explicit targets.
`ERBSLAND_CORE_ENABLE_INTEROP_TESTS`	Off	Off	Configures standalone interoperability executables and their external-language counterparts.
`ERBSLAND_CORE_ENABLE_PRECOMPILED_HEADERS`	On	Off	Uses Core’s private standard-library precompiled header to reduce full-build time.
`ERBSLAND_CORE_DO_NOT_FLATTEN_NS`	On	Off	Keeps APIs in their domain namespaces instead of importing them into `erbsland`.
`ERBSLAND_CORE_DEVELOPER_BUILD`	On	Off	Enables debug-only developer hooks and development build settings.

Options whose top-level and embedded defaults differ derive from CMake’s PROJECT_IS_TOP_LEVEL value. Set an option before add_subdirectory(erbsland) or pass it on the configure command line:

$ cmake -S . -B cmake-build -DERBSLAND_CORE_ENABLE_PRECOMPILED_HEADERS=ON

For a checked-in project policy, create the cache value before adding Erbsland:

set(ERBSLAND_CORE_ENABLE_PRECOMPILED_HEADERS ON CACHE BOOL "Enable Core precompiled headers")
add_subdirectory(erbsland)

Tests and Demos

Tests are part of a top-level Core development build and can be run through CTest:

$ cmake -S erbsland/core -B cmake-build-core -G Ninja -DCMAKE_BUILD_TYPE=Debug
$ cmake --build cmake-build-core
$ ctest --test-dir cmake-build-core --output-on-failure

Interoperability tests are intentionally separate from unit tests because they launch subprocesses. Enable and run the system and network suites manually. The network suite requires a Rust toolchain and builds the pinned rustls counterpart through Cargo:

$ cmake -S erbsland/core -B cmake-build-interop -G Ninja -DCMAKE_BUILD_TYPE=Debug \
    -DERBSLAND_CORE_ENABLE_INTEROP_TESTS=ON
$ cmake --build cmake-build-interop \
    --target erbsland-core-system-interop erbsland-core-network-interop
$ cmake-build-interop/test/interop/system/erbsland-core-system-interop
$ cmake-build-interop/test/interop/network/erbsland-core-network-interop

Demos are configured but excluded from the default build. Build all registered demos explicitly with:

$ cmake --build cmake-build-core --target erbsland-core-all-demos

Precompiled Headers and Unity Builds

Precompiled headers are a private build optimization and do not affect Core’s public API. Disable them for an unsupported or unusual compiler with -DERBSLAND_CORE_ENABLE_PRECOMPILED_HEADERS=OFF.

When Core is top-level, developer mode is enabled, and CMAKE_UNITY_BUILD was not explicitly set, Core enables CMake unity builds to reduce clean build time. An embedded build never changes this setting automatically. Select a conventional build with -DCMAKE_UNITY_BUILD=OFF or explicitly enable unity builds with -DCMAKE_UNITY_BUILD=ON.

Core’s unit tests and demos follow the selected unity-build mode. The conventional CI workflow builds the unit tests without unity builds or precompiled headers to verify translation-unit isolation.

Namespace Configuration

Regular consumer builds flatten domain namespaces into erbsland. This makes erbsland::text::String available as erbsland::String and provides the short alias el so user-code can use el::String.

Set ERBSLAND_CORE_DO_NOT_FLATTEN_NS to keep types only in their domain namespaces. The CMake option publishes the corresponding compile definition through erbsland::core so Core and its consumers use the same header configuration.

Two consumer compile definitions control only the short namespace alias:

ERBSLAND_NO_SHORT_NAMESPACE: Disables the el alias.
ERBSLAND_SHORT_NAMESPACE=<name>: Replaces el with another namespace alias.

Apply them to the consuming target when needed:

target_compile_definitions(example PRIVATE ERBSLAND_SHORT_NAMESPACE=myel)

These namespace options change source spelling, not the underlying C++ symbols or static-library ABI.