Commit | Line | Data |
---|---|---|
7eeb782e AT |
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 |