kit

Cross-platform C/C++ toolset library targeting Linux, macOS, and Windows.

CI

GitHub Actions runs on every push and pull request against main:

Platform	Compiler	Runner
Linux	GCC 13	ubuntu-24.04
macOS	AppleClang	macos-14
Windows	MSVC 2022	windows-2022

Workflow: .github/workflows/ci.yml

Requirements

Native build

Tool	Version
CMake	4.0+
C compiler	C11 support (GCC, Clang, MSVC)
C++ compiler	C++20 support (GCC 13+, Clang 15+, MSVC 2022+)
clang-format	20+ (for git pre-commit hook)
Python	3.10+ (for build/format scripts)

C++ is used for header-only modules (list.hpp) and Google Test. The compiled library core is pure C.

Linux cross-build via Docker

Tool	Version
Docker	20.10+
bash	4.0+

No other local dependencies needed; the Docker image includes CMake 4.0.1, GCC 13, and all required tooling.

Project structure

kit/
├── CMakeLists.txt               # root: project version, options, subdirectories
├── CMakePresets.json            # configure presets: windows, macos, linux
├── cmake/Platform.cmake         # OS detection, compiler flags
├── Dockerfile                   # Linux build environment (Ubuntu 24.04)
├── include/kit/
│   ├── kit.h                    # facade header + kit_version()
│   ├── export.h                 # KIT_API visibility macro
│   ├── version.h.in             # template -> version.h (generated by CMake)
│   ├── ts_helpers.h             # platform macros, text macros, compiler helpers
│   ├── list.hpp                 # doubly-linked list with memory pool allocator (kit::c_lst)
│   ├── shared.h                 # shared memory (conditional platform include)
│   └── detail/
│       ├── PShared_linux.h      # POSIX shm_open / sem_open implementation
│       └── PShared_win32.h      # CreateFileMapping / CreateMutex implementation
├── src/
│   ├── CMakeLists.txt           # OBJECT target -> static + shared libraries
│   └── version.cpp              # kit_version() implementation
├── tests/
│   ├── CMakeLists.txt           # Google Test v1.17.0 via FetchContent
│   ├── main.cpp                 # test entry point
│   └── list_test.hpp            # 39 tests for kit::c_lst
└── scripts/
    ├── cmake_build.py           # cross-platform CMake configure/build helper
    ├── code_format.py           # clang-format check/apply helper
    ├── conftest.py              # pytest path config for test_code_format.py
    ├── test_code_format.py      # tests for code_format.py
    ├── docker_create.sh         # build Docker image
    ├── docker_build.sh          # configure, build, test inside container
    └── git_hooks/
        └── pre-commit           # source for .git/hooks/pre-commit

Modules

Header	Type	Description
kit/ts_helpers.h	portable, header-only	Platform detection (G_OS_LINUX, G_OS_DARWIN, G_OS_WINDOWS), text macros (TM), packing/alignment, UNUSED_ARG
kit/types.h	portable, header-only	Type aliases (tBOOL, tUINT8, tUINT16, tUINT32, tINT64, tXCHAR), TRUE/FALSE constants
kit/list.hpp	portable, header-only	Doubly-linked list kit::c_lst<T> with pool-based allocation. Supports iterators, move semantics, initializer lists
kit/shared.h	platform-dependent, header-only	Shared memory with named locking. Linux: POSIX shm_open/sem_open. Windows: CreateFileMapping/CreateMutex

Build (native)

The project uses CMake presets (CMakePresets.json) and requires building via the helper script:

python3 scripts/cmake_build.py --build

Use --clean to wipe the build directory first:

python3 scripts/cmake_build.py --clean --build

The script auto-detects the platform and selects the matching preset (macos, linux, or windows). Build artifacts go to _Build_mac/, _Build_lnx/, or _Build_wnd/ respectively. The git pre-commit hook is installed automatically on each run.

Running cmake directly at the top level will produce an error directing you to use the script. This guard does not apply when kit is consumed as a subdirectory via FetchContent.

Build (Linux via Docker)

For verifying Linux compilation from macOS or Windows, two scripts are provided.

1. Create the build environment

./scripts/docker_create.sh

Builds a Docker image kit-linux-build based on Ubuntu 24.04 with:

• GCC 13 (g++)
• CMake 4.0.1 (downloaded from GitHub releases)
• make, git

The image is built once and cached. Rebuild it only when you change the Dockerfile or need a toolchain update.

2. Build and run tests

./scripts/docker_build.sh

This script:

1. Checks that the kit-linux-build image exists (run docker_create.sh first if not)
2. Mounts project sources read-only into the container at /src
3. Runs cmake -B /build -S /src (configure)
4. Runs cmake --build /build (compile)
5. Runs ctest --test-dir /build --output-on-failure (test)

Build artifacts are stored in a Docker volume kit-build-cache for incremental rebuilds. To force a clean build:

docker volume rm kit-build-cache
./scripts/docker_build.sh

Integration via FetchContent

cmake_minimum_required(VERSION 4.0)
project(myapp C CXX)

include(FetchContent)
FetchContent_Declare(
    kit
    GIT_REPOSITORY https://github.com/you/kit.git
    GIT_TAG        v0.1.0
)
FetchContent_MakeAvailable(kit)

add_executable(myapp src/main.cpp)
target_link_libraries(myapp PRIVATE kit::kit)

When consumed via FetchContent, tests are not built by default. To enable them:

cmake -B build -DKIT_BUILD_TESTS=ON

Google Test deduplication

If the parent project already fetches Google Test, kit reuses it automatically: the first FetchContent_Declare(googletest) wins, and kit's declaration is silently ignored.

Local development (SOURCE_DIR override)

When developing kit alongside a consumer project, bypass git fetch and point directly at your local checkout:

cmake -B build -DFETCHCONTENT_SOURCE_DIR_KIT=~/Projects/kit

Or via CMakeUserPresets.json (add to .gitignore):

{
    "version": 6,
    "configurePresets": [
        {
            "name": "dev",
            "inherits": "default",
            "cacheVariables": {
                "FETCHCONTENT_SOURCE_DIR_KIT": "${sourceDir}/../kit"
            }
        }
    ]
}

Changes in the local kit directory are picked up immediately on the next cmake --build without any push/tag/fetch cycle.

Code formatting

The project uses clang-format (version 20+) with the style defined in .clang-format.

A pre-commit hook checks that all staged .cpp, .h, .hpp, .c files are properly formatted. The hook is installed automatically by cmake_build.py, or manually:

cp scripts/git_hooks/pre-commit .git/hooks/pre-commit
chmod +x .git/hooks/pre-commit

Check formatting for all project files:

python3 scripts/code_format.py --check --all

Apply formatting to all project files:

python3 scripts/code_format.py --format --all

Check only staged/changed files (this is what the hook does):

python3 scripts/code_format.py --check --staged

Run format script tests:

python3 -m pytest scripts/test_code_format.py -v

Versioning

Strict semver. The single source of truth is the project(kit VERSION x.y.z) line in the root CMakeLists.txt.

• Compile-time: KIT_VERSION_MAJOR, KIT_VERSION_MINOR, KIT_VERSION_PATCH, KIT_VERSION_STRING
• Runtime: kit_version() returns the version string

Semver rules

• PATCH (0.1.0 -> 0.1.1): bug fixes, no API/ABI changes
• MINOR (0.1.0 -> 0.2.0): new features, backward-compatible
• MAJOR (0.x -> 1.0.0): breaking API changes

License

See LICENSE.