Development & Building

Guide for developers working on the TraceForge codebase, building Go native helpers, running test suites, and compiling documentation.

---

1. Setting Up Development Environment

# 1. Clone repository
git clone https://github.com/paman7647/TraceForge.git
cd TraceForge

# 2. Set up Python virtual environment
python3 -m venv .venv
source .venv/bin/activate

# 3. Install in editable mode with development dependencies
pip install -e .
pip install -r docs/requirements.txt

---

2. Building the Go Native Fast-Path Helpers

TraceForge includes high-throughput Go utilities under go/:

# Compile traceforge-native into bin/
mkdir -p bin
cd go
go build -trimpath -ldflags="-s -w" -o ../bin/traceforge-native .
cd ..

---

3. Running Diagnostics & Validation

# Run environment and runtime diagnostics
traceforge doctor

# Audit catalog integrity and toolchain depth
traceforge tools audit --integration

# Validate shell syntax across all scripts
for script in setup.sh run.sh install_all.sh main.sh lib/*.sh modules/*.sh scripts/*.sh; do
  bash -n "$script"
done

---

4. Building Read the Docs Documentation Locally

To test and build the Sphinx documentation locally:

# Build HTML documentation
python3 -m sphinx -b html docs build/docs

# Open in browser
open build/docs/index.html   # macOS
xdg-open build/docs/index.html  # Linux