Stockfish Docs

Appearance

This guide is for contributors to the fishtest codebase (server and worker). For submitting Stockfish patches see [[Creating my first test]]. For production deployment see [[Fishtest server setup]].

The fishtest worker must support multiple OSes, Python versions (>= 3.8), and C++ compilers (GCC, Clang). Test your changes locally before opening a PR.

Development Environment Setup ​

Python ​

  • pyenv: simple Python version management for Linux/WSL
  • fishtest server: Python >= 3.14
  • fishtest worker: Python >= 3.8

Install uv and sync the project:

bash
mkdir -p $HOME/.local/bin
curl -LsSf https://astral.sh/uv/install.sh | sh
. $HOME/.profile
cd $HOME/fishtest
uv sync

CSS, HTML, JavaScript ​

MongoDB ​

The server requires MongoDB. Install MongoDB Community Edition for your platform.

C++ compilers ​

The worker compiles Stockfish and fastchess locally, so you need GCC and/or Clang to test worker changes.

Install several GCC versions on Ubuntu ​

Launch the following script to have several versions of GCC on Ubuntu alongside the default one, manage the different GCC versions using update-alternatives. This works also for Windows Subsystem for Linux.

Click to view
bash
#!/bin/bash
# add gcc 13 and gcc 14 to Ubuntu 24.04
# launch this script using "sudo"
# check for non official gcc versions on:
# https://launchpad.net/~ubuntu-toolchain-r/+archive/ubuntu/test?field.series_filter=

# install the default building tools
apt update
apt install -y build-essential software-properties-common

# install other GCC versions
apt install -y gcc-14 g++-14

# configure the alternatives for gcc and g++, setting a higher priority to a newer version (ymmv)
update-alternatives --install /usr/bin/gcc gcc /usr/bin/gcc-13 50 --slave /usr/bin/g++ g++ /usr/bin/g++-13
update-alternatives --install /usr/bin/gcc gcc /usr/bin/gcc-14 60 --slave /usr/bin/g++ g++ /usr/bin/g++-14

# check or change the alternatives configuration
update-alternatives --config gcc

Install several Clang versions on Ubuntu ​

You can install and manage several versions of Clang on Ubuntu (or Windows Subsystem for Linux) alongside the default compiler. The recommended approach is to use the LLVM Ubuntu/Debian packages and configure version switching with update-alternatives.

Note: For complex C++ projects, you should register all relevant LLVM/Clang tools as slaves in update-alternatives. The required list of tools varies with each LLVM release. The example below sets only the minimum required for Stockfish/fishtest

Click to view
bash
#!/bin/bash
# add Clang 19 and Clang 21 to a clean Ubuntu
wget https://apt.llvm.org/llvm.sh
sudo apt update
sudo bash llvm.sh 19
sudo bash llvm.sh 21

# configure the alternatives for clang and llvm-profdata, setting a higher priority to a newer version (ymmv)
sudo update-alternatives --install /usr/bin/clang clang /usr/bin/clang-19 19 --slave /usr/bin/clang++ clang++ /usr/bin/clang++-19 --slave /usr/bin/llvm-profdata llvm-profdata /usr/bin/llvm-profdata-19
sudo update-alternatives --install /usr/bin/clang clang /usr/bin/clang-21 21 --slave /usr/bin/clang++ clang++ /usr/bin/clang++-21 --slave /usr/bin/llvm-profdata llvm-profdata /usr/bin/llvm-profdata-21

# check or change the alternatives configuration
sudo update-alternatives --config clang

# to uninstall a Clang version
# LLVM_VERSION=19
# sudo apt purge -y clang-$LLVM_VERSION lldb-$LLVM_VERSION lld-$LLVM_VERSION clangd-$LLVM_VERSION && sudo apt autoremove -y
# sudo update-alternatives --config clang

Coding Style ​

Python ​

PEP 8 - Style Guide for Python Code

Tools configured in pyproject.toml:

Install the git hook to automate formatting and linting on each commit:

bash
cd $HOME/fishtest
uv run pre-commit install

# uninstall the git hook
uv run pre-commit uninstall
# skip temporarily the hook during a commit
git commit --no-verify -a -m "bad syntax commit"

Run ruff manually:

bash
uv run ruff format
uv run ruff check --select I --fix
uv run ruff check

If ruff starts formatting in a wrong way, clean the cache:

bash
uv run ruff clean

CSS, HTML, JavaScript ​

Google HTML/CSS Style Guide - Google JavaScript Style Guide

bash
npx prettier --write 'server/fishtest/static/{css/*.css,html/*.html,js/*.js}'

Shell ​

Google Shell Style Guide

Development Workflows ​

Run server tests locally ​

Start mongod, run the tests, then stop mongod:

bash
mkdir -p .local/mongo-data
mongod --dbpath .local/mongo-data --fork --logpath .local/mongod.log
pushd server && uv run python3 -m unittest discover -s tests -v
popd && mongod --shutdown --dbpath .local/mongo-data

Generate sri.txt for worker PRs ​

The fishtest worker writes in the sri.txt file the hash of the worker files, the GitHub fishtest Continuous Integration stops if the hash is invalid. To generate a new sri.txt before opening a PR for the fishtest worker code, simply run:

bash
python3 worker.py a a --only_config --no_validation

Install a pull request locally ​

The script below fetches and checks out a pull request. Assuming the script is named pull.sh and is in the current directory, it is used as

sh
./pull.sh PULL_ID
Click to view
sh
#!/bin/sh
BRANCH_NAME=PR$1
git switch master
git branch -D $BRANCH_NAME
git fetch -p origin pull/$1/head:$BRANCH_NAME
git switch $BRANCH_NAME