This is the README.md file for belofte, a promising chess program
released under GNU - GPL v2.0. Binaries are available for Mac OS X, Linux,
Windows, Android, all in 32 and 64 bit. The last stable release is 2.1.3.4 and
has been released on 02/07/2024.

Belofte is a cross platform chess program that requires a graphical user
interface or that can be run on the command line. Most users will want to use
a graphical user interface. See Configuring your UI section below.

The added value of Belofte is that it can be beaten by a human opponent.
The program is a perfect companion of beginning chess players. Please note that
this advantage might fade away in upcoming versions.

• Please refer to the user manual for more information on the
  program. Please refer to licensing information
  section in the user manual as well.
• Please refer to the homepage for more information. Belofte has been
  published on sourceforge.
  http://macchess.internetcontact.be

Version 2 is a rewrite of the program from scratch. At this time, version 0.9.12
is the strongest version generally available. Version 0.9.18 should be stronger.
Unfortunately, version 0.9.18 has some issues on windows and did not make it
in the public elo lists.

Please download binaries from the git repository or from the homepage.
The different binaries for the different platforms can be found in
the dist directory.

Playing a game

Launching the program from the graphical user interface

Please note that the program is not intended to run clicking from a graphical
user interface. On Windows, a command line will be presented, on all other
platforms, the program will run in background needing to be killed manually.
Please configure a UI as explained below.

The program interfaces according to the UCI protocol or the
Xboard protocol (also known as the CECP or Winboard protocol).
This program has been tested with following user-interfaces: Arena, cutechess,
eBoard, pychess. It works fine as well with any interace implementing the UCI
or Xboard protocol.

Please note that versions before 2.0 do support the Xboard protocol only.
The UCI protocol is correctly implemented in version 2.0. As of version
2.1.1, both protocols are fully supported.

Configuring your UI

• Arena (see http://www.playwitharena.de/) (linux/windows)
• Xboard (see https://www.gnu.org/software/xboard/) (linux/macos)
• Winboard (see xboard, WinBoard) (windows)
• Cute Chess (see https://github.com/cutechess/cutechess) (linux/macos/windows)
• Droidfish (DroidFish) (android)
• BanksiaGui (https://banksiagui.com/) (linux/macos/windows)
• Scid vs PC (windows/macos)
• ChessX (linux/macos/windows)
• Nibbler (https://github.com/rooklift/nibbler) (linux/macos/windows)
• Schredder (windows/macos/ios/android/linux)
• Chessbase, Fritz, Chessmaster, ... (windows)
• pychess (see PyChess) (linux)
• eBoard (see https://sourceforge.net/projects/eboard/) (linux)

Belofte expects one of the following commands after launching:

• uci for getting into uci mode, or passing --uci as a parameter;
• xboard followed by protover 2 for getting into xboard mode (or passing
  --xboard or -xboard as a parameter).

If no command is issued, belofte will work more or less like a winboard 1
compatible program while accepting all UCI and CECP commands.

Launching the program on the command line

Please open a terminal or command prompt and launch the program.
The program accepts different optional command line parameters as shown below:

• Linux, BSD Unix, Mac OSX, Unix, Solaris Windows 10 with WSL or WSL-2.

./belofte [script]
./belofte --help
./belofte --uci [script]
./belofte --version
./belofte -xboard [script]

• Windows 95, 98, Me, Vista, 7, 8, 8.1, 10, 11

Replace ./belofte with belofte.exe.

• Android, Arduino, ...

To be completed.

Typical game on the command line

After having started the program, issue the following commands:

belofte>uci
id name Belofte 2.1.3.4
id author Yves De Billoëz
... further option lines ...
uciok
>isready
readyok
>ucinewgame
>isready
readyok
>position startpos
>go depth 1
... wait for engine to play its move ...
belofte>quit

Configuring belofte

The UCI protocol has support for runtime configuration that can be activated
through the UI.

Possible UCI configuration commands (default in bold):

• alg Random|StaticEval|BruteForce|SearchIterativeBF| AB |ABFS|ABFH
• evaltype PiecesOnly|StaticBoard| PositionalBoard

After reading eventual command line parameters, and parsing a file passed on
the command line, Belofte will start reading a file consisting of its program
name and a .rc suffix. This can be useful to read e.g. an opening book or
to configure the algorithm.

e.g. One could rename belofte-2.1.3.4 into belofte-2.1.3.4-random and
supply an rc-file with the name belofte-2.1.3.4-randcom.rc with the
alg Random command in order to force this version to play with the ramdom
protocol.

#!/bin/env belofte.sh
# configuration script
echo Reading configuration script belofte-2.1.3.4.rc
alg Random

At runtime, after playing a move, one could undo the move and issue
an alg BruteForce command to search again with the brute-force algorithm.

When compiling, following conditionals can be turned on:

• BELOFTE_NORANDOM: removes random seeds added to position evaluation;
• BELOFTE_TESTFUNCTION: to call testfunction during init;
• BELOFTE_UCIMODE: creates a binary that defaults to UCI protocol;
• BELOFTE_NOSIGNALS: suppress reaction to signals. (SIGINT, SIGTERM);
• BELOFTE_NOUNICODE: compile for platforms that do not support UTF-8 console
  output, defined for Windows targets;
• INCOMPLETE_C11: compile with compiler that does not support full C++11,
  defined for GCC before version 6;

Playing against other engines

Belofte can be tested against other engines. Please edit the
test/engines.json file to include your engine.
You can edit the test/tour-allversions.sh script to organise a tournament
in between different engines. Make sure to extend the path in the script to
include all engines you want to use. Use symbolic links if required.

cd test
./tour-allversions.sh
./tour-nextversion.sh -debug -concurrency 2
./tour-bottomlist.sh -concurrency 8

Following an ongoing match.

cd test
./cutewatch.sh tour-nextversion

Belofte can be used with cutechess[-cli], BanksiaGui and Arena.

Testing positions, benchmarking, finding mates

Belofte supports epd to test a position. Launch epd pos, epd file commands
with valid epd strings. Please refer to the documentation for more information.

cd test
./belofte.sh belofte 64 2.1.3.4 bmi2
belofte>epd file epd/test.epd

Run benchmark against specific compile (GCC only):

cd test
./belofte.sh belofte 64 2.1.3.4 popcnt --bench

Run windows (32/64 bit) executable from linux through wine:

cd test
./belofte.sh wine 64 2.1.3.4 --version

Belofte also supports executing commands from a command file. Use
exec to run a test.

cd test
./belofte.sh
belofte>exec testcase/perft01.rc

Building/Compiling/Debugging

If the binaries for your platform are not released, or you want
to create a custom build, you need to compile from source. Your toolset needs to support C++11. See C++ reference
for more information.

cd project
make all

Alternatively:

cd project
./compile.sh [--gcc|--clang] [--all|--32|--64] [--opt|--profile] [next]

• --gcc: prefer gcc complier;
• --clang: prefer clang compiler;
• --all: build all targets, 32 and 64 bit (on 64 bit platform);
• --32: build 32 bit target only;
• --64: build 64 bit target only;
• --opt: also generate optimized build (32/64) and a static build (64)
  for your machine;
• --profile: build non optimized profilable build;
• next: if not passed, will detect version number from source code.

Linux

By default, your platform is only configured to compile compatible programs.
Therefor, on a 64 bit system, 32 bit compilation must be enabled manually
first. See below. Not doing so will result in an error during compilation
that can be ignored.

• Compiling on Linux x64 for 32 or 64 bit with Clang or GCC installed,
  use compile.sh.

• Installing Clang 32 target compilation on 64 bit Linux:

dnf install glibc-devel.i686

Replace dnf with yum/apt-get/... according to your linux flavour.

• Compiling on Linux x86_64 with Code::Blocks installed:
  Open Code::Blocks project file, select target and build all or debug.

• Compiling on Linux wiht NetBeans installed:
  Open NetBeans 8.02 or NetBeans 8.2, compile or debug.

Mac OS X

• Compiling on Mac OS X with developer command line tools for Xcode installed,
  use compile.sh.

Windows

• Compiling on Windows 64bit with Code::Blocks installed:
  Open Code::Blocks project file, select target and build all or debug.

• Compiling on Windows with Dev C++ installed:
  Open Dev C++ project (.dev) and build all. (warning, creates slow
  executable due to bundled gcc version.)

• Compiling on Windows with other compilers:
  Compiler needs to support C++11, This means that following compilers
  will not work: Visual Studio Express, versions before Visual Studio 2015,
  Visual Studio Code, Borland C++ builder, Borland C++, ...

You cannot run or debug 64 bit code on a 32 bit platform.

Android

• Android builds are generated with ndk-build from Android NDK r22 Beta 1.

cd project/ndk-build
make

ReactOS

• Install the Code::Blocks from the repository:
  Open Code::Blocks project file, select target w32 and build. Running not yet
  possible though.

Changelist

Fixes implemented in different versions.
For open issues, please refer to the TODO.md file.

2.1.3

Intially released on 03/08/2021 Fix dates:
06/09/2021 (2.1.3.1)
07/09/2021 (2.1.3.2)
24/10/2021 (2.1.3.3)
02/07/2024 (2.1.3.4)

For the details of the release, these fixes and previous releases, please
refer to the HISTORY.md file.

eof