Skip to content

Commit d5a60b1

Browse files
CopilotCopilot
authored
Add Copilot coding agent instructions for Fairy-Stockfish development (#897)
1 parent 8bcd3ac commit d5a60b1

2 files changed

Lines changed: 203 additions & 1 deletion

File tree

‎.github/copilot-instructions.md‎

Lines changed: 198 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,198 @@
1+
# Fairy-Stockfish Development Guide
2+
3+
## Repository Overview
4+
5+
**Fairy-Stockfish** is a chess variant engine derived from Stockfish, designed to support numerous chess variants and protocols. Written primarily in C++17, it includes Python and JavaScript bindings for library use.
6+
7+
**Repository Statistics:**
8+
- **Languages:** C++17 (primary), Python, JavaScript, Shell scripts
9+
- **Architecture:** Multi-protocol chess engine (UCI, UCCI, USI, XBoard/CECP)
10+
- **Target Platforms:** Windows, Linux, macOS, Android, WebAssembly
11+
- **Supported Variants:** 90+ chess variants including regional, historical, and modern variants
12+
13+
## Build System & Requirements
14+
15+
### Prerequisites
16+
- **Compiler:** GCC, Clang, or MSVC with C++17 support
17+
- **Build Tool:** GNU Make (required for C++ engine)
18+
- **Python:** 3.7+ (for Python bindings)
19+
- **Node.js:** (for JavaScript bindings)
20+
- **Additional Tools:** expect utility (for testing)
21+
22+
### Core Build Process
23+
24+
Note: Run engine and test commands from the `src/` directory unless specified otherwise.
25+
26+
#### Basic Build Commands
27+
```bash
28+
# Standard release build (recommended for most users)
29+
make -j2 ARCH=x86-64 build
30+
31+
# Debug build (for development)
32+
make -j2 ARCH=x86-64 debug=yes build
33+
34+
# Large board variants (supports boards up to 12x10)
35+
make -j2 ARCH=x86-64 largeboards=yes build
36+
37+
# All variants including ones with large branching factor
38+
make -j2 ARCH=x86-64 largeboards=yes all=yes build
39+
```
40+
41+
#### Architecture Options
42+
Common architectures (use `make help` for full list):
43+
- `x86-64-modern`: Modern 64-bit CPUs (recommended)
44+
- `x86-64-avx2`: CPUs with AVX2 support
45+
- `x86-64`: Generic 64-bit (portable but slower)
46+
- `armv8`: ARM64 CPUs
47+
- `apple-silicon`: Apple M1/M2 processors
48+
49+
#### Build Troubleshooting
50+
- **Compilation errors:** Ensure C++17 compiler (GCC 7+, Clang 5+)
51+
- **Linking errors on Linux:** Install `g++-multilib` for 32-bit builds
52+
53+
### Python Bindings (pyffish)
54+
```bash
55+
# Build Python bindings (from repository root)
56+
python3 setup.py install
57+
58+
# Alternative: Install from PyPI
59+
pip install pyffish
60+
```
61+
62+
### JavaScript Bindings (ffish.js)
63+
Also see the `tests/js/README.md`.
64+
```bash
65+
cd src/
66+
67+
# Build JavaScript bindings (requires emscripten)
68+
make -f Makefile_js build
69+
70+
# Alternative: Install from npm
71+
npm install ffish
72+
```
73+
74+
## Testing & Validation
75+
76+
All test commands below assume the current directory is `src/`.
77+
78+
### Core Engine Tests
79+
```bash
80+
# Basic functionality test
81+
./stockfish bench
82+
83+
# Variant-specific benchmarks
84+
./stockfish bench xiangqi
85+
./stockfish bench shogi
86+
./stockfish bench capablanca
87+
88+
# Validate variants configuration
89+
./stockfish check variants.ini
90+
```
91+
92+
### Comprehensive Test Suite
93+
```bash
94+
# Protocol compliance tests
95+
../tests/protocol.sh
96+
97+
# Move generation validation
98+
../tests/perft.sh all
99+
../tests/perft.sh chess # Chess only
100+
../tests/perft.sh largeboard # Large board variants only
101+
102+
# Regression testing
103+
../tests/regression.sh
104+
105+
# Reproducible search test
106+
../tests/reprosearch.sh
107+
108+
# Build signature verification
109+
../tests/signature.sh
110+
```
111+
112+
113+
## Project Architecture
114+
115+
### Directory Structure
116+
```
117+
├── src/ # Core C++ engine source
118+
│ ├── Makefile # Primary build configuration
119+
│ ├── main.cpp # Engine entry point
120+
│ ├── uci.cpp # UCI protocol implementation
121+
│ ├── xboard.cpp # XBoard protocol implementation
122+
│ ├── position.h # Position representation
123+
│ ├── position.cpp # Board logic
124+
│ ├── movegen.cpp # Move generation
125+
│ ├── search.cpp # Search algorithm
126+
│ ├── evaluate.cpp # Position evaluation
127+
│ ├── variant.h # Variant properties
128+
│ ├── variant.cpp # Variant definitions (built-in variants)
129+
│ ├── variants.ini # Variant definitions (runtime configurable variants)
130+
│ ├── nnue/ # Neural network evaluation
131+
│ ├── syzygy/ # Endgame tablebase support
132+
│ ├── pyffish.cpp # Python bindings
133+
│ └── ffishjs.cpp # JavaScript bindings
134+
├── tests/ # Test scripts and data
135+
│ ├── perft.sh # Move generation tests
136+
│ ├── protocol.sh # Protocol compliance tests
137+
│ ├── js/ # JavaScript binding tests
138+
│ └── pgn/ # Test game files
139+
├── .github/workflows/ # CI/CD configurations
140+
├── setup.py # Python package configuration
141+
└── README.md # Comprehensive documentation
142+
```
143+
144+
### Configuration Files
145+
- **`src/variants.ini`**: Defines examples for configuration of chess variants
146+
- **`setup.py`**: Python package build configuration
147+
- **`tests/js/package.json`**: JavaScript bindings configuration
148+
149+
### Key Source Files
150+
- **`src/variant.h`**: Variant rule properties
151+
- **`src/variant.cpp`**: Variant-specific game rules
152+
- **`src/variant.ini`**: Variant rule configuration examples and documentation of variant properties
153+
- **`src/position.h`**: Position representation
154+
- **`src/position.cpp`**: Board logic
155+
- **`src/movegen.cpp`**: Move generation logic
156+
- **`src/parser.cpp`**: Variant rule configuration parsing
157+
- **`src/piece.cpp`**: Piece type definitions and behavior
158+
159+
## Continuous Integration
160+
161+
### GitHub Actions Workflows
162+
- **`fairy.yml`**: Core engine testing (perft, protocols, variants)
163+
- **`stockfish.yml`**: Standard Stockfish compatibility tests
164+
- **`release.yml`**: Binary releases for multiple platforms
165+
- **`wheels.yml`**: Python package builds
166+
- **`ffishjs.yml`**: JavaScript binding builds
167+
168+
### Validation Pipeline
169+
1. **Code Standards:** C++17 compliance, `-Werror` warnings
170+
2. **Protocol Tests:** UCI, UCCI, USI, XBoard compatibility
171+
3. **Variant Tests:** Move generation verification for all variants
172+
4. **Performance Tests:** Benchmark consistency across builds
173+
5. **Multi-platform:** Linux, Windows, macOS builds
174+
175+
## Common Development Patterns
176+
177+
### Making Engine Changes
178+
1. **Always test basic functionality:** `./stockfish bench` after changes
179+
2. **Validate variant compatibility:** `./stockfish check variants.ini`
180+
3. **Run relevant tests:** `../tests/perft.sh all` for move generation changes
181+
182+
### Adding New Configurable Variants
183+
1. **Edit `src/variants.ini`**: Add variant configuration
184+
2. **Test parsing:** `./stockfish check variants.ini`
185+
186+
## Troubleshooting Guide
187+
188+
### Build Failures
189+
- **C++ version:** Requires C++17-compatible compiler
190+
- **32-bit builds:** May need `g++-multilib` package
191+
- **Linking errors:** Ensure pthread library availability
192+
193+
### Test Failures
194+
- **Perft mismatches:** Usually indicates move generation bugs
195+
- **Benchmark variations:** Expected 1-5% variance across builds
196+
- **Missing expect:** Install expect utility for test scripts
197+
198+
This documentation covers the essential information needed for effective development in Fairy-Stockfish.

‎.gitignore‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -24,7 +24,11 @@ ffish.js
2424
venv
2525
*.so
2626
pyffish.egg-info
27-
__pycache__/
27+
__pycache__
28+
*.pyc
29+
30+
# test artifacts
31+
tests/*.exp
2832

2933
# IDEs
3034
.vscode

0 commit comments

Comments
 (0)