# Build Guide

This repository has two parts:

- Fusion: Rust engine and HTTP API
- zztetris: static web client

## 1) Prerequisites (Linux)

Install these tools first:

- Rust (stable) with Cargo
- Git
- A static file server for local web testing (Python 3 is enough)

Optional (for PGO builds):

- Rust LLVM tools component

Install optional LLVM tools:

```bash
rustup component add llvm-tools
```

## 2) Build Fusion (Rust)

From repository root:

```bash
cd fusion
cargo build
```

Release build:

```bash
cargo build --release
```

Run all tests:

```bash
cargo test
```

### Build specific binaries

Build API server binary:

```bash
cargo build --release --bin engine_api
```

Build perft CLI:

```bash
cargo build --release --bin perft_cli
```

Build benchmark tool:

```bash
cargo build --release --bin bench_perft
```

### Run the API server

Default address is 127.0.0.1:8787:

```bash
cargo run --release --bin engine_api
```

Custom bind address:

```bash
ENGINE_API_ADDR=0.0.0.0:8787 cargo run --release --bin engine_api
```

Health check:

```bash
curl -s http://127.0.0.1:8787/health
```

For endpoint details, see:

- fusion/docs/engine_api.md
- fusion/docs/evaluation_parameter_reference.md

### Optional: PGO build workflow

A helper script is included:

```bash
./scripts/pgo-build.sh
```

D7 variant:

```bash
./scripts/pgo-build.sh --d7
```

## 3) Run zztetris (Web)

The zztetris folder is static HTML/CSS/JS. There is no npm build step required.

From repository root:

```bash
cd zztetris
python3 -m http.server 8080
```

Open in browser:

- http://127.0.0.1:8080/index.html

## 4) Run full stack locally

Use two terminals.

Terminal A (Fusion API):

```bash
cd fusion
cargo run --release --bin engine_api
```

Terminal B (zztetris):

```bash
cd zztetris
python3 -m http.server 8080
```

Then open zztetris and set API base to:

- http://127.0.0.1:8787

## 5) Troubleshooting

### Cargo not found

Make sure Rust is installed and your shell has Cargo in PATH.

### llvm-profdata not found during PGO

Install LLVM tools:

```bash
rustup component add llvm-tools
```

### Port already in use

Change one of the ports:

- API: set ENGINE_API_ADDR
- Web: use a different http.server port (for example 8081)