# 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://git.revivesparc.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
```