You can get the most recent version of GNU Go ftp.gnu.org or a mirror (see http://www.gnu.org/order/ftp.html for a list).  You can read about newer versions and get other information at http://www.gnu.org/software/gnugo/.

GNU/Linux and Unix
==================

Untar the sources, change to the directory gnugo-3.8. Now do:

        ./configure [OPTIONS]
        make

Several configure options will be explained in the next section. You do not need to set these unless you are dissatisfied with GNU Go's performance or wish to vary the experimental options.

As an example,

        ./configure --enable-level=9 --enable-cosmic-gnugo

will make a binary in which the default level is 9, and the experimental ``cosmic''' option is enabled. A list of all configure options can be obtained by running ./configure --help. Further information about the experimental options can be found in the next section (see Configure Options).

After running configure and make, you have now made a binary called interface/gnugo. Now (running as root) type

        make install

to install gnugo in /usr/local/bin.

There are different methods of using GNU Go. You may run it from the command line by just typing:

        gnugo

but it is nicer to run it using CGoban 1 (under X Window System), Quarry, Jago (on any platform with a Java Runtime Environment) or other client programs offering a GUI.

You can get the most recent version of CGoban 1 from http://sourceforge.net/projects/cgoban1/. The earlier version 1.12 is available from http://www.igoweb.org/~wms/comp/cgoban/index.html. The CGoban version number MUST be 1.9.1 at least or it won't work. CGoban 2 will not work.

See CGoban, for instructions on how to run GNU Go from Cgoban, or see Other Clients, for Jago or other clients.

Quarry is available at http://home.gna.org/quarry/.

Configure Options
=================

There are three options which you should consider configuring, particularly if you are dissatisfied with GNU Go's performance.

Ram Cache
---------

By default, GNU Go makes a cache of about 8 Megabytes in RAM for its internal use. The cache is used to store intermediate results during its analysis of the position. More precisely the default cache size is 350000 entries, which translates to 8.01 MB on typical 32 bit platforms and 10.68 MB on typical 64 bit platforms.

Increasing the cache size will often give a modest speed improvement. If your system has lots of RAM, consider increasing the cache size. But if the cache is too large, swapping will occur, causing hard drive accesses and degrading performance. If your hard drive seems to be running excessively your cache may be too large. On GNU/Linux systems, you may detect swapping using the program 'top'. Use the 'f' command to toggle SWAP display.

You may override the size of the default cache at compile time by running one of:

        ./configure --enable-cache-size=n

to set the cache size to n megabytes. For example

        ./configure --enable-cache-size=32

creates a cache of size 32 megabytes. If you omit this, your default cache size will be 8-11 MB as discussed above. Setting cache size negative also gives the default size. You must recompile and reinstall GNU Go after reconfiguring it by running make and make install.

You may override the compile-time defaults by running gnugo with the option --cache-size n, where n is the size in megabytes of the cache you want, and --level where n is the level desired.  We will discuss setting these parameters next in detail.

Default Level
-------------

GNU Go can play at different levels. Up to level 10 is supported. At level 10 GNU Go is much more accurate but takes an average of about 1.6 times longer to play than at level 8.

The level can be set at run time using the --level option. If you don't set this, the default level will be used. You can set the default level with the configure option --enable-level=n. For example

     ./configure --enable-level=9

sets the default level to 9. If you omit this parameter, the compiler sets the default level to 10. We recommend using level 10 unless you find it too slow. If you decide you want to change the default you may rerun configure and recompile the program.

Other Options
-------------

Anything new in the engine is generally tested as an experimental option which can be turned on or off at compile time or run time. Some ``experimental'' options such as the break-in code are no longer experimental but are enabled by default.

This section can be skipped unless you are interested in the experimental options.

Moreover, some configure options were removed from the stable release. For example it is known that the owl extension code can cause crashes, so the configure option --enable-experimental-owl-ext was disabled for 3.8.

The term ``default'' must be clarified, since there are really two sets of defaults at hand, runtime defaults specified in config.h and compile time default values for the runtime defaults, contained in configure (which is created by editing configure.in then running autoconf. For example we find in config.h

     /* Center oriented influence. Disabled by default. */
     #define COSMIC_GNUGO 0

     /* Break-in module. Enabled by default. */
     #define USE_BREAK_IN 1

This means that the experimental cosmic option, which causes GNU Go to play a center-oriented game (and makes the engine weaker) is disabled by default, but that the break-in module is used. These are defaults which are used when GNU Go is run without command line options. They can be overridden with the run time options:

     gnugo --cosmic-gnugo --without-break-in

Alternatively you can configure GNU Go as follows:

     ./configure --enable-cosmic-gnugo --disable-experimental-break-in

then recompile GNU Go. This changes the defaults in config.h, so that you do not have to pass any command line options to GNU Go at run time to get the experimental owl extension turned on and the experimental break-in code turned off.

If you want to find out what experimental options were compiled into your GNU Go binary you can run gnugo --options to find out. Here is a list of experimental options in GNU Go.

  * experimental-break-in. Experimental break-in code (see Break Ins). You should not need to configure this because the break in code is enabled by default in level 10, and is turned off at level 9. If you don't want the breakin code just play at level 9.

  * cosmic-gnugo. An experimental style which plays a center oriented game and has a good winning rate against standard GNU Go, though it makes GNU Go weaker against other opponents.

  * large-scale. Attempt to make large-scale captures. See:

     http://lists.gnu.org/archive/html/gnugo-devel/2003-07/msg00209.html

     for the philosophy of this option. This option makes the engine slower.

  * metamachine. Enables the metamachine, which allows you to run the engine in an experimental mode whereby it forks a new gnugo process which acts as an ``oracle.'' Has no effect unless combined with the --metamachine run-time option.

Other options are not experimental, and can be changed as configure or runtime options.

  * chinese-rules Use Chinese (area) counting.

  * resignation-allowed Allow GNU Go to resign games. This is on by default.

Compiling GNU Go on Microsoft platforms
=======================================

Building with older visual studio
---------------------------------

The distribution directories contain some .dsp and .dsw files with GNU Go. These have been brought up to date in the sense that they should work if you have the older VC++ with Visual Studio 6 but the distributed .dsp and .dsw files will only be of use with older version of Visual Studio.

In most cases (unless you are building in Cygwin) the preferred way to build GNU Go on Windows platforms is to use CMake. CMake understands about many versions of Visual C/Visual Studio, and will generate project/solution files for the tools installed on your system. So even if you have Visual Studio 6 you may use CMake and dispense with the distributed .dsp and .dsw files.

Building with Visual Studio project files
-----------------------------------------

Before you compile the GNU Go source, you need to run CMake first, to generate the build files you'll give to Visual Studio.

From the cmd.exe command prompt, CD into the GNU Go source directory. To confirm you're in the right place, you should see the file 'CMakeLists.txt' in the top-level directory of the GNU Go code (as well as others in lower subdirectories).

Direct CMake to generate the new Visual Studio build files by typing:

         cmake CMakeLists.txt

Compile the code by invoking the newly-created Solution file:

         vcbuild GNUGo.sln

This will take a few moments, as CMake generates 4 debug/retail targets:

         debug
         release
         minsizerel
         relwithdebinfo

For each of these targets, Visual Studio is generating a version of gnugo.exe:

         interface\debug\gnugo.exe
         interface\release\gnugo.exe
         interface\minsizerel\gnugo.exe
         interface\relwithdebinfo\gnugo.exe

Additionally, there is an 'Install' target available, that will copy the the gnugo.exe into the %ProgramFiles% directory. To do this, type:

         vcbuild INSTALL.vcproj

This should result in copying GNU/Go into:

         "%ProgramFiles%\GNUGo\bin\gnugo.exe" --options

In addition to command line use, CMake also has a GUI version. Users of the Visual Studio GUI might prefer to use that.

Building with Nmake makefiles
-----------------------------

GNU Go will also build using NMake makefiles. Optionally, instead of Visual Studio project/solution files, you may direct CMake to generate NMake makefiles. To generate the makefiles:

         cmake -G "NMake Makefiles" CMakeLists.txt

The default rule for the makefile is 'all'. Use the 'help' rule to show a list of available targets.

         nmake -f Makefile help

To compile GNU Go:

         nmake -f Makefil, all

One sysand 2009 tems, GNU GO may fail to build when using NMake makefiles. only fails the first time run, run NMake again with the 'clean all' targets, and it will compile the second and subsequent times.

         nmake -f Makefile clean all

Which will successfully generate a gnugo.exe.

         interface\gnugo.exe --options

Building with MinGW Makefiles
-----------------------------

GNU Go can be built on Windows systems using MinGW.

This development environment uses: the GCC compiler (gcc.exe, not cl.exe), the Microsoft C runtime libraries (MSCRT, not GLibC), the GNU Make build tool (mingw32-make.exe, not NMake), all from the Windows shell (cmd.exe, not sh/bash).

For CMake to work, in addition to the base MinGW installation, the C++ compiler (g++.exe) and GNU Make (mingw32-make.exe) need to be installed. This was tested using GCC v3, not the experimental v4. To debug, use GDB, as the GCC-generated symbols won't work with NTSD/Windbg/Visual Studio.

To create the makfiles, run CMake with the MinGW generator option:

         cmake -G "MinGW Makefiles" CMakeLists.txt

To build GNU Go, from a cmd.exe shell, run GNU Make (against the newly-created 'Makefile' and it's default 'all' target):

         mingw32-make
         ..\interface\gnugo.exe --options

Building with MSYS makefiles (MinGW)
------------------------------------

GNU Go can be built on Windows systems using MSYS.

This development environment uses: the GCC compiler (gcc.exe, not cl.exe), the Microsoft C runtime libraries (MSCRT, not GLibC), the GNU Make build tool (make, not NMake), all from the GNU Bash (sh.exe, not cmd.exe).

To create the makfiles, run CMake with the MSYS generator option:

         cmake -G "MSYS Makefiles" CMakeLists.txt

Start MSYS's Bash shell, either clicking on a shortcut on from the command line:

         cd /d c:\msys\1.0
         msys.bat

To build GNU Go, from a Bash shell, run GNU Make (against the newly-created 'Makefile' and it's default 'all' target):

         make
         ../interface/gnugo.exe --options

To debug, use GDB, as the GCC-generated symbols won't work with NTSD/Windbg/Visual Studio.

Building on cygwin
------------------

With Cygwin, you should be able to

       tar zxvf gnugo-3.8.tar.gz
       cd gnugo-3.8
       env CC='gcc -mno-cygwin' ./configure
       make

Testing on Windows:
-------------------

regression/regress.cmd is a simplified cmd.exe-centric port of the main gnugo Unix shell script regress.sh. It can be used to help verify that the generated binary might be operational. Read the script's comment header for more information. For access to the full GNU Go tests, use Unix, not Windows.

To test:

         cd regression
         regress.cmd ..\interface\gnugo.exe

Macintosh
=========

If you have Mac OS X you can build GNU Go using Apple's compiler, which is derived from GCC. You will need Xcode.

One issue is that the configure test for socket support is too conservative. On OS/X, the configure test fails, but actually socket support exists. So if you want to be able to connect to the engine through tcp/ip (using gtp) you may configure --enable-socket-support.  There will be an error message but you may build the engine and socket support should work.