Cut the Sac Eye penalty to 1 amuletsworth (DrKe)
[crawl.git] / crawl-ref / INSTALL.txt
1 Install instructions for Dungeon Crawl Stone Soup (DCSS)
2 --------------------------------------------------------
3
4 Getting DCSS to run
5 -------------------
6
7 This file describes how to compile a runtime executable of DCSS from the
8 source code. If you're trying to compile Crawl yourself, skip ahead to the
9 next section, "Building Dungeon Crawl Stone Soup".
10
11 If, however, you're having trouble getting a precompiled binary to run:
12
13 1) Check whether you've downloaded and extracted the correct version.
14
15     Platform        Tiles?          Download package
16     --------        ------          ----------------
17     Windows         yes             stone_soup-VERSION-tiles-win32.zip
18     Windows         no              stone_soup-VERSION-win32.zip
19     Mac OS X        yes             stone_soup-VERSION-tiles-osx.zip
20                                     or stone_soup-VERSION-tiles-osx-app.dmg
21     Mac OS X        no              stone_soup-VERSION-osx.zip
22                                     or stone_soup-VERSION-osx-app.dmg
23     Source code     yes             stone_soup-VERSION-src.zip
24                                     or stone_soup-VERSION-src.tar.bz2
25
26 2) Try removing/renaming your saves/ directory in case older saves aren't
27    recognized anymore.
28
29
30 If you still can't get Crawl to run, you can ask for further help on IRC:
31 ##crawl-dev on freenode, forums: https://crawl.develz.org/tavern/ or usenet:
32 rec.games.roguelike.misc. Please try to be as detailed as possible about
33 any error messages you're getting.
34
35 The rest of the file deals with compiling from the source.
36
37
38 Building Dungeon Crawl Stone Soup
39 ---------------------------------
40
41 Crawl Stone Soup is known to run on the following platforms as of version
42 0.12:
43
44 - Any Unix with GNU or BSD userland.
45 - Mac OS X.
46 - Android.
47 - Microsoft Windows 2000/XP/Vista/7/8
48
49 The only officially supported compilers are gcc (4.7 or newer) and clang
50 (3.4 or newer). On Windows, gcc is usually available as MinGW; compilation
51 with MSVC (Microsoft Visual Studio 2013) is supported.
52
53 There's no reason Crawl shouldn't work on other modern systems, especially
54 Unixy ones, although some porting may be needed.
55
56 Windows 9X and ME are no longer supported; you might have some luck using
57 cygwin but a native build is probably a lost cause.
58
59
60 Source Code Checkout
61 --------------------
62
63 If you don't already have the source code downloaded (in the form of a .zip
64 or .tar.bz2 file), you can obtain the latest source code from Git. MinGW
65 users can obtain Git by installing msysgit (described in the MinGW section).
66 Linux users can just install the 'git' or 'git-core' package with whatever
67 package manager they use. Note that there used to be another package called
68 'git' (now 'gnuit') going around which stands for 'GNU interactive tools'.
69 This is not what you want.
70
71 Once you have Git installed, you just need to do:
72
73     git clone https://github.com/crawl/crawl.git
74
75 And then to get the contributing libraries, enter the newly cloned
76 repository via 'cd crawl' and type:
77
78     git submodule update --init
79
80 This should get you all you need to build Crawl from source.
81
82
83 Optional libraries
84 ------------------
85
86 Crawl can be built with some optional features:
87
88 * Sounds
89 * User Lua scripts
90
91 Crawl Stone Soup also uses a level compiler to compile special level
92 definitions; to make changes to the level compiler, you'll need the flex and
93 bison/byacc tools (Other lex/yaccs may also work). More details are
94 available below.
95
96 Sound can be provided by SDL2_mixer (the default), by WINMM on Windows
97 (defined by WINMM_PLAY_SOUNDS in AppHdr.h), or by an external command on
98 Unix systems (SOUND_PLAY_COMMAND in AppHdr.h). To enable this, append
99 SOUND=y to the make invocation.
100
101 Stone Soup 0.6+ includes Lua 5.1.4 in its submodules. Crawl uses Lua for
102 dungeon generation. In addition, Crawl has a (rudimentary) Lua interface
103 for users to run scripts which can do things such as conditionalise parts of
104 the .crawlrc/init.txt. Such user Lua scripts are enabled by default, but
105 can be turned off by appending NO_LUA_BINDINGS=y to the make invocation.
106
107
108 Building on Unix (Linux, *BSD, Solaris, etc.)
109 ---------------------------------------------
110
111 To install or not to install:
112
113 If only one user on the system (you) is going to be playing Crawl, you do
114 not need to use "make install". A simple "make" will build Crawl in the
115 source directory, where you can run it as "./crawl".
116
117
118 Prerequisites (Debian):
119
120 On Debian-based systems (Ubuntu, Mint, ...), you can get all dependencies by
121 typing the following as root/sudo:
122 apt-get install build-essential libncursesw5-dev bison flex liblua5.1-0-dev \
123   libsqlite3-dev libz-dev pkg-config libsdl2-image-dev libsdl2-mixer-dev    \
124   libsdl2-dev libfreetype6-dev libpng-dev ttf-dejavu-core
125 (the last five are needed only for tiles builds). This is the complete set,
126 with it you don't have a need for the bundled "contribs".
127
128 If you are going to be rebuilding after doing small changes a lot, it is
129 recommended that you also install and configure ccache and binutils-gold:
130 apt-get install ccache binutils-gold
131 less /usr/share/doc/ccache/README.Debian
132
133
134 Prerequisites (Fedora):
135
136 On Fedora, and possibly other RPM-based systems, you can get the dependencies
137 by running the following as root:
138 yum install gcc gcc-c++ make bison flex ncurses-devel lua-devel sqlite-devel \
139   zlib-devel pkgconfig SDL-devel SDL_image-devel libpng-devel freetype-devel \
140   dejavu-sans-fonts dejavu-sans-mono-fonts
141 (the last six are needed only for tile builds). As with Debian, this package
142 list avoids the need for the bundled "contribs". For Fedora 20 or later,
143 replace lua-devel by compat-lua-devel.
144
145 ccache can be installed with:
146 yum install ccache
147
148
149 Prerequisites (other systems):
150
151 GNU gcc and g++, GNU make, libncursesw or libcursesw. You need the development
152 headers for ncurses - they may not be installed by default on some Unixes.
153
154 For tile builds, you need FreeDesktop's pkg-config, X11 and opengl headers.
155 The latter are likely to come from mesa sources.
156
157 flex and bison are optional but highly recommended. Recent versions of byacc
158 are also fine (edit your makefile appropriately).
159
160 You need to link with a curses library that understands Unicode characters,
161 usually named libncursesw (the development headers for libncursesw are
162 usually in /usr/include/ncursesw).
163
164
165 Building:
166
167 * cd to the source directory.
168
169 * Most users can simply type 'make' without any extra flags, and get a
170   working build as a result. If just typing 'make' works for you, then you
171   shouldn't need to read any further. BSD and Solaris users may have to use
172   'gmake' instead of 'make'.
173
174 * If you want a graphical (tiled) build, then you should add 'TILES=y' to
175   the 'make' command-line, like so:
176
177     make TILES=y
178
179   Note that the graphical build requires that you have development libraries
180   installed for SDL, SDL_image, libpng, zlib, and freetype. If your system
181   doesn't have these installed, you can usually get them via your package
182   manager (apt-get, emerge, yum, etc).
183
184   If you would rather, you can go to the source/contrib directory and type
185   'make', and the required libraries should be built for you.
186
187 * If you want to install Crawl system-wide rather than play from the build
188   directory, you need to specify a directory to hold the save and data files.
189   Specifying a prefix of /usr or /usr/local will default SAVEDIR to
190   "~/.crawl" and DATADIR to share/crawl (relative to the prefix).
191   SAVEDIR must be writeable and owned by the user running crawl, so except
192   for special cases it should be inside "~" (home directory).
193
194 * If you're installing Crawl for multiple users, run 'make install' as root.
195   Crawl will be copied into the directory specified by 'prefix' (see above).
196   The data directory will be created if necessary, and the level layout,
197   tile and help files will be copied there.
198
199 * If you do not want players to be able to script Crawl with Lua, add
200   'NO_LUA_BINDINGS=y' to the 'make' command-line. This removes functionality
201   like autofight, and Lua scripts have been enabled on public servers for
202   many years without any security issues, so there is no real reason to do
203   so.
204
205
206 Building on Mac OS X
207 --------------------
208
209 Before building on Mac OS X, you need a working copy of Xcode and the
210 associated command line tools. For recent versions of OS X, Xcode can be
211 installed through the AppStore as a free download; the associated command
212 line tools can then be installed by opening Xcode, opening the Preferences
213 dialog, and clicking Install on the Command Line Tools line in the Download
214 tab.
215
216 Mac builds then use the Unix build process described above, but require you
217 to add 'APPLE_GCC=y' to the 'make' command-line. In addition, to build the
218 graphical version of Crawl, you must add 'NO_PKGCONFIG=y' and
219 'CONTRIB_SDL=y'.
220
221 So, to build build Crawl on a Mac you could use the following example
222 command lines.
223
224 For the console version:
225   make APPLE_GCC=y
226 For the graphical version:
227   make APPLE_GCC=y NO_PKGCONFIG=y CONTRIB_SDL=y TILES=y
228
229
230 Building on Windows (MinGW)
231 ---------------------------
232
233 NOTE: You cannot build Windows binaries on Windows 9x/ME using MinGW. On
234 9x/ME, you can use the Cygwin build instructions, or build a binary on a
235 Windows NT/2k/XP system (although it would require a good bit of porting to
236 run on 9x).
237
238 * To build Crawl on Windows, first download and install msysgit. msysgit is
239   a full MinGW setup that even includes Git (which happens to be the source
240   code management system used by the Crawl team). To get msysgit, click on
241   the 'Download msysGit" button here:
242
243     http://msysgit.github.io/#contribute
244
245   Do not use the download button at the top of the page; that package does
246   not contain make or g++.
247   NOTE: msysgit should be installed to a path that does not contain spaces,
248         such as the default location 'c:\msysgit'.
249
250 * The default msysgit has an old version of GCC can't handle C++11. To
251   update yours, Win-builds is recommended.
252
253 Upgrading GCC with Win-builds:
254
255 Follow steps 2-4 of the 'Installation For Use With MSYS or Cygwin' instructions
256 from the win-builds.org website, currently at:
257
258 http://win-builds.org/1.5.0/msys-cygwin.html
259
260 Skip step 1 of the instructions, since you already have MSYS installed through
261 msysgit, and skip step 5 since you'll be compiling Crawl next.
262
263 For step 2 of the instructions, run the installer exe after downloading
264 it. You'll need to select the 'System to install for' and the architecture.
265
266 For the system, choose the 'Cygwin or MSYS' option and enter the path to the
267 folder where you installed msysgit, which is usually 'c:\msysgit'.
268
269 For the architecture, the installer should automatically detect this, in which
270 case note it now so you know which command you need to run in step 3 of the
271 Win-build instructions. If you're unsure which architecture you have, exit the
272 installer, start Msys by running 'c:\msysgit\msys.bat', and execute the command
273 'gcc -v'. Note the output line that reads e.g. Target: i686-w64-mingw32' or
274 'Target: x86_64-w64-mingw32' to indicate whether you have i686 or x86_64.
275
276 After choosing the system and architecture, click Ok and then Process on the
277 next screen to install the Win-builds packages. This will take some time to
278 download and install. You can close the installer after the installation is
279 finished.
280
281 For step 3 of the instructions, start msys by running 'c:\msysgit\msys.bat',
282 and run the appropriate command out of the two given, based on the architecture
283 you used/determined in step 2.
284
285 It's a good idea to follow step 4 of the instructions so that the Win-builds
286 version of GCC is selected every time you start MSYS.
287
288 After completing the instructions, check that you have an updated GCC in MSYS
289 by running the command 'gcc --version'. The version should be 4.8 or higher. If
290 the version is not at least 4.8, run the command 'which gcc', and check that
291 the path used for GCC is either '/opt/windows_32/bin/gcc' or
292 '/opt/windows_64/bin/gcc', depending on your system. If not, you're still using
293 the older GCC shipped with msysgit. In that case make sure you followed step 3
294 correctly to activate the Win-builds GCC.
295
296 Running MSYS and building Crawl:
297
298 * Start MSYS by running 'c:\msysgit\msys.bat'. This gives you the MinGW/MSYS
299   build environment.
300
301 * cd to the Crawl source directory. For instance, if you have the crawl sources
302   in c:\crawl\source, you would type 'cd /c/crawl/source'.
303
304 * Build Crawl by running 'make NO_PKGCONFIG=y'. If you want a graphical build,
305   you will need to add ' TILES=y' on the 'make' command line.
306
307 * When the process finishes, you should be able to run crawl right from the
308   source directory by typing './crawl'
309
310 * If you get a message about missing SDL.h even though you do have contribs
311   installed, your version of msys may suffer from a bug that has been fixed
312   since. Please either update msys, or delete /mingw/bin/sdl-config so it
313   won't interfere with the copy shipped with Crawl.
314
315 * For you stubborn types who insist on using separate msys and git installs,
316   make sure git.exe is in your PATH when trying to build from git! Otherwise,
317   util/gen_ver.pl will most likely fail to generate build.h.
318
319 NOTE: You may be able to omit 'NO_PKGCONFIG=y' in the make command to use
320 libraries that are shipped with Win-builds instead of compiling the contrib
321 libraries in the Crawl source. Using 'NO_PKGCONFIG=y' will increase compilation
322 time the first time Crawl is compiled, but it means fewer potential build
323 problems. The contrib libraries are changed infrequently, so subsequent
324 compilations will be faster as contribs won't require recompilation. If you do
325 want to use the Win-builds libraries and omit NO_PKGCONFIG=y, you will likely
326 still need to use some of the Crawl contribs, which you can enable by adding
327 any of the following make arguments (alone or in combination):
328
329   BUILD_LUA=y BUILD_ZLIB=y BUILD_SQLITE=y BUILD_SDL2=y BUILD_SDL2IMAGE=y
330
331
332 Building on Windows (cygwin)
333 ----------------------------
334
335 * Get Cygwin from http://www.cygwin.com/. When installing, ensure that the
336   following packages are selected: gcc, g++, make, flex, bison,
337   libncurses-devel. If you'd like to build from git, install the git-core
338   package. You may also want to install diff, patch, and other such tools.
339
340 * Once Cygwin is installed, open a Cygwin bash shell (use the Start menu or
341   desktop icon, do not double-click bash.exe in Explorer).
342
343 * cd to the the Crawl source directory. For instance, if you have the crawl
344   sources in c:\crawl\source, you would type 'cd /cygdrive/c/crawl/source'.
345
346 * Follow the Linux build instructions to build Crawl.
347
348 Building on Windows (MSVC)
349 --------------------------
350
351 * If you do not have Visual Studio 2012 you can get the free Express edition
352   (for Desktop) from http://www.microsoft.com/visualstudio/eng/downloads
353   (look for Visual Studio Express 2012 for Windows Desktop).
354
355 * You'll need a perl environment, there are links to several Windows binaries
356   you can choose from at http://www.perl.org/get.html
357
358 * In the Crawl source, run gen-all.cmd which is in source/util/. This step
359   must be executed any time you update to a new version of the source (or
360   if you have modified tile data or unrandarts).
361
362 * The first time you compile, you need to build the Contribs solution. This
363   compiles various libraries which crawl itself needs to build. This only
364   needs to be performed the first time you build, or if the contribs are
365   ever updated (extremely rare). To do this open and compile Contribs.sln
366   in source/contrib.
367
368 * Open crawl-ref.sln in Visual Studio, this is in source/MSVC/.
369
370 * You can now select Debug or Release from the drop-down build configurations
371   menu on the main toolbar (it should be next to "Local Windows Debugger");
372   crawl.exe can them be compiled by selecting "Build Solution" in the BUILD
373   menu. You can quickly run it by selecting "Start without Debugging" in the
374   debug menu (or debug with "Start Debugging" but the game will run extremely
375   slowly). Note: the Release build can still be debugged using the Visual
376   Studio debugger.
377
378 * Better support for Python (for the webserver project) and Lua (for the dat
379   project) can be installed with these extensions:
380
381   Python Tools for Visual Studio
382   http://pytools.codeplex.com/releases
383
384   Ports of VsLua to Visual Studio 2012
385   http://www.dbfinteractive.com/forum/index.php?topic=5873.0
386   http://pouet.net/topic.php?which=9087
387
388   Try at your own risk, but the first one has been tested and found to be
389   effective.
390
391 Building Tiles versions
392 -----------------------
393
394 * On most platforms, you can simply type:
395     make TILES=y
396
397 * If you compiled the ASCII binary before, you'll need to run 'make clean'
398   before running 'make'.
399
400 * All platforms require the same prerequisites listed in the other sections
401   above for building each of these platforms.
402
403 * All platforms additionally require the development versions of the
404   following software packages installed.
405
406     * SDL2 (http://www.libsdl.org/download-1.2.php)
407     * SDL2_image (http://www.libsdl.org/projects/SDL_image/)
408     * libpng (http://www.libpng.org/pub/png/libpng.html)
409     * Freetype 2 (http://www.freetype.org/download.html)
410
411   On Linux, these can be installed via a package manager (apt-get, emerge,
412   yum, etc).
413
414   On Mac OS X, these will be compiled automatically when you build the Xcode
415   project.
416
417   On Windows (MinGW or Cygwin), these will be compiled as needed when you
418   run 'make TILES=y'.
419
420 * If you want both ASCII and Tiles binaries you need to compile them
421   separately, rename one of them, and copy them into the same Crawl
422   directory.
423
424
425 *****************************************************************************
426 Data files
427 ----------
428
429 Crawl looks for several data files when starting up. They include:
430
431 * Special level and vault layout (dat/*.des) files.
432 * Core Lua code (dat/dlua/*.lua).
433 * Descriptions for monsters and game features (dat/descript/*.txt).
434 * Definitions for monster dialogue and randart names (dat/database/*.txt).
435
436 All these files are in the source tree under source/dat.
437
438 Crawl will also look for documentation files when players invoke the help
439 system. These files are available under the docs directory.
440
441 Your built Crawl binary must be able to find these files, or it will not
442 start.
443
444 If Crawl is built without an explicit DATA_DIR_PATH (this is the most common
445 setup), it will search for its data files under the current directory, and
446 if it can't find them there, one level above the current directory. In
447 short, it uses these search paths: ., ./dat, ./docs, .., ../dat, ../docs.
448
449
450 *****************************************************************************
451
452 The level compiler
453 ------------------
454
455 Crawl uses a level compiler to read the level design (.des) files in the
456 source/dat directory.
457
458 If you're using one of standard makefile, the steps described in this
459 section are performed automatically:
460
461 The level compiler source is in the source/util directory (levcomp.lpp and
462 levcomp.ypp). The steps involved in building the level compiler are:
463
464 * Run flex on levcomp.lpp to produce the levcomp.lex.cc lexer.
465 * Run bison on levcomp.ypp to produce the levcomp.tab.cc parser and
466   levcomp.tab.h
467 * Compile the resulting C++ source files and levcomp.cc and link the object
468   files into the Crawl executable.
469
470 For convenience on systems that don't have flex/bison, pre-generated
471 intermediate files are provided under source/prebuilt. The makefiles
472 provided with the Crawl source distribution will use these pre-generated
473 files automatically if flex/bison is not available.
474
475
476 *****************************************************************************
477 Optional Libraries (Lua and PCRE)
478 ---------------------------------
479
480 Lua
481 ---
482
483 Security on multiuser systems (Unix):
484
485 As of 0.8, setuid and setgid installs are no longer supported, thus any
486 previous concerns are no longer applicable. Lua user scripts are sandboxed
487 and should be generally safe even on public servers (besides increasing the
488 attack surface).
489
490 As of 0.3, the Lua source is included with Crawl. It will be used if you
491 don't have Lua headers installed. Note that we don't provide security
492 support for Lua, and thus if you run a public server or a kiosk, it is
493 strongly recommended to use system Lua which does receive security updates
494 from whatever distribution you use.
495
496
497 PCRE
498 ----
499 As of 0.6.0, PCRE 7.9 source is included with Crawl. It is enabled by
500 default. The sources in contrib/pcre are identical to the 7.9 distro except
501 for the use of a custom-made Makefile instead of the automake system that
502 was in place previously.
503
504 On Unixes, you're better served by the existing POSIX regular expression
505 support. If you want PCRE, your package management system is again your
506 best bet. Remember to install development headers, not just the plain
507 library.
508
509
510 Unicode
511 -------
512 As of 0.8, Unicode support is included in all ports. Still, you might need
513 to ensure your terminal can display non-basic glyphs.
514
515 On Unix, you want an UTF-8 locale. All modern distributions install one by
516 default, but you might have somehow dropped required settings. To check
517 this, run "locale charmap", which should say "UTF-8". If it's not, please
518 ensure either LANG, LC_ALL or LC_CTYPE is set. A typical line would be
519 "export LC_ALL=en_US.UTF-8".
520
521 On Windows, the console behaves differently for TrueType and legacy (bitmap)
522 fonts. The latter (mostly) work only on certain language editions of
523 Windows, such as English, and even there, they work adequately only for
524 Crawl's default settings. For anything more, please select one of TrueType
525 fonts. If, like one of our players, you are deeply attached to the looks of
526 bitmap fonts, you can download a corrected version of the Terminal font from
527 http://www.yohng.com/software/terminalvector.html