build: initial repository setup (M0)

CMake project structure with ymir_core, ymir_naval, and ymir_adapters
static library targets. Catch2 and nlohmann/json via FetchContent;
SUNDIALS and CGAL probed as optional system deps (required from M1/M2).
Smoke tests pass on macOS ARM64. Docker multi-stage image for Linux
x86_64. GitHub Actions CI matrix: Linux x86_64, macOS ARM64, Windows
x86_64. Code quality tooling: .clang-format, .clang-tidy, Doxyfile.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

.clang-format

@@ -0,0 +1,32 @@
+---
+BasedOnStyle: LLVM
+Language: Cpp
+Standard: c++17
+
+IndentWidth: 4
+ColumnLimit: 100
+TabWidth: 4
+UseTab: Never
+
+BreakBeforeBraces: Allman
+AllowShortFunctionsOnASingleLine: Inline
+AllowShortIfStatementsOnASingleLine: Never
+AllowShortLoopsOnASingleLine: false
+
+SortIncludes: true
+IncludeBlocks: Regroup
+IncludeCategories:
+  - Regex:    '^<ymir/'
+    Priority: 1
+  - Regex:    '^<catch2/'
+    Priority: 2
+  - Regex:    '^<'
+    Priority: 3
+  - Regex:    '.*'
+    Priority: 4
+
+PointerAlignment: Left
+ReferenceAlignment: Left
+SpaceBeforeParens: ControlStatements
+SpaceAfterCStyleCast: false
+SpacesInContainerLiterals: false

.clang-tidy

@@ -0,0 +1,26 @@
+Checks: >
+  modernize-*,
+  readability-*,
+  bugprone-*,
+  performance-*,
+  -modernize-use-trailing-return-type,
+  -readability-magic-numbers,
+  -readability-named-parameter
+
+WarningsAsErrors: "*"
+
+HeaderFilterRegex: "^(core|naval|adapters)/include/.*"
+
+CheckOptions:
+  - key: readability-identifier-naming.ClassCase
+    value: CamelCase
+  - key: readability-identifier-naming.FunctionCase
+    value: camelBack
+  - key: readability-identifier-naming.VariableCase
+    value: camelBack
+  - key: readability-identifier-naming.MemberCase
+    value: camelBack
+  - key: readability-identifier-naming.ConstantCase
+    value: UPPER_CASE
+  - key: readability-identifier-naming.NamespaceCase
+    value: lower_case

.github/workflows/ci.yml

@@ -0,0 +1,68 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  build-and-test:
+    name: ${{ matrix.name }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - name: Linux x86_64
+            os: ubuntu-22.04
+            cmake_extra: ""
+
+          - name: macOS ARM64
+            os: macos-14
+            cmake_extra: ""
+
+          - name: Windows x86_64
+            os: windows-latest
+            cmake_extra: >-
+              -DCMAKE_TOOLCHAIN_FILE=$env:VCPKG_ROOT/scripts/buildsystems/vcpkg.cmake
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Install dependencies (Linux)
+        if: runner.os == 'Linux'
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y --no-install-recommends \
+            ninja-build \
+            libcgal-dev \
+            libsundials-dev
+
+      - name: Install dependencies (macOS)
+        if: runner.os == 'macOS'
+        run: |
+          brew install ninja cgal sundials
+
+      - name: Install dependencies (Windows)
+        if: runner.os == 'Windows'
+        run: |
+          # vcpkg is pre-installed on windows-latest
+          # CGAL and SUNDIALS are optional until M1/M2 — skipped here to avoid
+          # long compile times. Add when needed:
+          #   vcpkg install cgal:x64-windows sundials:x64-windows
+          choco install ninja --no-progress
+
+      - name: Configure
+        run: >
+          cmake -B build
+          -DCMAKE_BUILD_TYPE=Release
+          -DYMIR_BUILD_TESTS=ON
+          ${{ matrix.cmake_extra }}
+
+      - name: Build
+        run: cmake --build build --parallel
+
+      - name: Test
+        run: ctest --test-dir build --output-on-failure

.gitignore

@@ -1,6 +1,12 @@
 # Reference docs (legacy project — internal only)
 .docs/
 
+# Spec files (working documents — not repo artifacts)
+.specs/
+
+# Doxygen output
+docs/api/
+
 # Build
 build/
 cmake-build-*/

CMakeLists.txt

@@ -0,0 +1,36 @@
+cmake_minimum_required(VERSION 3.16)
+
+project(Ymir
+    VERSION 0.1.0
+    DESCRIPTION "General-purpose physics engine"
+    LANGUAGES CXX
+)
+
+set(CMAKE_CXX_STANDARD 17)
+set(CMAKE_CXX_STANDARD_REQUIRED ON)
+set(CMAKE_CXX_EXTENSIONS OFF)
+
+option(YMIR_BUILD_TESTS  "Build test suite"      ON)
+option(YMIR_BUILD_DOCS   "Generate Doxygen docs" OFF)
+option(YMIR_BUILD_APPS   "Build applications"    OFF)
+
+configure_file(
+    ${CMAKE_CURRENT_SOURCE_DIR}/cmake/version.h.in
+    ${CMAKE_BINARY_DIR}/include/ymir/version.h
+)
+
+include(cmake/Dependencies.cmake)
+include(cmake/CompilerWarnings.cmake)
+
+add_subdirectory(core)
+add_subdirectory(naval)
+add_subdirectory(adapters)
+
+if(YMIR_BUILD_APPS)
+    add_subdirectory(applications)
+endif()
+
+if(YMIR_BUILD_TESTS)
+    enable_testing()
+    add_subdirectory(tests)
+endif()

Doxyfile

@@ -0,0 +1,32 @@
+PROJECT_NAME           = "Ymir"
+PROJECT_NUMBER         = 0.1.0
+PROJECT_BRIEF          = "General-purpose physics engine"
+
+INPUT                  = core/include \
+                         naval/include \
+                         adapters/include \
+                         include
+RECURSIVE              = YES
+FILE_PATTERNS          = *.h *.hpp
+
+OUTPUT_DIRECTORY       = docs/api
+GENERATE_HTML          = YES
+GENERATE_LATEX         = NO
+
+EXTRACT_ALL            = NO
+EXTRACT_PRIVATE        = NO
+EXTRACT_STATIC         = NO
+
+WARN_AS_ERROR          = YES
+QUIET                  = NO
+
+JAVADOC_AUTOBRIEF      = YES
+QT_AUTOBRIEF           = NO
+
+ALPHABETICAL_INDEX     = YES
+HTML_DYNAMIC_SECTIONS  = YES
+
+GENERATE_TREEVIEW      = YES
+DISABLE_INDEX          = NO
+
+HAVE_DOT               = NO

adapters/CMakeLists.txt

@@ -0,0 +1,18 @@
+add_library(ymir_adapters STATIC
+    src/adapters.cpp
+)
+
+target_include_directories(ymir_adapters
+    PUBLIC
+        $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/include>
+        $<INSTALL_INTERFACE:include>
+)
+
+target_link_libraries(ymir_adapters
+    PUBLIC
+        ymir_core
+        ymir_naval
+        nlohmann_json::nlohmann_json
+)
+
+target_set_warnings(ymir_adapters)

adapters/src/adapters.cpp

@@ -0,0 +1,2 @@
+// Adapters — JSON I/O, CSV output, and public C API (DLL boundary).
+// No physics logic here: adapters translate between external formats and core types.

applications/CMakeLists.txt

@@ -0,0 +1,3 @@
+# Applications (executables) — added in M4.
+# fasttime: fast-time simulation runner
+# realtime: real-time simulation host example

cmake/CompilerWarnings.cmake

@@ -0,0 +1,13 @@
+function(target_set_warnings target)
+    if(MSVC)
+        target_compile_options(${target} PRIVATE /W4 /WX /permissive-)
+    else()
+        target_compile_options(${target} PRIVATE
+            -Wall
+            -Wextra
+            -Wpedantic
+            -Werror
+            -Wno-unused-parameter  # relaxed during early development
+        )
+    endif()
+endfunction()

cmake/Dependencies.cmake

@@ -0,0 +1,43 @@
+include(FetchContent)
+
+# ---------------------------------------------------------------------------
+# Catch2 v3 — test framework
+# ---------------------------------------------------------------------------
+FetchContent_Declare(
+    Catch2
+    GIT_REPOSITORY https://github.com/catchorg/Catch2.git
+    GIT_TAG        v3.5.4
+    GIT_SHALLOW    TRUE
+)
+
+# ---------------------------------------------------------------------------
+# nlohmann/json — JSON parser (header-only)
+# ---------------------------------------------------------------------------
+FetchContent_Declare(
+    nlohmann_json
+    GIT_REPOSITORY https://github.com/nlohmann/json.git
+    GIT_TAG        v3.11.3
+    GIT_SHALLOW    TRUE
+)
+
+FetchContent_MakeAvailable(Catch2 nlohmann_json)
+
+# ---------------------------------------------------------------------------
+# SUNDIALS CVODE — ODE integrator (system package, required from M1)
+# ---------------------------------------------------------------------------
+find_package(SUNDIALS QUIET)
+if(SUNDIALS_FOUND)
+    message(STATUS "SUNDIALS found: ${SUNDIALS_VERSION}")
+else()
+    message(STATUS "SUNDIALS not found — ODE integrator unavailable (needed from M1)")
+endif()
+
+# ---------------------------------------------------------------------------
+# CGAL — mesh and geometry library (system package, required from M2)
+# ---------------------------------------------------------------------------
+find_package(CGAL QUIET)
+if(CGAL_FOUND)
+    message(STATUS "CGAL found: ${CGAL_VERSION}")
+else()
+    message(STATUS "CGAL not found — mesh support unavailable (needed from M2)")
+endif()

cmake/version.h.in

@@ -0,0 +1,6 @@
+#pragma once
+
+#define YMIR_VERSION_MAJOR @Ymir_VERSION_MAJOR@
+#define YMIR_VERSION_MINOR @Ymir_VERSION_MINOR@
+#define YMIR_VERSION_PATCH @Ymir_VERSION_PATCH@
+#define YMIR_VERSION_STRING "@Ymir_VERSION@"

core/CMakeLists.txt

@@ -0,0 +1,12 @@
+add_library(ymir_core STATIC
+    src/core.cpp
+)
+
+target_include_directories(ymir_core
+    PUBLIC
+        $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/include>
+        $<BUILD_INTERFACE:${CMAKE_BINARY_DIR}/include>
+        $<INSTALL_INTERFACE:include>
+)
+
+target_set_warnings(ymir_core)

core/src/core.cpp

@@ -0,0 +1,10 @@
+#include <ymir/version.h>
+
+namespace ymir {
+
+const char* version()
+{
+    return YMIR_VERSION_STRING;
+}
+
+} // namespace ymir

docker-compose.yml

@@ -0,0 +1,30 @@
+services:
+  build:
+    build:
+      context: .
+      dockerfile: docker/linux-x86_64/Dockerfile
+      target: builder
+    volumes:
+      - .:/src
+      - ymir_build:/build
+    working_dir: /src
+    command: >
+      sh -c "cmake -B /build -S /src -GNinja -DCMAKE_BUILD_TYPE=Release -DYMIR_BUILD_TESTS=ON
+             && cmake --build /build --parallel"
+
+  test:
+    build:
+      context: .
+      dockerfile: docker/linux-x86_64/Dockerfile
+      target: builder
+    volumes:
+      - .:/src
+      - ymir_build:/build
+    working_dir: /src
+    command: >
+      sh -c "cmake -B /build -S /src -GNinja -DCMAKE_BUILD_TYPE=Release -DYMIR_BUILD_TESTS=ON
+             && cmake --build /build --parallel
+             && ctest --test-dir /build --output-on-failure"
+
+volumes:
+  ymir_build:

docker/linux-x86_64/Dockerfile

@@ -0,0 +1,33 @@
+# Stage 1: builder — system deps only, no source
+FROM ubuntu:22.04 AS builder
+
+ENV DEBIAN_FRONTEND=noninteractive
+
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    gcc-12 \
+    g++-12 \
+    cmake \
+    ninja-build \
+    git \
+    ca-certificates \
+    libcgal-dev \
+    libsundials-dev \
+    && apt-get clean \
+    && rm -rf /var/lib/apt/lists/*
+
+RUN update-alternatives --install /usr/bin/gcc gcc /usr/bin/gcc-12 100 \
+    && update-alternatives --install /usr/bin/g++ g++ /usr/bin/g++-12 100
+
+WORKDIR /src
+
+# Stage 2: ci — copies source, configures, builds, and tests
+FROM builder AS ci
+
+COPY . /src
+
+RUN cmake -B /build -S /src \
+        -GNinja \
+        -DCMAKE_BUILD_TYPE=Release \
+        -DYMIR_BUILD_TESTS=ON \
+    && cmake --build /build --parallel \
+    && ctest --test-dir /build --output-on-failure

docs/adr/README.md

@@ -0,0 +1,30 @@
+# Architecture Decision Records
+
+ADRs document significant architectural decisions — what was decided, why, and what the consequences are. They are immutable once accepted; superseded decisions get a new ADR that references the old one.
+
+## Format
+
+```markdown
+# ADR-NNN: Title
+
+**Status**: Proposed | Accepted | Deprecated | Superseded by ADR-XXX
+**Date**: YYYY-MM-DD
+
+## Context
+
+What situation prompted this decision? What forces are at play?
+
+## Decision
+
+What was decided, stated clearly and directly.
+
+## Consequences
+
+What becomes easier? What becomes harder? What are the trade-offs?
+```
+
+## Index
+
+| ADR | Title | Status |
+| --- | ----- | ------ |
+| — | *(none yet)* | — |

naval/CMakeLists.txt

@@ -0,0 +1,15 @@
+add_library(ymir_naval STATIC
+    src/naval.cpp
+)
+
+target_include_directories(ymir_naval
+    PUBLIC
+        $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/include>
+        $<INSTALL_INTERFACE:include>
+)
+
+target_link_libraries(ymir_naval
+    PUBLIC ymir_core
+)
+
+target_set_warnings(ymir_naval)

naval/src/naval.cpp

@@ -0,0 +1,2 @@
+// Naval domain module — force models for ships and floating platforms.
+// Implements ForceModel interfaces defined in ymir_core (from M1 onwards).

tests/CMakeLists.txt

@@ -0,0 +1,13 @@
+add_executable(ymir_tests
+    SmokeTest.cpp
+)
+
+target_link_libraries(ymir_tests
+    PRIVATE
+        ymir_core
+        Catch2::Catch2WithMain
+)
+
+include(CTest)
+include(Catch)
+catch_discover_tests(ymir_tests)

tests/SmokeTest.cpp

@@ -0,0 +1,15 @@
+#include <catch2/catch_test_macros.hpp>
+#include <ymir/version.h>
+
+TEST_CASE("build system is wired up", "[smoke]")
+{
+    REQUIRE(YMIR_VERSION_MAJOR >= 0);
+    REQUIRE(YMIR_VERSION_MINOR >= 0);
+    REQUIRE(YMIR_VERSION_PATCH >= 0);
+}
+
+TEST_CASE("version string is non-empty", "[smoke]")
+{
+    std::string v = YMIR_VERSION_STRING;
+    REQUIRE_FALSE(v.empty());
+}