Integrate Core as a Git Submodule

The recommended way to consume Erbsland Core is to pin it as a Git submodule and build it with your application. This gives your project an exact dependency revision and lets the compiler apply one consistent toolchain and build configuration across application and library code.

Recommended Project Layout

Place all Erbsland Core libraries below one directory:

<project>
    ├── erbsland
    │   ├── core                    # Git submodule
    │   ├── <extension>             # Future Erbsland Core extension
    │   └── CMakeLists.txt          # Erbsland Core aggregation
    ├── <application-or-library>
    │   ├── src
    │   └── CMakeLists.txt
    └── CMakeLists.txt

Add Core from the project root:

$ mkdir erbsland
$ git submodule add https://github.com/erbsland-dev/erbsland-core.git erbsland/core

Initialize all recorded dependencies after cloning a project:

$ git submodule update --init --recursive

Aggregate Erbsland Core Libraries

The project root only needs to know about the erbsland directory and its own targets:

<project>/CMakeLists.txt

cmake_minimum_required(VERSION 3.28)
project(ExampleProject LANGUAGES CXX)

add_subdirectory(erbsland)
add_subdirectory(app)

The aggregation file owns the individual Erbsland Core subdirectories:

<project>/erbsland/CMakeLists.txt

add_subdirectory(core EXCLUDE_FROM_ALL)
# add_subdirectory(<extension> EXCLUDE_FROM_ALL)

This structure keeps the top-level project stable when extensions are added or removed. Add Core before extensions because an extension may use Core’s types and CMake target.

Configure an Application Target

Pass each executable target to Core’s application setup helper:

<project>/app/CMakeLists.txt

add_executable(example src/main.cpp)
erbsland_core_setup_application(TARGET example)

erbsland_core_setup_application() links erbsland::core, enables C++20, disables C++ module scanning for the target, and selects UTF-8 source and execution character sets on MSVC. Calling it more than once for the same executable is safe.

Pass static-library targets to the corresponding setup helper:

add_library(example_library STATIC src/library.cpp)
erbsland_core_setup_static_library(TARGET example_library)

erbsland_core_setup_static_library() publishes Core, C++20, and the MSVC UTF-8 option to consumers while applying the target-local module-scanning setting to the library itself. Calling it more than once for the same static library is safe.

Include only public headers below <erbsland/...>. Use focused headers for individual APIs or domain headers such as <erbsland/all_path.hpp> when a source file works with many related types. Do not include files through src/erbsland or depend on impl headers.

Update Deliberately

Update Core inside the submodule, test your application, and then commit the new submodule revision in the parent repository:

$ git -C erbsland/core fetch
$ git -C erbsland/core switch --detach <tested-revision>
$ git add erbsland/core

Erbsland Core is currently alpha and may introduce intentional breaking API changes. Review the Changelog and run your complete test suite before recording a new revision.