| 1 | |
| 2 | You can get the most recent version of GNU Go ftp.gnu.org or a mirror |
| 3 | (see @url{http://www.gnu.org/order/ftp.html} for a list). You can read |
| 4 | about newer versions and get other information at |
| 5 | @url{http://www.gnu.org/software/gnugo/}. |
| 6 | |
| 7 | @menu |
| 8 | * GNU/Linux and Unix:: GNU Linux and Unix Installation |
| 9 | * Configure Options:: Configure Options |
| 10 | * Windows and MS-DOS:: Windows Installation |
| 11 | * Macintosh:: Macintosh Installation |
| 12 | @end menu |
| 13 | |
| 14 | @node GNU/Linux and Unix, Configure Options, ,Installation |
| 15 | @section GNU/Linux and Unix |
| 16 | @cindex installation |
| 17 | |
| 18 | Untar the sources, change to the directory gnugo-3.8. Now do: |
| 19 | |
| 20 | @example |
| 21 | ./configure [OPTIONS] |
| 22 | make |
| 23 | @end example |
| 24 | |
| 25 | Several configure options will be explained in the next section. You do not |
| 26 | need to set these unless you are dissatisfied with GNU Go's performance or |
| 27 | wish to vary the experimental options. |
| 28 | |
| 29 | As an example, |
| 30 | |
| 31 | @example |
| 32 | ./configure --enable-level=9 --enable-cosmic-gnugo |
| 33 | @end example |
| 34 | |
| 35 | @noindent |
| 36 | will make a binary in which the default level is 9, and the experimental |
| 37 | ``cosmic''' option is enabled. A list of all configure options can be |
| 38 | obtained by running @command{./configure --help}. Further information |
| 39 | about the experimental options can be found in the next section |
| 40 | (@pxref{Configure Options}). |
| 41 | |
| 42 | After running configure and make, you have now made a binary called |
| 43 | @file{interface/gnugo}. Now (running as root) type |
| 44 | |
| 45 | @example |
| 46 | make install |
| 47 | @end example |
| 48 | |
| 49 | @noindent |
| 50 | to install @file{gnugo} in @file{/usr/local/bin}. |
| 51 | |
| 52 | There are different methods of using GNU Go. You may run it from the |
| 53 | command line by just typing: |
| 54 | |
| 55 | @example |
| 56 | gnugo |
| 57 | @end example |
| 58 | |
| 59 | @noindent |
| 60 | but it is nicer to run it using CGoban 1 (under X Window System), |
| 61 | Quarry, Jago (on any platform with a Java Runtime Environment) or other |
| 62 | client programs offering a GUI. |
| 63 | |
| 64 | You can get the most recent version of CGoban 1 from |
| 65 | @url{http://sourceforge.net/projects/cgoban1/}. The earlier version |
| 66 | 1.12 is available from @url{http://www.igoweb.org/~wms/comp/cgoban/index.html}. |
| 67 | The CGoban version number MUST be 1.9.1 at least or it won't work. CGoban 2 |
| 68 | will not work. |
| 69 | |
| 70 | @xref{CGoban}, for instructions on how to run GNU Go from Cgoban, or |
| 71 | @xref{Other Clients}, for Jago or other clients. |
| 72 | |
| 73 | Quarry is available at @url{http://home.gna.org/quarry/}. |
| 74 | |
| 75 | @node Configure Options |
| 76 | @section Configure Options |
| 77 | |
| 78 | There are three options which you should consider configuring, |
| 79 | particularly if you are dissatisfied with GNU Go's performance. |
| 80 | |
| 81 | @menu |
| 82 | * Ram Cache:: Ram Cache |
| 83 | * Default Level:: Default Level |
| 84 | * Other Options:: Other Options |
| 85 | @end menu |
| 86 | |
| 87 | @node Ram Cache |
| 88 | @subsection Ram Cache |
| 89 | |
| 90 | By default, GNU Go makes a cache of about 8 Megabytes in RAM for its |
| 91 | internal use. The cache is used to store intermediate results during |
| 92 | its analysis of the position. More precisely the default cache size is |
| 93 | 350000 entries, which translates to 8.01 MB on typical 32 bit |
| 94 | platforms and 10.68 MB on typical 64 bit platforms. |
| 95 | |
| 96 | Increasing the cache size will often give a modest speed improvement. |
| 97 | If your system has lots of RAM, consider increasing the cache |
| 98 | size. But if the cache is too large, swapping will occur, |
| 99 | causing hard drive accesses and degrading performance. If |
| 100 | your hard drive seems to be running excessively your cache |
| 101 | may be too large. On GNU/Linux systems, you may detect swapping |
| 102 | using the program 'top'. Use the 'f' command to toggle SWAP |
| 103 | display. |
| 104 | |
| 105 | You may override the size of the default cache at compile time |
| 106 | by running one of: |
| 107 | |
| 108 | @example |
| 109 | ./configure --enable-cache-size=n |
| 110 | @end example |
| 111 | |
| 112 | @noindent |
| 113 | to set the cache size to @code{n} megabytes. For example |
| 114 | |
| 115 | @example |
| 116 | ./configure --enable-cache-size=32 |
| 117 | @end example |
| 118 | |
| 119 | @noindent |
| 120 | creates a cache of size 32 megabytes. If you omit this, your default |
| 121 | cache size will be 8-11 MB as discussed above. Setting cache size |
| 122 | negative also gives the default size. You must recompile and reinstall |
| 123 | GNU Go after reconfiguring it by running @command{make} and |
| 124 | @command{make install}. |
| 125 | |
| 126 | You may override the compile-time defaults by running @file{gnugo} |
| 127 | with the option @option{--cache-size n}, where @code{n} is the size in |
| 128 | megabytes of the cache you want, and @option{--level} where n is the |
| 129 | level desired. We will discuss setting these parameters next in |
| 130 | detail. |
| 131 | |
| 132 | @node Default Level |
| 133 | @subsection Default Level |
| 134 | |
| 135 | GNU Go can play at different levels. Up to level 10 is |
| 136 | supported. At level 10 GNU Go is much more accurate but takes |
| 137 | an average of about 1.6 times longer to play than at level 8. |
| 138 | |
| 139 | The level can be set at run time using the @option{--level} option. |
| 140 | If you don't set this, the default level will be used. You |
| 141 | can set the default level with the configure option |
| 142 | @option{--enable-level=n}. For example |
| 143 | |
| 144 | @example |
| 145 | ./configure --enable-level=9 |
| 146 | @end example |
| 147 | |
| 148 | @noindent |
| 149 | sets the default level to 9. If you omit this parameter, |
| 150 | the compiler sets the default level to 10. We recommend |
| 151 | using level 10 unless you find it too slow. If you decide |
| 152 | you want to change the default you may rerun configure |
| 153 | and recompile the program. |
| 154 | |
| 155 | @node Other Options |
| 156 | @subsection Other Options |
| 157 | |
| 158 | Anything new in the engine is generally tested as an experimental option |
| 159 | which can be turned on or off at compile time or run time. Some |
| 160 | ``experimental'' options such as the break-in code are no longer |
| 161 | experimental but are enabled by default. |
| 162 | |
| 163 | This section can be skipped unless you are interested in the |
| 164 | experimental options. |
| 165 | |
| 166 | Moreover, some configure options were removed from the stable |
| 167 | release. For example it is known that the owl extension code |
| 168 | can cause crashes, so the configure option --enable-experimental-owl-ext |
| 169 | was disabled for 3.8. |
| 170 | |
| 171 | The term ``default'' must be clarified, since there |
| 172 | are really two sets of defaults at hand, runtime defaults |
| 173 | specified in @file{config.h} and compile time default |
| 174 | values for the runtime defaults, contained in @file{configure} |
| 175 | (which is created by editing @file{configure.in} then running |
| 176 | @command{autoconf}. For example we find in @file{config.h} |
| 177 | |
| 178 | @example |
| 179 | /* Center oriented influence. Disabled by default. */ |
| 180 | #define COSMIC_GNUGO 0 |
| 181 | |
| 182 | /* Break-in module. Enabled by default. */ |
| 183 | #define USE_BREAK_IN 1 |
| 184 | @end example |
| 185 | |
| 186 | This means that the experimental cosmic option, which causes |
| 187 | GNU Go to play a center-oriented game (and makes the engine |
| 188 | weaker) is disabled by default, but that the break-in module |
| 189 | is used. These are defaults which are used when GNU Go is |
| 190 | run without command line options. They can be overridden |
| 191 | with the run time options: |
| 192 | |
| 193 | @example |
| 194 | gnugo --cosmic-gnugo --without-break-in |
| 195 | @end example |
| 196 | |
| 197 | Alternatively you can configure GNU Go as follows: |
| 198 | |
| 199 | @example |
| 200 | ./configure --enable-cosmic-gnugo --disable-experimental-break-in |
| 201 | @end example |
| 202 | |
| 203 | then recompile GNU Go. This changes the defaults in @file{config.h}, |
| 204 | so that you do not have to pass any command line options to GNU Go |
| 205 | at run time to get the experimental owl extension turned on and |
| 206 | the experimental break-in code turned off. |
| 207 | |
| 208 | If you want to find out what experimental options were compiled into your GNU |
| 209 | Go binary you can run @command{gnugo --options} to find out. Here is a list |
| 210 | of experimental options in GNU Go. |
| 211 | |
| 212 | @itemize @bullet |
| 213 | @item @code{experimental-break-in}. Experimental break-in code |
| 214 | (@pxref{Break Ins}). You should not need to configure this because |
| 215 | the break in code is enabled by default in level 10, and is turned |
| 216 | off at level 9. If you don't want the breakin code just play at |
| 217 | level 9. |
| 218 | @item @code{cosmic-gnugo}. An experimental style which plays a center |
| 219 | oriented game and has a good winning rate against standard GNU Go, |
| 220 | though it makes GNU Go weaker against other opponents. |
| 221 | @item @code{large-scale}. Attempt to make large-scale captures. |
| 222 | See: |
| 223 | |
| 224 | @url{http://lists.gnu.org/archive/html/gnugo-devel/2003-07/msg00209.html} |
| 225 | |
| 226 | for the philosophy of this option. This option makes the engine slower. |
| 227 | @item @code{metamachine}. Enables the metamachine, which allows |
| 228 | you to run the engine in an experimental mode whereby it forks |
| 229 | a new @code{gnugo} process which acts as an ``oracle.'' Has no |
| 230 | effect unless combined with the @option{--metamachine} run-time |
| 231 | option. |
| 232 | @end itemize |
| 233 | |
| 234 | Other options are not experimental, and can be changed as |
| 235 | configure or runtime options. |
| 236 | |
| 237 | @itemize @bullet |
| 238 | @item @code{chinese-rules} Use Chinese (area) counting. |
| 239 | @item @code{resignation-allowed} Allow GNU Go to resign games. |
| 240 | This is on by default. |
| 241 | @end itemize |
| 242 | |
| 243 | @node Windows and MS-DOS, Macintosh, Configure Options, Installation |
| 244 | @section Compiling GNU Go on Microsoft platforms |
| 245 | |
| 246 | @subsection Building with older visual studio |
| 247 | |
| 248 | The distribution directories contain some .dsp and .dsw files with |
| 249 | GNU Go. These have been brought up to date in the sense that they |
| 250 | should work if you have the older VC++ with Visual Studio 6 |
| 251 | but the distributed .dsp and .dsw files will only be of use with |
| 252 | older version of Visual Studio. |
| 253 | |
| 254 | In most cases (unless you are building in Cygwin) the preferred way |
| 255 | to build GNU Go on Windows platforms is to use CMake. CMake |
| 256 | understands about many versions of Visual C/Visual Studio, and will |
| 257 | generate project/solution files for the tools installed on your |
| 258 | system. So even if you have Visual Studio 6 you may use CMake |
| 259 | and dispense with the distributed .dsp and .dsw files. |
| 260 | |
| 261 | @subsection Building with Visual Studio project files |
| 262 | |
| 263 | Before you compile the GNU Go source, you need to run CMake first, to |
| 264 | generate the build files you'll give to Visual Studio. |
| 265 | |
| 266 | From the cmd.exe command prompt, CD into the GNU Go source directory. |
| 267 | To confirm you're in the right place, you should see the file |
| 268 | 'CMakeLists.txt' in the top-level directory of the GNU Go code (as well |
| 269 | as others in lower subdirectories). |
| 270 | |
| 271 | Direct CMake to generate the new Visual Studio build files by typing: |
| 272 | |
| 273 | @example |
| 274 | cmake CMakeLists.txt |
| 275 | @end example |
| 276 | |
| 277 | Compile the code by invoking the newly-created Solution file: |
| 278 | |
| 279 | @example |
| 280 | vcbuild GNUGo.sln |
| 281 | @end example |
| 282 | |
| 283 | This will take a few moments, as CMake generates 4 debug/retail targets: |
| 284 | |
| 285 | @example |
| 286 | debug |
| 287 | release |
| 288 | minsizerel |
| 289 | relwithdebinfo |
| 290 | @end example |
| 291 | |
| 292 | For each of these targets, Visual Studio is generating a version of |
| 293 | gnugo.exe: |
| 294 | |
| 295 | @example |
| 296 | interface\debug\gnugo.exe |
| 297 | interface\release\gnugo.exe |
| 298 | interface\minsizerel\gnugo.exe |
| 299 | interface\relwithdebinfo\gnugo.exe |
| 300 | @end example |
| 301 | |
| 302 | Additionally, there is an 'Install' target available, that will copy the |
| 303 | the gnugo.exe into the %ProgramFiles% directory. To do this, type: |
| 304 | |
| 305 | @example |
| 306 | vcbuild INSTALL.vcproj |
| 307 | @end example |
| 308 | |
| 309 | This should result in copying GNU/Go into: |
| 310 | |
| 311 | @example |
| 312 | "%ProgramFiles%\GNUGo\bin\gnugo.exe" --options |
| 313 | @end example |
| 314 | |
| 315 | In addition to command line use, CMake also has a GUI version. Users of |
| 316 | the Visual Studio GUI might prefer to use that. |
| 317 | |
| 318 | @subsection Building with Nmake makefiles |
| 319 | |
| 320 | GNU Go will also build using NMake makefiles. Optionally, instead of |
| 321 | Visual Studio project/solution files, you may direct CMake to generate |
| 322 | NMake makefiles. To generate the makefiles: |
| 323 | |
| 324 | @example |
| 325 | cmake -G "NMake Makefiles" CMakeLists.txt |
| 326 | @end example |
| 327 | |
| 328 | The default rule for the makefile is 'all'. Use the 'help' rule to show |
| 329 | a list of available targets. |
| 330 | |
| 331 | @example |
| 332 | nmake -f Makefile help |
| 333 | @end example |
| 334 | |
| 335 | To compile GNU Go: |
| 336 | |
| 337 | @example |
| 338 | nmake -f Makefil, all |
| 339 | @end example |
| 340 | |
| 341 | One sysand 2009 tems, GNU GO may fail to build when using NMake makefiles. |
| 342 | only fails the first time run, run NMake again with the 'clean all' |
| 343 | targets, and it will compile the second and subsequent times. |
| 344 | |
| 345 | @example |
| 346 | nmake -f Makefile clean all |
| 347 | @end example |
| 348 | |
| 349 | Which will successfully generate a gnugo.exe. |
| 350 | |
| 351 | @example |
| 352 | interface\gnugo.exe --options |
| 353 | @end example |
| 354 | |
| 355 | @subsection Building with MinGW Makefiles |
| 356 | |
| 357 | GNU Go can be built on Windows systems using MinGW. |
| 358 | |
| 359 | This development environment uses: the GCC compiler (gcc.exe, not |
| 360 | cl.exe), the Microsoft C runtime libraries (MSCRT, not GLibC), the GNU |
| 361 | Make build tool (@code{mingw32-make.exe}, not NMake), all from the Windows |
| 362 | shell (@code{cmd.exe}, not sh/bash). |
| 363 | |
| 364 | For CMake to work, in addition to the base MinGW installation, the C++ |
| 365 | compiler (g++.exe) and GNU Make (mingw32-make.exe) need to be installed. |
| 366 | This was tested using GCC v3, not the experimental v4. To debug, use |
| 367 | GDB, as the GCC-generated symbols won't work with NTSD/Windbg/Visual Studio. |
| 368 | |
| 369 | To create the makfiles, run CMake with the MinGW generator option: |
| 370 | |
| 371 | @example |
| 372 | cmake -G "MinGW Makefiles" CMakeLists.txt |
| 373 | @end example |
| 374 | |
| 375 | To build GNU Go, from a cmd.exe shell, run GNU Make (against the |
| 376 | newly-created 'Makefile' and it's default 'all' target): |
| 377 | |
| 378 | @example |
| 379 | mingw32-make |
| 380 | ..\interface\gnugo.exe --options |
| 381 | @end example |
| 382 | |
| 383 | @subsection Building with MSYS makefiles (MinGW) |
| 384 | |
| 385 | GNU Go can be built on Windows systems using MSYS. |
| 386 | |
| 387 | This development environment uses: the GCC compiler (gcc.exe, not |
| 388 | cl.exe), the Microsoft C runtime libraries (MSCRT, not GLibC), the GNU |
| 389 | Make build tool (make, not NMake), all from the GNU Bash (sh.exe, not |
| 390 | cmd.exe). |
| 391 | |
| 392 | To create the makfiles, run CMake with the MSYS generator option: |
| 393 | |
| 394 | @example |
| 395 | cmake -G "MSYS Makefiles" CMakeLists.txt |
| 396 | @end example |
| 397 | |
| 398 | Start MSYS's Bash shell, either clicking on a shortcut on from the |
| 399 | command line: |
| 400 | |
| 401 | @example |
| 402 | cd /d c:\msys\1.0 |
| 403 | msys.bat |
| 404 | @end example |
| 405 | |
| 406 | To build GNU Go, from a Bash shell, run GNU Make (against the |
| 407 | newly-created 'Makefile' and it's default 'all' target): |
| 408 | |
| 409 | @example |
| 410 | make |
| 411 | ../interface/gnugo.exe --options |
| 412 | @end example |
| 413 | |
| 414 | To debug, use GDB, as the GCC-generated symbols won't work with |
| 415 | NTSD/Windbg/Visual Studio. |
| 416 | |
| 417 | @subsection Building on cygwin |
| 418 | |
| 419 | With Cygwin, you should be able to |
| 420 | |
| 421 | @example |
| 422 | tar zxvf gnugo-3.8.tar.gz |
| 423 | cd gnugo-3.8 |
| 424 | env CC='gcc -mno-cygwin' ./configure |
| 425 | make |
| 426 | @end example |
| 427 | |
| 428 | @subsection Testing on Windows: |
| 429 | |
| 430 | @file{regression/regress.cmd} is a simplified cmd.exe-centric port of the main |
| 431 | gnugo Unix shell script regress.sh. It can be used to help verify that the |
| 432 | generated binary might be operational. Read the script's comment header for |
| 433 | more information. For access to the full GNU Go tests, use Unix, not Windows. |
| 434 | |
| 435 | To test: |
| 436 | |
| 437 | @example |
| 438 | cd regression |
| 439 | regress.cmd ..\interface\gnugo.exe |
| 440 | @end example |
| 441 | |
| 442 | @node Macintosh |
| 443 | @section Macintosh |
| 444 | |
| 445 | If you have Mac OS X you can build GNU Go using Apple's compiler, |
| 446 | which is derived from GCC. You will need Xcode. |
| 447 | |
| 448 | One issue is that the configure test for socket support is |
| 449 | too conservative. On OS/X, the configure test fails, but |
| 450 | actually socket support exists. So if you want to be able |
| 451 | to connect to the engine through tcp/ip (using gtp) you |
| 452 | may @command{configure --enable-socket-support}. There |
| 453 | will be an error message but you may build the engine |
| 454 | and socket support should work. |
| 455 | |
| 456 | |