|
| 1 | +# Spacecraft C++ Guidelines — Full Reference |
| 2 | + |
| 3 | +**Version:** 1.0 |
| 4 | +**Date:** 2026-07-13 |
| 5 | +**Author:** Mohamed Hammad & Spacecraft Software |
| 6 | +**Compatibility:** Circle Compiler (Safe C++), Clang 18+, GCC 13+, Fil-C Compiler |
| 7 | + |
| 8 | +This document expands on the `SKILL.md` for C++ systems programming. It provides complete, compile-checked configurations and skeletons for Safe C++ syntax, hardened CMake setups, `std::jthread` concurrency, and testing. |
| 9 | + |
| 10 | +--- |
| 11 | + |
| 12 | +## 1. Safe C++ (safecpp.org) Borrow Checker Syntax |
| 13 | + |
| 14 | +Safe C++ extends the C++ parser to support compile-time borrow checking and safe execution contexts. Structure code inside `safe` blocks to enforce compile-time safety invariants. |
| 15 | + |
| 16 | +```cpp |
| 17 | +// Compilation requires Circle Compiler with Safe C++ enabled. |
| 18 | +#include <std2/vector.h> |
| 19 | +#include <std2/string.h> |
| 20 | +#include <iostream> |
| 21 | + |
| 22 | +public struct TelemetryPacket { |
| 23 | + std2::string id; |
| 24 | + double value; |
| 25 | +}; |
| 26 | + |
| 27 | +// Declaring a safe function restricts unsafe features inside its block |
| 28 | +public safe double calculate_average_value(const std2::vector<TelemetryPacket>& packets) { |
| 29 | + if (packets.empty()) { |
| 30 | + return 0.0; |
| 31 | + } |
| 32 | + |
| 33 | + double sum = 0.0; |
| 34 | + // The borrow checker tracks lifetimes and prevents collection mutation during iteration |
| 35 | + for (const auto& packet : packets) { |
| 36 | + sum += packet.value; |
| 37 | + } |
| 38 | + return sum / packets.size(); |
| 39 | +} |
| 40 | + |
| 41 | +public int main() { |
| 42 | + safe { |
| 43 | + std2::vector<TelemetryPacket> list; |
| 44 | + list.push_back(TelemetryPacket{ .id = "sensor-101", .value = 88.5 }); |
| 45 | + list.push_back(TelemetryPacket{ .id = "sensor-102", .value = 92.1 }); |
| 46 | + |
| 47 | + double avg = calculate_average_value(list); |
| 48 | + std::cout << "Average: " << avg << "\n"; |
| 49 | + } // safe context ends |
| 50 | + return 0; |
| 51 | +} |
| 52 | +``` |
| 53 | + |
| 54 | +--- |
| 55 | + |
| 56 | +## 2. Hardened Compiler Flags (CMakeLists.txt) |
| 57 | + |
| 58 | +Configure your project to build with runtime safety assertions enabled in GCC and Clang. Trapping out-of-bound errors reduces performance by less than 1% but prevents memory corruptions. |
| 59 | + |
| 60 | +```cmake |
| 61 | +cmake_minimum_required(VERSION 3.20) |
| 62 | +project(SpacecraftTelemetry CXX) |
| 63 | +
|
| 64 | +set(CMAKE_CXX_STANDARD 20) |
| 65 | +set(CMAKE_CXX_STANDARD_REQUIRED ON) |
| 66 | +
|
| 67 | +# Force warnings as errors |
| 68 | +add_compile_options(-Wall -Wextra -Wpedantic -Werror) |
| 69 | +
|
| 70 | +# Apply runtime hardening flags based on compiler type |
| 71 | +if(CMAKE_CXX_COMPILER_ID STREQUAL "Clang") |
| 72 | + add_compile_definitions( |
| 73 | + # Enable extensive LIBCPP hardening mode (traps out-of-bounds in std::vector, std::span) |
| 74 | + _LIBCPP_HARDENING_MODE=_LIBCPP_HARDENING_MODE_EXTENSIVE |
| 75 | + ) |
| 76 | + # Enable stack smashing protection and stack layout hardening |
| 77 | + add_compile_options(-fstack-protector-strong -fsanitize=safe-stack) |
| 78 | +elseif(CMAKE_CXX_COMPILER_ID STREQUAL "GNU") |
| 79 | + add_compile_definitions( |
| 80 | + # Enable bounds assertions in libstdc++ containers |
| 81 | + _GLIBCXX_ASSERTIONS |
| 82 | + # Enable source fortification to check string functions |
| 83 | + _FORTIFY_SOURCE=3 |
| 84 | + ) |
| 85 | + # Enable compiler-directed system hardening options |
| 86 | + add_compile_options(-fhardened -fstack-protector-strong -fcf-protection) |
| 87 | +endif() |
| 88 | +
|
| 89 | +add_executable(telemetry_node main.cpp telemetry_worker.cpp) |
| 90 | +``` |
| 91 | + |
| 92 | +--- |
| 93 | + |
| 94 | +## 3. Concurrency: Safe Thread Management via `std::jthread` |
| 95 | + |
| 96 | +Avoid raw `std::thread` to prevent crashes due to unjoined threads. Use C++20 `std::jthread` to automatically join upon scope exit and handle cooperative thread cancellation. |
| 97 | + |
| 98 | +```cpp |
| 99 | +#include <iostream> |
| 100 | +#include <vector> |
| 101 | +#include <thread> |
| 102 | +#include <mutex> |
| 103 | +#include <chrono> |
| 104 | +#include <atomic> |
| 105 | + |
| 106 | +class TelemetryWorker { |
| 107 | +private: |
| 108 | + std::mutex mtx_; |
| 109 | + std::vector<double> readings_; |
| 110 | + std::atomic<bool> status_active_{false}; |
| 111 | + std::jthread worker_thread_; |
| 112 | + |
| 113 | + // Thread internal loop task |
| 114 | + void run_loop(std::stop_token stop_token) { |
| 115 | + while (!stop_token.stop_requested()) { |
| 116 | + std::this_thread::sleep_for(std::chrono::milliseconds(100)); |
| 117 | + |
| 118 | + // Simulating sensor poll |
| 119 | + double mock_reading = 42.0; |
| 120 | + |
| 121 | + // Lock context safely using RAII guard |
| 122 | + { |
| 123 | + std::lock_guard<std::mutex> lock(mtx_); |
| 124 | + readings_.push_back(mock_reading); |
| 125 | + } |
| 126 | + } |
| 127 | + } |
| 128 | + |
| 129 | +public: |
| 130 | + TelemetryWorker() = default; |
| 131 | + |
| 132 | + // Non-copyable |
| 133 | + TelemetryWorker(const TelemetryWorker&) = delete; |
| 134 | + TelemetryWorker& operator=(const TelemetryWorker&) = delete; |
| 135 | + |
| 136 | + ~TelemetryWorker() { |
| 137 | + // jthread destructor automatically signals cancellation stop request and joins |
| 138 | + } |
| 139 | + |
| 140 | + void start() { |
| 141 | + status_active_.store(true); |
| 142 | + // jthread takes a function accepting a std::stop_token automatically |
| 143 | + worker_thread_ = std::jthread(&TelemetryWorker::run_loop, this); |
| 144 | + } |
| 145 | + |
| 146 | + void stop() { |
| 147 | + status_active_.store(false); |
| 148 | + // Request thread interruption cooperatively |
| 149 | + worker_thread_.request_stop(); |
| 150 | + } |
| 151 | + |
| 152 | + std::vector<double> get_readings() { |
| 153 | + std::lock_guard<std::mutex> lock(mtx_); |
| 154 | + return readings_; |
| 155 | + } |
| 156 | +}; |
| 157 | +``` |
| 158 | +
|
| 159 | +--- |
| 160 | +
|
| 161 | +## 4. Drop-In Memory Safety: Fil-C Compiler Setup |
| 162 | +
|
| 163 | +To run legacy C++ code safely, use the **Fil-C** compiler toolchain. Fil-C replaces raw pointers with capabilities (InvisiCaps) and implements a concurrent garbage collector to block all spatial and temporal bugs. |
| 164 | +
|
| 165 | +### Compilation commands |
| 166 | +```bash |
| 167 | +# Set Fil-C clang compiler paths |
| 168 | +export CC=/usr/local/fil-c/bin/clang |
| 169 | +export CXX=/usr/local/fil-c/bin/clang++ |
| 170 | +
|
| 171 | +# Build source code |
| 172 | +$CXX -O3 -std=c++20 main.cpp -o telemetry_node_safe |
| 173 | +
|
| 174 | +# Running the binary will automatically panic and abort on out-of-bounds access |
| 175 | +./telemetry_node_safe |
| 176 | +``` |
| 177 | + |
| 178 | +--- |
| 179 | + |
| 180 | +## 5. Testing: GoogleTest Assertions |
| 181 | + |
| 182 | +Test concurrent code and bounds assertions using GoogleTest. |
| 183 | + |
| 184 | +```cpp |
| 185 | +#include <gtest/gtest.h> |
| 186 | +#include "telemetry_worker.h" |
| 187 | + |
| 188 | +TEST(TelemetryWorkerTest, CaptureReadingsSuccessfully) { |
| 189 | + TelemetryWorker worker; |
| 190 | + |
| 191 | + worker.start(); |
| 192 | + std::this_thread::sleep_for(std::chrono::milliseconds(250)); |
| 193 | + worker.stop(); |
| 194 | + |
| 195 | + auto readings = worker.get_readings(); |
| 196 | + |
| 197 | + // Verify that data was appended by background jthread |
| 198 | + EXPECT_FALSE(readings.empty()); |
| 199 | + for (double val : readings) { |
| 200 | + EXPECT_DOUBLE_EQ(val, 42.0); |
| 201 | + } |
| 202 | +} |
| 203 | +``` |
| 204 | + |
| 205 | +--- |
| 206 | + |
| 207 | +## 6. Common Pitfalls & Troubleshooting |
| 208 | + |
| 209 | +| Pitfall | Symptom | Corrective Action | |
| 210 | +| :--- | :--- | :--- | |
| 211 | +| **Raw Pointer allocation** | Use-after-free, memory leaks | Use `std::make_unique` or `std::make_shared`. | |
| 212 | +| **Raw `std::thread` destruction** | `std::terminate()` aborts runtime | Replace thread with C++20 `std::jthread`. | |
| 213 | +| **Unprotected shared container** | Data races, memory corruptions | Synchronize accesses using `std::mutex` and `std::lock_guard`. | |
| 214 | +| **Out-of-bounds indexing** | Security exploits, silent bugs | Enable `-fhardened` / `_LIBCPP_HARDENING_MODE_EXTENSIVE`. | |
| 215 | +| **Recursive mutex locking** | Thread deadlocks | Redesign lock domains; avoid calling locked functions from within locks. | |
| 216 | + |
| 217 | +--- |
| 218 | + |
| 219 | +## 7. Code Review Compliance Gate |
| 220 | + |
| 221 | +Before merging C++ code, verify: |
| 222 | +1. No raw `new`/`delete` operators or manual pointer arithmetic exists in production files. |
| 223 | +2. Background threading utilizes `std::jthread` instead of raw `std::thread`. |
| 224 | +3. Mutex locks are managed exclusively using RAII class constructs (`std::lock_guard`). |
| 225 | +4. GCC/Clang extensive hardening flags are configured in CMakeLists.txt. |
| 226 | +5. Safe C++ blocks utilize `safe` keywords and `std2` library classes. |
| 227 | +6. Compilations pass cleanly without diagnostic warnings under `-Werror`. |
0 commit comments