NNG/FLAKE_USAGE.md

# Nix Flake Usage for NNG4

This flake provides a complete development and runtime environment for the Lean4 Natural Number Game without requiring Docker or VSCode.

## Quick Start

The fastest way to get started:

```bash
nix run
```

This single command will:
1. Set up the lean4game platform in `.lean4game-nix/`
2. Install all npm dependencies
3. Build the Lean game (if needed)
4. Start the game server at `http://localhost:3000`

**First run takes 5-15 minutes** due to dependency downloads and Lean compilation. Subsequent runs are much faster.

## Available Commands

### `nix run` - Start the Game Server

Starts the complete game server with web interface:

```bash
nix run
```

The game will be available at: **http://localhost:3000/#/g/local/NNG4**

Press `Ctrl+C` to stop the server.

### `nix develop` - Development Shell

Enter a development environment with all tools available:

```bash
nix develop
```

This provides:
- `elan` - Lean toolchain manager
- `lake` - Lean build tool
- `node` and `npm` (Node.js 20)
- Helper scripts (see below)

### `nix build` - Build the Game

Build the Lean game and create a `./result` symlink:

```bash
nix build
```

The compiled game will be in `./result/`.

## Helper Scripts

When inside `nix develop`, additional commands are available:

### `setup-nng4-workspace`

Sets up the workspace for the first time:

```bash
setup-nng4-workspace
```

This script:
1. Copies lean4game to `.lean4game-nix/`
2. Installs npm dependencies
3. Updates Lake dependencies
4. Fetches mathlib cache (speeds up compilation significantly)
5. Builds the game with `lake build`

**Note:** Only needed if you want to manually set up before running the server.

### `run-nng4-server`

Starts the game server:

```bash
run-nng4-server
```

Same as `nix run` but from within the dev shell.

## Directory Structure

The flake sets up the following structure:

```
NNG4/                          # Your game repository
├── flake.nix                  # Nix flake configuration
├── flake.lock                 # Locked dependency versions
├── .lean4game-nix/            # lean4game platform (created by setup)
│   ├── client/                # React frontend
│   ├── relay/                 # Node.js relay server
│   ├── server/                # Lean GameServer
│   └── node_modules/          # npm dependencies
├── Game/                      # Your game source code
├── lakefile.lean              # Lake build configuration
└── lean-toolchain             # Lean version (v4.23.0)
```

## How It Works

The flake:

1. **Fetches lean4game** at the matching version (v4.23.0) from GitHub
2. **Creates a development shell** with:
   - Lean 4.23.0 via elan
   - Node.js 20
   - Build tools (git, curl, etc.)
3. **Sets up the workspace** by:
   - Copying lean4game to `.lean4game-nix/` (sibling structure)
   - Installing npm dependencies
   - Building your game with Lake
4. **Runs the server** with:
   - Environment variables for single-game mode
   - Relay server on port 8080
   - Vite dev server on port 3000
   - Lean server for proof verification

## Workflow Examples

### Daily Development

1. Make changes to your game code in `Game/`
2. Rebuild: `nix develop -c lake build`
3. Restart server: `nix run`
4. View changes at `http://localhost:3000/#/g/local/NNG4`

### Starting from Scratch

If you clone this repository fresh:

```bash
# One command does it all:
nix run

# Or step by step:
nix develop
setup-nng4-workspace
run-nng4-server
```

### Clean Rebuild

To force a complete rebuild:

```bash
nix develop
lake clean
lake build
run-nng4-server
```

### Remove Build Artifacts

```bash
# Remove the lean4game platform
rm -rf .lean4game-nix/

# Remove Lean build artifacts
lake clean

# Next nix run will rebuild everything
```

## Troubleshooting

### "npm install" takes forever

This is normal on first run. The lean4game platform has 1600+ npm packages. Subsequent runs reuse the installed packages.

### Mathlib builds are slow

On first build, run this to fetch prebuilt mathlib:

```bash
nix develop
lake exe cache get
lake build
```

### Port 3000 or 8080 already in use

Stop any other processes using these ports:

```bash
lsof -ti:3000 | xargs kill -9
lsof -ti:8080 | xargs kill -9
```

### Changes to game code not reflected

Rebuild the game:

```bash
nix develop -c lake build
```

Then reload the browser (hard refresh: `Ctrl+Shift+R`).

### "Git tree is dirty" warning

This is harmless. Nix warns when the git repository has uncommitted changes. The flake still works correctly.

## Technical Details

### Version Pinning

- **Lean:** 4.23.0 (from `lean-toolchain`)
- **lean4game:** v4.23.0 tag (from GitHub)
- **Node.js:** 20.x (matching Dockerfile)
- **npm packages:** Locked in lean4game's `package-lock.json`

### Why `.lean4game-nix/`?

The lean4game platform expects to be a sibling directory to your game. Since Nix works with immutable store paths, we copy it to a local directory that can be modified (for npm install, etc.).

### Differences from Docker Setup

**Docker approach:**
- Uses containers with Ubuntu base
- Requires Docker daemon
- Builds image with all dependencies
- Mounts volumes for development

**Nix approach:**
- Uses Nix store for dependencies
- No daemon needed
- Declarative, reproducible environment
- Direct file access, no volumes

Both produce the same result: a working game server at `http://localhost:3000`.

## Advanced Usage

### Update lean4game Version

To update lean4game to a newer version:

1. Edit `flake.nix`:
   ```nix
   lean4game = {
     url = "github:leanprover-community/lean4game/v4.XX.0";  # Change version
     flake = false;
   };
   ```

2. Update the lock file:
   ```bash
   nix flake update lean4game
   ```

3. Rebuild:
   ```bash
   rm -rf .lean4game-nix/
   nix run
   ```

### Use Local lean4game Clone

If you want to develop lean4game itself, you can point to a local clone:

1. Clone lean4game:
   ```bash
   cd ..
   git clone https://github.com/leanprover-community/lean4game.git
   ```

2. Edit `flake.nix`:
   ```nix
   lean4game = {
     url = "path:../lean4game";  # Local path
     flake = false;
   };
   ```

3. Rebuild:
   ```bash
   nix flake lock --update-input lean4game
   nix run
   ```

### Multi-System Support

The flake supports:
- `x86_64-linux` (tested)
- `aarch64-linux`
- `x86_64-darwin` (macOS Intel)
- `aarch64-darwin` (macOS Apple Silicon)

All platforms should work identically.

## Contributing

When contributing changes:

1. **Keep flake.nix in sync** with the Lean version in `lean-toolchain`
2. **Commit flake.lock** to ensure reproducible builds
3. **Test with** `nix flake check` before committing

## Resources

- [Nix Flakes Manual](https://nixos.org/manual/nix/stable/command-ref/new-cli/nix3-flake.html)
- [lean4game Documentation](https://github.com/leanprover-community/lean4game)
- [NNG4 README](./README.md)
- [Running Games Locally](https://github.com/leanprover-community/lean4game/blob/main/doc/running_locally.md)