* Initial

docs/build-guide.md

@@ -0,0 +1,146 @@
+# Build Guide
+
+Detailed build instructions for ReviveSparc across different platforms and configurations.
+
+## Directory Structure
+
+```
+revivesparc/
+  emu/           -- Functional instruction-set simulator (C)
+  rtl/           -- Verilog RTL for synthesis
+  soft/          -- Firmware and boot ROM code
+  tests/         -- ISA verification test suite
+  tools/         -- Helper scripts and utilities
+  docs/          -- Additional documentation
+  Makefile       -- Top-level build file
+  CMakeLists.txt -- CMake build configuration
+```
+
+## Build System
+
+ReviveSparc supports two build systems: **Make** (simple) and **CMake** (advanced).
+
+### Make (Default)
+
+```bash
+make
+```
+
+### CMake
+
+```bash
+mkdir build && cd build
+cmake ..
+make -j$(nproc)
+```
+
+CMake offers more granular control:
+
+```bash
+cmake .. -DCMAKE_BUILD_TYPE=Debug -DENABLE_TRACE=ON
+```
+
+## Platform-Specific Notes
+
+### Linux (x86_64)
+
+Standard build with GCC:
+
+```bash
+sudo apt install build-essential cmake git
+git clone https://github.com/revivesparc/revivesparc.git
+cd revivesparc
+make
+```
+
+### Linux (aarch64)
+
+```bash
+sudo apt install build-essential cmake git
+make
+```
+
+No additional steps required.
+
+### macOS (Apple Silicon)
+
+Install dependencies via Homebrew:
+
+```bash
+brew install cmake make gcc
+make CC=gcc-14
+```
+
+### macOS (Intel)
+
+```bash
+brew install cmake make
+make
+```
+
+## Cross-Compilation
+
+To build for a different target architecture:
+
+```bash
+make CROSS=aarch64-linux-gnu-
+```
+
+This is useful for embedded ReviveSparc deployments.
+
+## Building the RTL
+
+The Verilog RTL requires Verilator or Icarus Verilog for simulation:
+
+```bash
+make rtl
+```
+
+For synthesis, see the [RTL Synthesis Guide](rtl-synthesis.md).
+
+## Building the Toolchain
+
+ReviveSparc includes scripts to build a complete SPARC cross-toolchain:
+
+```bash
+cd tools
+./build-toolchain.sh
+```
+
+This builds `sparc-elf-gcc`, `sparc-linux-gcc`, and associated binutils. The toolchain is installed to `tools/toolchain/`.
+
+## Common Build Issues
+
+### "No such file or directory" for standard headers
+
+Install libc development headers:
+
+```bash
+# Debian/Ubuntu
+sudo apt install libc6-dev
+
+# Fedora
+sudo dnf install glibc-devel
+
+# macOS
+# Headers are included with Xcode Command Line Tools
+```
+
+### "cc1: error: unrecognized command-line option"
+
+You may be using an older GCC. ReviveSparc requires GCC 8+ or Clang 10+.
+
+### "undefined reference to `clock_gettime'"
+
+Link with librt on older glibc versions:
+
+```bash
+make LDFLAGS=-lrt
+```
+
+## Cleaning the Build
+
+```bash
+make clean     # Remove build artifacts
+make distclean # Also remove generated files
+```