feat: (WIP) CPU isolation, cmake 4 check, shellcheck, makefile changes, housekeeping

Author: milsanore

.env.example

@@ -10,3 +10,6 @@ SYMBOLS=BTCUSDT,
 # CPU PINNING
 PX_SESSION_CPU=0
 TX_SESSION_CPU=1
+# CPU ISOLATION
+CPU_SET_NAME=tradercpp
+CPU_SET_RANGE="0-1"

.github/workflows/reusable_build.yml

@@ -26,6 +26,9 @@ jobs:
       - name: clang-format
         run: hooks/check_clang_format.sh
 
+      - name: shellcheck
+        run: hooks/check_shell.sh
+
       - name: Restore Conan cache
         uses: actions/cache@v4
         with:

CMakeLists.txt

@@ -1,4 +1,4 @@
-cmake_minimum_required(VERSION 3.16)
+cmake_minimum_required(VERSION 4.0)
 project(tradercpp)
 
 set(CMAKE_CXX_STANDARD 23)

Dockerfile_build

@@ -115,5 +115,6 @@ RUN apt update && apt install -y --no-install-recommends \
     make \
     ninja-build \
     perl \
+    shellcheck \
     unzip \
     && rm -rf /var/lib/apt/lists/*

Makefile

@@ -1,10 +1,11 @@
 #!make
 SHELL:=/bin/bash
 
-#################################################
-# A set of basic execution recipes (all PHONY).
-# Call `make` on the command line for documentation.
-#################################################
+# ###############################################
+# A set of execution recipes (all PHONY).
+# In essence, a programmatic entrypoint into the app.
+# Run `make` for help.
+# ###############################################
 
 # pp - pretty print function
 yellow := $(shell tput setaf 3)
@@ -18,33 +19,41 @@ help: Makefile
 	@echo " Choose a command to run:"
 	@sed -n 's/^##//p' $< | column -t -s ':' | sed -e 's/^/ /'
 
-## withenv: 😭 run `make` with envars from `.env`. like so `make withenv RECIPE=init`
+## withenv: 😭 execute `make` with environment variables defined in `.env`. like so > `make withenv RECIPE=init`
 .PHONY: withenv
 withenv:
 	test -e .env || cp .env.example .env
 	bash -c 'set -o allexport; source .env; set +o allexport; make "$$RECIPE"'
 
-## init: 🏌️ initialize the project, fetch dependencies
+# TODO: replace ☝️ with `set -a; . .env; set +a;`
+
+## init: 🏌️ initialize the project
 .PHONY: init
 init:
+	$(call pp,initializing project)
+	git config core.hooksPath hooks
 	rm -rf build && mkdir build
 	python3 -m venv .venv
 	source .venv/bin/activate && \
 		pip install gcovr conan && \
 		conan install . --lockfile=conan.lock --build=missing -s build_type=Debug && \
 		conan install . --lockfile=conan.lock --build=missing -s build_type=Release
+	cmake --preset=release
 	cmake --preset=debug
+	$(MAKE) restore-cpus
 
-## lock-conan: 📦 run after adding (but before installing) conan dependencies
-.PHONY: lock-conan
-lock-conan:
-	conan lock create . --profile:host=default -s build_type=Debug   --lockfile-out=conan.lock
-	conan lock create . --profile:host=default -s build_type=Release --lockfile=conan.lock --lockfile-out=conan.lock
+## lock: 📦 update Conan dependency lock file. (NB run after adding conan dependencies to conanfile.txt, but before installing)
+.PHONY: lock
+lock:
+	$(call pp,updating conan lock file to match contents of conanfile.txt)
+	source .venv/bin/activate && \
+		conan lock create . --profile:host=default -s build_type=Debug   --lockfile-out=conan.lock && \
+		conan lock create . --profile:host=default -s build_type=Release --lockfile=conan.lock --lockfile-out=conan.lock
 
 ## build-debug: 🔨 compile (debug)
 .PHONY: build-debug
 build-debug:
-	$(call pp,assuming `make init` has been called)
+	$(call pp,NB assuming `make init` has been called)
 	cmake --preset=debug
 	cmake --build --preset=debug
 
@@ -68,7 +77,6 @@ test:
 ## bench: ⏱️ build and run benchmarks
 .PHONY: bench
 bench:
-	$(call pp,assuming `make build-release` has been called)
 	cmake --build --preset release
 	build/Release/benchmarks/benchmarks \
 	--benchmark_out=bench_results.json \
@@ -80,18 +88,26 @@ bench:
 tidy:
 	find src/ tests/ benchmarks/ \( -name '*.cpp' -o -name '*.hpp' -o -name '*.c' -o -name '*.h' \) -exec clang-format -i {} +	
 	hooks/check_clang_tidy.sh
+	hooks/check_shell.sh
 
-## run-debug: 🏃‍♂️  run the app (debug) (don't forget `withenv`)
+## run-debug: 🏃‍♂️ run the app (debug) (don't forget `withenv`)
 .PHONY: run-debug
 run-debug:
 	ASAN_OPTIONS=detect_leaks=1:leak_check_at_exit=1:fast_unwind_on_malloc=0 \
 	build/Debug/tradercpp
 
-## run-release: 🏎️  run the app (prod)
+## run-release: 🏎️ run the app (prod)
 .PHONY: run-release
 run-release:
-	$(call pp,starting app. dont forget to run `scripts/cpu_shield_start.sh` and `scripts/irqs_move.sh`)
-	build/Release/tradercpp
+# 	set -a; . .env; set +a; sudo -E scripts/pin_irqs.sh
+	set -a; . .env; set +a; sudo -E scripts/pin_cpus.sh build/Release/tradercpp
+
+## restore-cpus: 🖥️ hand back pinned CPUs and IRQs to the operating system. (NB app must not be running) 
+.PHONY: restore-cpus
+restore-cpus:
+	$(call pp,handing CPU and IRQ management back to the kernel. NB: app must not be running`)
+	set -a; . .env; set +a; sudo -E scripts/unpin_cpus.sh
+	set -a; . .env; set +a; sudo -E scripts/unpin_irqs.sh
 
 # CONTAINERISATION RECIPES ----------------------------------------------------
 

hooks/check_shell.sh

@@ -0,0 +1,17 @@
+#!/usr/bin/env bash
+
+################################################################
+# check_clang_tidy.sh
+# checks for any lint warnings and errors out.
+# does not modify files in-place.
+# uses run-clang-tidy for parallel execution.
+################################################################
+
+set -euo pipefail
+
+echo ">> Running shellcheck on all scripts"
+
+while IFS= read -r file; do
+    shellcheck "$file"
+# find files that start with a sh/bash shebang, exclude build/ and .git/hooks folders
+done < <(find . \( -type d -name build -o -path './.git/hooks' \) -prune -o -type f -exec grep -Iq '^#!.*sh' {} \; -print)

scripts/cpu_shield_start.sh

@@ -0,0 +1,72 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# ----------------------------------------------------------
+# CPU isolation launcher for Linux (cgroup v1 & v2)
+#
+# How it works:
+# 1. Root required: The script checks for root because writing to /sys/fs/cgroup requires privileges.
+# 2. Validation: Ensures CPU_SET_NAME and CPU_SET_RANGE exist.
+# 3. Cgroup detection: Automatically handles v1 and v2.
+# 4. CPU and memory configuration: Writes cpuset.cpus and cpuset.mems.
+# 5. Associating the application:
+#   - $$ is the PID of the script itself.
+#   - When we exec "$@", the application replaces the script and inherits the cgroup.
+#   - This is the standard way to bind the app to the cpuset.
+# ----------------------------------------------------------
+
+# Validate environment variables
+: "${CPU_SET_NAME:?Environment variable CPU_SET_NAME is required}"
+: "${CPU_SET_RANGE:?Environment variable CPU_SET_RANGE is required}"
+echo "CPU isolation launcher starting..."
+echo "CPU_SET_NAME = $CPU_SET_NAME"
+echo "CPU_SET_RANGE = $CPU_SET_RANGE"
+
+# Check for root privileges
+if [[ $EUID -ne 0 ]]; then
+    echo "WARNING: root privileges are required for true CPU isolation."
+    echo "Proceeding without isolation..."
+    exec "$@"
+fi
+
+# Detect cgroup version
+if [[ -f /sys/fs/cgroup/cgroup.controllers ]]; then
+    CGROUP_VERSION=2
+    BASE_CGROUP="/sys/fs/cgroup"
+else
+    CGROUP_VERSION=1
+    BASE_CGROUP="/sys/fs/cgroup/cpuset"
+fi
+echo "Detected cgroup version: $CGROUP_VERSION"
+
+GROUP_PATH="$BASE_CGROUP/$CPU_SET_NAME"
+
+# Create cpuset directory if it doesn't exist
+if [[ ! -d "$GROUP_PATH" ]]; then
+    mkdir -p "$GROUP_PATH"
+    echo "Created cpuset directory: $GROUP_PATH"
+fi
+
+# Write CPUs
+CPU_FILE="$GROUP_PATH/cpuset.cpus"
+echo "$CPU_SET_RANGE" > "$CPU_FILE"
+echo "Wrote CPUs to $CPU_FILE"
+
+# Write memory nodes (required for cpuset)
+MEM_FILE="$GROUP_PATH/cpuset.mems"
+if [[ ! -f "$MEM_FILE" ]]; then
+    # assume NUMA node 0
+    echo "0" > "$MEM_FILE"
+fi
+echo "Set memory nodes in $MEM_FILE"
+
+# TODO(MILS): WARN ABOUT MULTI-NUMA CPU RANGES AND REFUSE TO CONTINUE
+
+# Add current process to the cpuset
+# - $$ is the PID of the script itself.
+# - When we exec "$@", the application replaces the script and inherits the cgroup.
+PROCS_FILE="$GROUP_PATH/cgroup.procs"
+echo "$$" > "$PROCS_FILE"
+echo "Added PID $$ to $PROCS_FILE"
+echo "Launching application in isolated cpuset..."
+exec "$@"

scripts/cpu_shield_stop.sh

@@ -4,6 +4,15 @@
 # ------------------------------------------------------------
 
 set -euo pipefail
+
+# Check for root
+if [ "$EUID" -ne 0 ]; then
+    echo "This script must be run as root."
+    echo "Try: sudo $0"
+    exit 1
+fi
+
+# Handle filenames with whitespace
 IFS=$'\n\t'
 
 # List of NIC interfaces to protect (keep IRQs on isolated cores)