@cubis/foundry 0.3.71 → 0.3.73

package/workflows/powers/c-pro/references/build-systems-and-toolchains.md

@@ -0,0 +1,148 @@
+# Build Systems and Toolchains
+
+## CMake Modern Practices
+
+```cmake
+# CMakeLists.txt — modern CMake (3.21+)
+cmake_minimum_required(VERSION 3.21)
+project(mylib VERSION 1.0.0 LANGUAGES C)
+
+# Set C standard project-wide
+set(CMAKE_C_STANDARD 23)
+set(CMAKE_C_STANDARD_REQUIRED ON)
+set(CMAKE_C_EXTENSIONS OFF)  # disable GNU extensions for portability
+
+# Library target
+add_library(mylib
+    src/core.c
+    src/parser.c
+    src/util.c
+)
+
+target_include_directories(mylib
+    PUBLIC  $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/include>
+    PRIVATE src/
+)
+
+# Compiler warnings as errors
+target_compile_options(mylib PRIVATE
+    $<$<C_COMPILER_ID:GNU,Clang>:-Wall -Wextra -Wpedantic -Werror>
+    $<$<C_COMPILER_ID:MSVC>:/W4 /WX>
+)
+
+# Sanitizers for debug builds
+if(CMAKE_BUILD_TYPE STREQUAL "Debug")
+    target_compile_options(mylib PRIVATE -fsanitize=address,undefined -fno-omit-frame-pointer)
+    target_link_options(mylib PRIVATE -fsanitize=address,undefined)
+endif()
+
+# Tests
+enable_testing()
+add_executable(test_core tests/test_core.c)
+target_link_libraries(test_core PRIVATE mylib)
+add_test(NAME test_core COMMAND test_core)
+
+# Install rules
+install(TARGETS mylib EXPORT mylibTargets)
+install(DIRECTORY include/ DESTINATION include)
+```
+
+## Meson Build System
+
+```meson
+# meson.build — lightweight alternative to CMake
+project('mylib', 'c',
+    version: '1.0.0',
+    default_options: ['c_std=c23', 'warning_level=3', 'werror=true']
+)
+
+src = files('src/core.c', 'src/parser.c', 'src/util.c')
+inc = include_directories('include')
+
+mylib = library('mylib', src, include_directories: inc)
+mylib_dep = declare_dependency(link_with: mylib, include_directories: inc)
+
+# Tests
+test_core = executable('test_core', 'tests/test_core.c', dependencies: mylib_dep)
+test('core', test_core)
+```
+
+## Cross-Compilation
+
+```cmake
+# toolchain-arm.cmake — cross-compile for ARM
+set(CMAKE_SYSTEM_NAME Linux)
+set(CMAKE_SYSTEM_PROCESSOR arm)
+
+set(CMAKE_C_COMPILER arm-linux-gnueabihf-gcc)
+set(CMAKE_CXX_COMPILER arm-linux-gnueabihf-g++)
+
+set(CMAKE_FIND_ROOT_PATH /usr/arm-linux-gnueabihf)
+set(CMAKE_FIND_ROOT_PATH_MODE_PROGRAM NEVER)
+set(CMAKE_FIND_ROOT_PATH_MODE_LIBRARY ONLY)
+set(CMAKE_FIND_ROOT_PATH_MODE_INCLUDE ONLY)
+```
+
+```bash
+# Build with cross-compilation toolchain
+cmake -B build-arm -DCMAKE_TOOLCHAIN_FILE=toolchain-arm.cmake
+cmake --build build-arm
+```
+
+## CI Matrix Configuration
+
+```yaml
+# GitHub Actions — multi-compiler, multi-platform
+jobs:
+  build:
+    strategy:
+      matrix:
+        os: [ubuntu-latest, macos-latest]
+        compiler: [gcc-13, clang-17]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v4
+      - name: Configure
+        run: |
+          cmake -B build \
+            -DCMAKE_C_COMPILER=${{ matrix.compiler }} \
+            -DCMAKE_BUILD_TYPE=Debug
+      - name: Build
+        run: cmake --build build
+      - name: Test
+        run: ctest --test-dir build --output-on-failure
+      - name: Sanitizer build
+        run: |
+          cmake -B build-san \
+            -DCMAKE_C_COMPILER=${{ matrix.compiler }} \
+            -DCMAKE_BUILD_TYPE=Debug \
+            -DENABLE_SANITIZERS=ON
+          cmake --build build-san
+          ctest --test-dir build-san
+```
+
+## Dependency Management
+
+```cmake
+# FetchContent for pinned dependencies
+include(FetchContent)
+
+FetchContent_Declare(cjson
+    GIT_REPOSITORY https://github.com/DaveGamble/cJSON.git
+    GIT_TAG        v1.7.17  # pin exact version
+)
+FetchContent_MakeAvailable(cjson)
+target_link_libraries(mylib PRIVATE cjson)
+
+# vcpkg for larger dependency sets
+# Install: cmake -B build -DCMAKE_TOOLCHAIN_FILE=$VCPKG_ROOT/scripts/buildsystems/vcpkg.cmake
+```
+
+## Reproducible Builds Checklist
+
+1. Pin compiler version in CI (e.g., `gcc-13`, not `gcc`).
+2. Pin all external dependencies to exact versions or commit hashes.
+3. Use deterministic build flags (`-frandom-seed=`, `-ffile-prefix-map=`).
+4. Commit `CMakePresets.json` or equivalent for consistent local/CI builds.
+5. Disable compiler plugins and extensions that vary by environment.
+6. Verify with two independent builds and `diffoscope` or binary hash comparison.

package/workflows/powers/c-pro/references/common-ub-and-portability.md

@@ -0,0 +1,166 @@
+# Common Undefined Behavior and Portability
+
+## Undefined Behavior Catalog
+
+These are the most common sources of UB in C code. Sanitizers catch many at runtime, but prevention through coding discipline is the primary defense.
+
+### Signed Integer Overflow
+
+```c
+// UB — signed overflow is undefined in C
+int x = INT_MAX;
+x += 1; // UB: compiler may assume this never happens and optimize accordingly
+
+// SAFE — check before arithmetic
+if (x <= INT_MAX - 1) {
+    x += 1;
+}
+
+// SAFE — use unsigned for wrapping arithmetic
+unsigned int y = UINT_MAX;
+y += 1; // defined: wraps to 0
+```
+
+### Null Pointer Dereference
+
+```c
+// UB — dereferencing NULL
+int *p = NULL;
+int val = *p; // UB
+
+// SAFE — check before dereference
+if (p != NULL) {
+    int val = *p;
+}
+
+// Gotcha: compiler may remove NULL checks after dereference
+int val = *p;        // if this executes, compiler assumes p != NULL
+if (p == NULL) { ... } // compiler may optimize this away as "unreachable"
+```
+
+### Buffer Overflow and Out-of-Bounds Access
+
+```c
+// UB — reading/writing past allocation
+int arr[10];
+arr[10] = 42; // UB: index 10 is one past the end
+
+// UB — string function overflow
+char buf[8];
+strcpy(buf, "this string is too long"); // UB: writes past buf
+
+// SAFE — use bounded functions
+char buf[8];
+strncpy(buf, source, sizeof(buf) - 1);
+buf[sizeof(buf) - 1] = '\0'; // ensure null termination
+
+// Better: use snprintf for formatted strings
+snprintf(buf, sizeof(buf), "%s", source);
+```
+
+### Use After Free and Double Free
+
+```c
+// UB — use after free
+char *data = malloc(100);
+free(data);
+data[0] = 'x'; // UB: data is freed
+
+// UB — double free
+free(data);
+free(data); // UB: second free on already-freed pointer
+
+// SAFE — NULL after free
+free(data);
+data = NULL; // prevents use-after-free (dereference NULL → crash, not silent corruption)
+```
+
+### Strict Aliasing Violations
+
+```c
+// UB — accessing memory through incompatible pointer type
+float f = 3.14f;
+int *ip = (int *)&f;
+int bits = *ip; // UB: strict aliasing violation
+
+// SAFE — use memcpy for type punning
+float f = 3.14f;
+int bits;
+memcpy(&bits, &f, sizeof(bits)); // defined behavior
+
+// SAFE — union-based type punning (C99+, implementation-defined but widely supported)
+union { float f; int i; } u;
+u.f = 3.14f;
+int bits = u.i;
+```
+
+### Uninitialized Variable Reads
+
+```c
+// UB — reading uninitialized automatic variable
+int x;
+printf("%d\n", x); // UB: x has indeterminate value
+
+// SAFE — always initialize
+int x = 0;
+```
+
+## Implementation-Defined Behavior Traps
+
+These are defined by the compiler/platform but differ across implementations:
+
+| Behavior                      | Varies by           | Recommendation                                                    |
+| ----------------------------- | ------------------- | ----------------------------------------------------------------- |
+| `sizeof(int)`                 | Platform            | Use fixed-width types (`int32_t`, `uint64_t`) for data structures |
+| Bit-shift of negative values  | Compiler            | Avoid shifting signed integers; use unsigned                      |
+| Struct padding and alignment  | Compiler + platform | Use `offsetof`, `_Alignof`; pack with attributes only when needed |
+| Char signedness (`char`)      | Compiler            | Use `signed char` or `unsigned char` explicitly for arithmetic    |
+| Evaluation order of arguments | Compiler            | Avoid side effects in function argument expressions               |
+
+## Cross-Platform Portability
+
+```c
+// Use fixed-width integers for portable data structures
+#include <stdint.h>
+
+typedef struct {
+    uint32_t id;
+    int64_t timestamp;
+    uint16_t flags;
+} __attribute__((packed)) WireMessage; // packed for network protocol
+
+// Endianness-safe serialization
+#include <arpa/inet.h> // or use manual byte swapping
+
+void serialize(const WireMessage *msg, uint8_t *buf) {
+    uint32_t id_be = htonl(msg->id);
+    memcpy(buf, &id_be, sizeof(id_be));
+    // ... continue for other fields
+}
+
+// Feature detection with preprocessor
+#if defined(__linux__)
+    #include <sys/epoll.h>
+#elif defined(__APPLE__)
+    #include <sys/event.h>
+#elif defined(_WIN32)
+    #include <winsock2.h>
+#endif
+```
+
+## Compiler Warning Flags for UB Detection
+
+```bash
+# GCC — maximum diagnostic coverage
+gcc -Wall -Wextra -Wpedantic -Werror \
+    -Wformat=2 -Wformat-overflow -Wformat-truncation \
+    -Wconversion -Wsign-conversion \
+    -Wshadow -Wdouble-promotion \
+    -Wnull-dereference -Wuninitialized \
+    -Wstrict-aliasing=2 \
+    -fstack-protector-strong
+
+# Clang — additional checks
+clang -Weverything -Wno-padded -Wno-disabled-macro-expansion \
+      -fsanitize=undefined,address
+```

package/workflows/powers/c-pro/references/debugging-with-sanitizers.md

@@ -0,0 +1,205 @@
+# Debugging with Sanitizers
+
+## AddressSanitizer (ASan)
+
+Detects: buffer overflow, use-after-free, use-after-return, double-free, memory leaks.
+
+```bash
+# Compile with ASan
+gcc -fsanitize=address -fno-omit-frame-pointer -g -O1 -o myapp myapp.c
+clang -fsanitize=address -fno-omit-frame-pointer -g -O1 -o myapp myapp.c
+
+# Run — crashes with detailed report on first error
+./myapp
+# Output shows: error type, stack trace, shadow memory state
+```
+
+```c
+// ASan catches this at runtime
+void trigger_heap_overflow(void) {
+    int *arr = malloc(10 * sizeof(int));
+    arr[10] = 42; // heap-buffer-overflow detected
+    free(arr);
+}
+
+// ASan catches use-after-free
+void trigger_uaf(void) {
+    int *p = malloc(sizeof(int));
+    free(p);
+    *p = 42; // heap-use-after-free detected
+}
+```
+
+### ASan Options
+
+```bash
+# Environment variable to control ASan behavior
+export ASAN_OPTIONS="detect_leaks=1:halt_on_error=0:print_stats=1"
+
+# detect_leaks=1    — also report memory leaks at exit
+# halt_on_error=0   — continue after first error (find multiple issues)
+# print_stats=1     — show memory allocation statistics
+# suppressions=file — suppress known false positives
+```
+
+## UndefinedBehaviorSanitizer (UBSan)
+
+Detects: signed integer overflow, null pointer dereference, misaligned access, shift overflow, division by zero.
+
+```bash
+# Compile with UBSan
+gcc -fsanitize=undefined -fno-omit-frame-pointer -g -o myapp myapp.c
+
+# Common sub-sanitizers (can be selected individually)
+gcc -fsanitize=signed-integer-overflow,null,alignment,shift -g -o myapp myapp.c
+```
+
+```c
+// UBSan detects signed overflow
+int overflow(void) {
+    int x = INT_MAX;
+    return x + 1; // runtime error: signed integer overflow
+}
+
+// UBSan detects misaligned access
+void misaligned(void) {
+    char buf[8] = {0};
+    int *p = (int *)(buf + 1); // misaligned pointer
+    *p = 42; // runtime error: misaligned access
+}
+```
+
+## ThreadSanitizer (TSan)
+
+Detects: data races, lock-order violations, deadlocks.
+
+```bash
+# Compile with TSan (cannot combine with ASan)
+gcc -fsanitize=thread -fno-omit-frame-pointer -g -o myapp myapp.c -lpthread
+```
+
+```c
+// TSan detects this data race
+static int counter = 0;
+
+void *increment(void *arg) {
+    (void)arg;
+    for (int i = 0; i < 1000; i++) {
+        counter++; // data race: unsynchronized access
+    }
+    return NULL;
+}
+
+// Fix: use mutex or atomic
+#include <stdatomic.h>
+static atomic_int counter = 0;
+
+void *increment_safe(void *arg) {
+    (void)arg;
+    for (int i = 0; i < 1000; i++) {
+        atomic_fetch_add(&counter, 1); // no race
+    }
+    return NULL;
+}
+```
+
+## MemorySanitizer (MSan) — Clang Only
+
+Detects: reads of uninitialized memory.
+
+```bash
+# Clang-only (not available in GCC)
+clang -fsanitize=memory -fno-omit-frame-pointer -g -O1 -o myapp myapp.c
+
+# All linked libraries must also be compiled with MSan
+# Use with libc++ compiled with MSan for best results
+```
+
+## GDB / LLDB Debugging Workflow
+
+```bash
+# Compile for debugging
+gcc -g -O0 -o myapp myapp.c
+
+# GDB basics
+gdb ./myapp
+(gdb) break main            # set breakpoint
+(gdb) run                   # start execution
+(gdb) next                  # step over
+(gdb) step                  # step into
+(gdb) print variable        # inspect variable
+(gdb) backtrace             # show call stack
+(gdb) watch *ptr            # break when memory changes
+(gdb) info threads          # list threads
+(gdb) thread 2              # switch to thread 2
+
+# LLDB equivalents
+lldb ./myapp
+(lldb) breakpoint set -n main
+(lldb) run
+(lldb) thread step-over
+(lldb) thread step-in
+(lldb) frame variable
+(lldb) thread backtrace
+(lldb) watchpoint set variable counter
+```
+
+## Core Dump Analysis
+
+```bash
+# Enable core dumps
+ulimit -c unlimited
+
+# Set core dump pattern (Linux)
+echo "/tmp/core.%e.%p" | sudo tee /proc/sys/kernel/core_pattern
+
+# Analyze core dump
+gdb ./myapp /tmp/core.myapp.12345
+(gdb) backtrace          # see where it crashed
+(gdb) frame 3            # examine specific frame
+(gdb) info locals        # see local variables
+```
+
+## Valgrind (Alternative to ASan)
+
+```bash
+# Memory error detection
+valgrind --tool=memcheck --leak-check=full --show-leak-kinds=all ./myapp
+
+# Cache profiling
+valgrind --tool=cachegrind ./myapp
+cg_annotate cachegrind.out.<pid>
+
+# Call graph profiling
+valgrind --tool=callgrind ./myapp
+kcachegrind callgrind.out.<pid>
+```
+
+## Sanitizer Compatibility Matrix
+
+| Sanitizer        | GCC | Clang | Combinable with         |
+| ---------------- | --- | ----- | ----------------------- |
+| AddressSanitizer | Yes | Yes   | UBSan                   |
+| UBSan            | Yes | Yes   | ASan, MSan, TSan        |
+| ThreadSanitizer  | Yes | Yes   | UBSan                   |
+| MemorySanitizer  | No  | Yes   | UBSan                   |
+| LeakSanitizer    | Yes | Yes   | ASan (often integrated) |
+
+Cannot combine: ASan + TSan, ASan + MSan, TSan + MSan.
+
+## CI Integration
+
+```bash
+# Run multiple sanitizer builds in CI
+# Build 1: ASan + UBSan
+cmake -B build-asan -DCMAKE_C_FLAGS="-fsanitize=address,undefined -g -O1"
+cmake --build build-asan && ctest --test-dir build-asan
+
+# Build 2: TSan (separate because incompatible with ASan)
+cmake -B build-tsan -DCMAKE_C_FLAGS="-fsanitize=thread -g -O1"
+cmake --build build-tsan && ctest --test-dir build-tsan
+
+# Build 3: Regular optimized build (for performance tests)
+cmake -B build-release -DCMAKE_BUILD_TYPE=Release
+cmake --build build-release && ctest --test-dir build-release
+```

package/workflows/powers/c-pro/references/memory-safety-and-build-checklist.md

@@ -0,0 +1,60 @@
+# Memory Safety and Build Checklist
+
+## Ownership rules
+
+- Every heap allocation has exactly one owner. Document who allocates and who frees.
+- Functions that return allocated memory must document whether the caller owns the result.
+- Functions that receive pointers must document whether they borrow or take ownership.
+- Use naming conventions to signal ownership: `create_*` allocates (caller frees), `get_*` borrows (caller must not free).
+
+## Buffer safety
+
+- Always pass buffer size alongside buffer pointer. Never rely on null terminators for binary data.
+- Check return values of `snprintf`, `read`, `recv` — they may write fewer bytes than requested.
+- Use `sizeof(array)` only on stack-allocated arrays, never on decayed pointers.
+- Prefer bounded variants: `strnlen` over `strlen`, `snprintf` over `sprintf`, `strncpy` with explicit termination.
+
+## Initialization
+
+- Initialize all stack variables at declaration. Uninitialized reads are undefined behavior.
+- Zero-initialize structs with `= {0}` or `memset` before populating fields.
+- Use compound literals `(struct Foo){.field = val}` for partial initialization — remaining fields are zero.
+
+## Arena allocator pattern
+
+```c
+// Simple arena: bump allocator with single free at scope end
+typedef struct { char *base; size_t offset; size_t capacity; } Arena;
+void *arena_alloc(Arena *a, size_t size);  // bump offset, return pointer
+void arena_reset(Arena *a);                // reset offset to 0
+```
+
+- Allocate arena at scope entry, reset or free at scope exit. No per-object free needed.
+- Useful for request-scoped or frame-scoped allocations (servers, games, parsers).
+
+## Sanitizer configuration
+
+| Sanitizer                  | Flag                             | Catches                                                       |
+| -------------------------- | -------------------------------- | ------------------------------------------------------------- |
+| AddressSanitizer           | `-fsanitize=address`             | Use-after-free, buffer overflow, stack overflow, memory leaks |
+| UndefinedBehaviorSanitizer | `-fsanitize=undefined`           | Signed overflow, null deref, alignment, shift out of range    |
+| ThreadSanitizer            | `-fsanitize=thread`              | Data races, lock order violations                             |
+| MemorySanitizer            | `-fsanitize=memory` (Clang only) | Reads of uninitialized memory                                 |
+
+- Run ASAN + UBSAN together in CI debug builds. TSAN requires a separate build (incompatible with ASAN).
+- Set `ASAN_OPTIONS=detect_leaks=1:halt_on_error=1` for strict leak detection.
+
+## Build system hygiene
+
+- Pin compiler version in CI (e.g., `gcc-13`, `clang-17`). Document minimum required version.
+- Use `-Wall -Wextra -Werror -Wpedantic -Wconversion -Wshadow` for maximum diagnostic coverage.
+- Run builds on at least GCC + Clang. They catch different issues.
+- Use `compile_commands.json` (CMake: `-DCMAKE_EXPORT_COMPILE_COMMANDS=ON`) for IDE and static analyzer integration.
+- Enable LTO (`-flto`) for release builds. Verify with tests — LTO can expose bugs that per-TU compilation hides.
+
+## ABI boundary review
+
+- Export only the minimum necessary symbols. Use `__attribute__((visibility("default")))` or export maps.
+- Keep struct layouts stable across versions. Add fields at the end, never reorder.
+- Use opaque pointers (`typedef struct Foo Foo;`) for types whose layout callers should not depend on.
+- Version-check shared libraries at load time when ABI stability is critical.