greg/NNG
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add Nix flake for local development without Docker/VSCode

Browse Source 
Provides flake.nix with nix run, nix develop, and nix build commands.
Automatically sets up lean4game platform and starts game server at
http://localhost:3000. See FLAKE_USAGE.md for complete documentation.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
Greg Shuflin
2025-11-11 02:07:34 -08:00
parent e55da341a6
commit ac9a60d137
5 changed files with 618 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

313
FLAKE_USAGE.md Normal file
View File

@@ -0,0 +1,313 @@
# 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)