Phase 2 foundation: CI, docs, and test structure

.clangd

@@ -0,0 +1,9 @@
+If:
+  PathMatch: (bsp/.*|examples/.*)
+CompileFlags:
+  CompilationDatabase: build/stm32f407-debug
+  Compiler: arm-none-eabi-gcc
+  Add: [--target=arm-none-eabi]
+---
+CompileFlags:
+  CompilationDatabase: build/host-debug

.github/workflows/ci.yml

@@ -0,0 +1,97 @@
+name: CI
+
+on:
+  pull_request:
+  workflow_dispatch:
+
+jobs:
+  host:
+    runs-on: windows-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup MinGW host tools
+        uses: msys2/setup-msys2@v2
+        with:
+          update: true
+          install: >-
+            mingw-w64-ucrt-x86_64-gcc
+            mingw-w64-ucrt-x86_64-cmake
+            mingw-w64-ucrt-x86_64-make
+
+      - name: Add MinGW tools to PATH
+        shell: pwsh
+        run: |
+          "C:\msys64\ucrt64\bin" | Out-File -FilePath $env:GITHUB_PATH -Encoding utf8 -Append
+
+      - name: make test
+        shell: pwsh
+        run: make test
+
+      - name: Build host preset
+        shell: pwsh
+        run: cmake --build --preset host-debug
+
+      - name: Run host ctest
+        shell: pwsh
+        run: ctest --preset host-debug
+
+  stm32f407:
+    runs-on: windows-latest
+    needs: host
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup MinGW host tools
+        uses: msys2/setup-msys2@v2
+        with:
+          update: true
+          install: >-
+            mingw-w64-ucrt-x86_64-gcc
+            mingw-w64-ucrt-x86_64-cmake
+            mingw-w64-ucrt-x86_64-make
+
+      - name: Add MinGW tools to PATH
+        shell: pwsh
+        run: |
+          "C:\msys64\ucrt64\bin" | Out-File -FilePath $env:GITHUB_PATH -Encoding utf8 -Append
+
+      - name: Install Arm GNU Toolchain
+        shell: pwsh
+        run: |
+          winget install --id Arm.ArmGnuToolchain -e --accept-package-agreements --accept-source-agreements --silent
+
+          $roots = @(
+            'C:\Program Files (x86)\Arm GNU Toolchain arm-none-eabi',
+            'C:\Program Files\Arm GNU Toolchain arm-none-eabi'
+          )
+          $selected = $null
+
+          foreach ($root in $roots) {
+            if (Test-Path $root) {
+              $selected = Get-ChildItem -Path $root -Directory |
+                Sort-Object Name -Descending |
+                Select-Object -First 1 -ExpandProperty FullName
+              if ($selected) {
+                break
+              }
+            }
+          }
+
+          if (-not $selected) {
+            throw 'Arm GNU Toolchain installation path not found.'
+          }
+
+          "MONAR_ARM_GCC_ROOT=$selected" | Out-File -FilePath $env:GITHUB_ENV -Encoding utf8 -Append
+
+      - name: Configure stm32f407 preset
+        shell: pwsh
+        run: cmake --preset stm32f407-debug
+
+      - name: Build stm32f407 preset
+        shell: pwsh
+        run: cmake --build --preset stm32f407-debug

.gitignore

@@ -0,0 +1,15 @@
+build/
+.cache/
+CMakeUserPresets.json
+compile_commands.json
+
+*.o
+*.obj
+*.a
+*.lib
+*.d
+*.elf
+*.bin
+*.hex
+*.map
+*.exe

.vscode/extensions.json

@@ -0,0 +1,7 @@
+{
+  "recommendations": [
+    "ms-vscode.cpptools",
+    "ms-vscode.cmake-tools",
+    "llvm-vs-code-extensions.vscode-clangd"
+  ]
+}

.vscode/settings.json

@@ -0,0 +1,23 @@
+{
+  "cmake.useCMakePresets": "always",
+  "cmake.configureOnOpen": false,
+  "cmake.configureEnvironment": {
+    "PATH": "${workspaceFolder};${env:PATH}",
+    "MONAR_ARM_GCC_ROOT": "${env:MONAR_ARM_GCC_ROOT}"
+  },
+  "cmake.buildEnvironment": {
+    "PATH": "${workspaceFolder};${env:PATH}",
+    "MONAR_ARM_GCC_ROOT": "${env:MONAR_ARM_GCC_ROOT}"
+  },
+  "terminal.integrated.env.windows": {
+    "PATH": "${workspaceFolder};${env:PATH}",
+    "MONAR_ARM_GCC_ROOT": "${env:MONAR_ARM_GCC_ROOT}"
+  },
+  "C_Cpp.default.configurationProvider": "ms-vscode.cmake-tools",
+  "clangd.arguments": [
+    "--compile-commands-dir=${workspaceFolder}/build/host-debug"
+  ],
+  "files.associations": {
+    "*.ld": "ld"
+  }
+}

.vscode/tasks.json

@@ -0,0 +1,77 @@
+{
+  "version": "2.0.0",
+  "tasks": [
+    {
+      "label": "cmake: configure host",
+      "type": "shell",
+      "command": "cmake",
+      "args": [
+        "--preset",
+        "host-debug"
+      ],
+      "group": "build",
+      "problemMatcher": [
+        "$gcc"
+      ]
+    },
+    {
+      "label": "cmake: build host",
+      "type": "shell",
+      "command": "cmake",
+      "args": [
+        "--build",
+        "--preset",
+        "host-debug"
+      ],
+      "group": "build",
+      "dependsOn": "cmake: configure host",
+      "problemMatcher": [
+        "$gcc"
+      ]
+    },
+    {
+      "label": "cmake: run host test",
+      "type": "shell",
+      "command": "ctest",
+      "args": [
+        "--preset",
+        "host-debug"
+      ],
+      "dependsOn": "cmake: build host",
+      "problemMatcher": [
+        "$gcc"
+      ]
+    },
+    {
+      "label": "cmake: configure stm32f407",
+      "type": "shell",
+      "command": "cmake",
+      "args": [
+        "--preset",
+        "stm32f407-debug"
+      ],
+      "group": "build",
+      "problemMatcher": [
+        "$gcc"
+      ]
+    },
+    {
+      "label": "cmake: build stm32f407",
+      "type": "shell",
+      "command": "cmake",
+      "args": [
+        "--build",
+        "--preset",
+        "stm32f407-debug"
+      ],
+      "dependsOn": "cmake: configure stm32f407",
+      "group": {
+        "kind": "build",
+        "isDefault": true
+      },
+      "problemMatcher": [
+        "$gcc"
+      ]
+    }
+  ]
+}

CMakeLists.txt

@@ -0,0 +1,39 @@
+cmake_minimum_required(VERSION 3.20)
+
+include(cmake/monar_options.cmake)
+
+project(Monar VERSION 0.1.0 LANGUAGES C ASM)
+
+set(CMAKE_C_STANDARD 11)
+set(CMAKE_C_STANDARD_REQUIRED ON)
+set(CMAKE_C_EXTENSIONS OFF)
+set(CMAKE_EXPORT_COMPILE_COMMANDS ON)
+
+if(MONAR_BUILD_TESTS)
+    enable_testing()
+endif()
+
+add_subdirectory(src)
+add_subdirectory(runtimes)
+
+if(MONAR_PLATFORM STREQUAL "stm32f407")
+    add_subdirectory(bsp)
+endif()
+
+if(MONAR_BUILD_EXAMPLES)
+    add_subdirectory(examples)
+endif()
+
+if(MONAR_BUILD_TESTS)
+    add_subdirectory(tests)
+endif()
+
+if(CMAKE_EXPORT_COMPILE_COMMANDS)
+    add_custom_target(monar_sync_compile_commands
+        COMMAND ${CMAKE_COMMAND} -E copy_if_different
+            ${CMAKE_CURRENT_BINARY_DIR}/compile_commands.json
+            ${CMAKE_CURRENT_SOURCE_DIR}/compile_commands.json
+        COMMENT "Sync compile_commands.json to repository root"
+        VERBATIM
+    )
+endif()

CMakePresets.json

@@ -0,0 +1,61 @@
+{
+  "version": 5,
+  "cmakeMinimumRequired": {
+    "major": 3,
+    "minor": 20,
+    "patch": 0
+  },
+  "configurePresets": [
+    {
+      "name": "base-debug",
+      "hidden": true,
+      "generator": "MinGW Makefiles",
+      "cacheVariables": {
+        "CMAKE_BUILD_TYPE": "Debug",
+        "MONAR_RUNTIME": "baremetal"
+      }
+    },
+    {
+      "name": "host-debug",
+      "displayName": "Host Debug",
+      "inherits": "base-debug",
+      "binaryDir": "${sourceDir}/build/host-debug",
+      "cacheVariables": {
+        "MONAR_PLATFORM": "host",
+        "MONAR_BUILD_TESTS": "ON",
+        "MONAR_BUILD_EXAMPLES": "OFF"
+      }
+    },
+    {
+      "name": "stm32f407-debug",
+      "displayName": "STM32F407 Debug",
+      "inherits": "base-debug",
+      "binaryDir": "${sourceDir}/build/stm32f407-debug",
+      "toolchainFile": "${sourceDir}/cmake/toolchains/arm-none-eabi-gcc.cmake",
+      "cacheVariables": {
+        "MONAR_PLATFORM": "stm32f407",
+        "MONAR_BUILD_TESTS": "OFF",
+        "MONAR_BUILD_EXAMPLES": "ON"
+      }
+    }
+  ],
+  "buildPresets": [
+    {
+      "name": "host-debug",
+      "configurePreset": "host-debug"
+    },
+    {
+      "name": "stm32f407-debug",
+      "configurePreset": "stm32f407-debug"
+    }
+  ],
+  "testPresets": [
+    {
+      "name": "host-debug",
+      "configurePreset": "host-debug",
+      "output": {
+        "outputOnFailure": true
+      }
+    }
+  ]
+}

CMakeUserPresets.example.json

@@ -0,0 +1,46 @@
+{
+  "version": 5,
+  "configurePresets": [
+    {
+      "name": "local-mingw-env",
+      "hidden": true,
+      "environment": {
+        "PATH": "C:/msys64/mingw64/bin;$penv{PATH}",
+        "MONAR_ARM_GCC_ROOT": "C:/Program Files (x86)/Arm GNU Toolchain arm-none-eabi/12.2 mpacbti-rel1"
+      }
+    },
+    {
+      "name": "host-debug-local",
+      "inherits": [
+        "host-debug",
+        "local-mingw-env"
+      ]
+    },
+    {
+      "name": "stm32f407-debug-local",
+      "inherits": [
+        "stm32f407-debug",
+        "local-mingw-env"
+      ]
+    }
+  ],
+  "buildPresets": [
+    {
+      "name": "host-debug-local",
+      "configurePreset": "host-debug-local"
+    },
+    {
+      "name": "stm32f407-debug-local",
+      "configurePreset": "stm32f407-debug-local"
+    }
+  ],
+  "testPresets": [
+    {
+      "name": "host-debug-local",
+      "configurePreset": "host-debug-local",
+      "output": {
+        "outputOnFailure": true
+      }
+    }
+  ]
+}