Revert "Make strength useless for melee."
[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.1 or newer) and clang
50 (3.0 or newer), with strong preference for the former.  On Windows, gcc is
51 usually available as MinGW; and as of version 0.13, compilation with MSVC
52 (Microsoft Visual Studio 2012 both Full or Express editions) is supported.
53
54 There's no reason Crawl shouldn't work on other modern systems, especially
55 Unixy ones, although some porting may be needed.
56
57 Windows 9X and ME are no longer supported; you might have some luck using
58 cygwin but a native build is probably a lost cause.
59
60
61 Source Code Checkout
62 --------------------
63
64 If you don't already have the source code downloaded (in the form of a .zip
65 or .tar.bz2 file), you can obtain the latest source code from Git.  MinGW
66 users can obtain Git by installing msysgit (described in the MinGW section).
67 Linux users can just install the 'git' or 'git-core' package with whatever
68 package manager they use.  Note that there used to be another package called
69 'git' (now 'gnuit') going around which stands for 'GNU interactive tools'.
70 This is not what you want.
71
72 Once you have Git installed, you just need to do:
73
74     git clone git://gitorious.org/crawl/crawl.git
75
76 And then to get the contributing libraries, enter the newly cloned
77 repository via 'cd crawl' and type:
78
79     git submodule update --init
80
81 This should get you all you need to build Crawl from source.
82
83
84 Optional libraries
85 ------------------
86
87 Crawl can be built with some optional features:
88
89 * Sounds
90 * User Lua scripts
91
92 Crawl Stone Soup also uses a level compiler to compile special level
93 definitions; to make changes to the level compiler, you'll need the flex and
94 bison/byacc tools (Other lex/yaccs may also work).  More details are
95 available below.
96
97 Sounds must be enabled by editing AppHdr.h (uncomment SOUND_PLAY_COMMAND on
98 Unixes or WINMM_PLAY_SOUNDS on Windows).
99
100 Stone Soup 0.6 includes Lua 5.1.4 in its source tree. Crawl uses Lua for
101 dungeon generation.  In addition, Crawl has a (rudimentary) Lua interface
102 for users to run scripts which can do things such as conditionalise parts of
103 the .crawlrc/init.txt.  Such user Lua scripts are enabled by default, but
104 can be turned off by appending NO_LUA_BINDINGS=y to the make invocation.
105
106
107 Building on Unix (Linux, *BSD, Solaris, etc.)
108 ---------------------------------------------
109
110 To install or not to install:
111
112 If only one user on the system (you) is going to be playing Crawl, you do
113 not need to use "make install".  A simple "make" will build Crawl in the
114 source directory, where you can run it as "./crawl".
115
116
117 Prerequisites (Debian):
118
119 On Debian-based systems (Ubuntu, Mint, ...), you can get all dependencies by
120 typing the following as root/sudo:
121 apt-get install build-essential libncursesw5-dev bison flex liblua5.1-0-dev \
122   libsqlite3-dev libz-dev pkg-config libsdl-image1.2-dev libsdl1.2-dev      \
123   libfreetype6-dev libpng-dev ttf-dejavu-core
124 (the last five are needed only for tiles builds).  This is the complete set,
125 with it you don't have a need for the bundled "contribs".
126
127 If you are going to be rebuilding after doing small changes a lot, it is
128 recommended that you also install and configure ccache and binutils-gold:
129 apt-get install ccache binutils-gold
130 less /usr/share/doc/ccache/README.Debian
131
132
133 Prerequisites (Fedora):
134
135 On Fedora, and possibly other RPM-based systems, you can get the dependencies
136 by running the following as root:
137 yum install gcc gcc-c++ make bison flex ncurses-devel lua-devel sqlite-devel \
138   zlib-devel pkgconfig SDL-devel SDL_image-devel libpng-devel freetype-devel \
139   dejavu-sans-fonts dejavu-sans-mono-fonts
140 (the last six are needed only for tile builds).  As with Debian, this package
141 list avoids the need for the bundled "contribs".  For Fedora 20 or later,
142 replace lua-devel by compat-lua-devel.
143
144 ccache can be installed with:
145 yum install ccache
146
147
148 Prerequisites (other systems):
149
150 GNU gcc and g++, GNU make, libncursesw or libcursesw. You need the development
151 headers for ncurses - they may not be installed by default on some Unixes.
152
153 For tile builds, you need FreeDesktop's pkg-config, X11 and opengl headers.
154 The latter are likely to come from mesa sources.
155
156 flex and bison are optional but highly recommended. Recent versions of byacc
157 are also fine (edit your makefile appropriately).
158
159 You need to link with a curses library that understands Unicode characters,
160 usually named libncursesw (the development headers for libncursesw are
161 usually in /usr/include/ncursesw).
162
163
164 Building:
165
166 * cd to the source directory.
167
168 * Most users can simply type 'make' without any extra flags, and get a
169   working build as a result.  If just typing 'make' works for you, then you
170   shouldn't need to read any further.  BSD and Solaris users may have to use
171   'gmake' instead of 'make'.
172
173 * If you want a graphical (tiled) build, then you should add 'TILES=y' to
174   the 'make' command-line, like so:
175
176     make TILES=y
177
178   Note that the graphical build requires that you have development libraries
179   installed for SDL, SDL_image, libpng, zlib, and freetype.  If your system
180   doesn't have these installed, you can usually get them via your package
181   manager (apt-get, emerge, yum, etc).
182
183   If you would rather, you can go to the source/contrib directory and type
184   'make', and the required libraries should be built for you.
185
186 * If you want to install Crawl system-wide rather than play from the build
187   directory, you need to specify a directory to hold the save and data files.
188   Specifying a prefix of /usr or /usr/local will default SAVEDIR to
189   "~/.crawl" and DATADIR to share/crawl (relative to the prefix).
190   SAVEDIR must be writeable and owned by the user running crawl, so except
191   for special cases it should be inside "~" (home directory).
192
193 * If you're installing Crawl for multiple users, run 'make install' as root.
194   Crawl will be copied into the directory specified by 'prefix' (see above).
195   The data directory will be created if necessary, and the level layout,
196   tile and help files will be copied there.
197
198 * If you do not want players to be able to script Crawl with Lua, add
199   'NO_LUA_BINDINGS=y' to the 'make' command-line. This removes functionality
200   like autofight, and Lua scripts have been enabled on public servers for
201   many years without any security issues, so there is no real reason to do
202   so.
203
204
205 Building on Mac OS X
206 --------------------
207
208 Before building on Mac OS X, you need a working copy of Xcode and the
209 associated command line tools. For recent versions of OS X, Xcode can be
210 installed through the AppStore as a free download; the associated command
211 line tools can then be installed by opening Xcode, opening the Preferences
212 dialog, and clicking Install on the Command Line Tools line in the Download
213 tab.
214
215 Mac builds then use the Unix build process described above, but require you
216 to add 'APPLE_GCC=y' to the 'make' command-line. In addition, to build the
217 graphical version of Crawl, you must add 'NO_PKGCONFIG=y' and
218 'CONTRIB_SDL=y'.
219
220 So, to build build Crawl on a Mac you could use the following example
221 command lines.
222
223 For the console version:
224   make APPLE_GCC=y
225 For the graphical version:
226   make APPLE_GCC=y NO_PKGCONFIG=y CONTRIB_SDL=y TILES=y
227
228
229 Building on Windows (MinGW)
230 ---------------------------
231
232 NOTE: You cannot build Windows binaries on Windows 9x/ME using MinGW. On
233 9x/ME, you can use the Cygwin build instructions, or build a binary on a
234 Windows NT/2k/XP system (although it would require a good bit of porting to
235 run on 9x).
236
237 * To build Crawl on Windows, first download and install msysgit. msysgit is
238   a full MinGW setup that even includes Git (which happens to be the source
239   code management system used by the Crawl team). To get msysgit, download
240   'msysGit-netinstall' from here:
241
242     http://code.google.com/p/msysgit/downloads/list?q=net+installer
243
244   NOTE: msysgit should be installed to a path that does not contain spaces,
245         such as the default location 'c:\msysgit'.
246
247 * Start msys by running 'c:\msysgit\msys.bat'. Now you're in a MinGW build
248   environment.
249
250 * cd to the the Crawl source directory. For instance, if you have the crawl
251   sources in c:\crawl\source, you would type 'cd /c/crawl/source'.
252
253 * Build Crawl by running 'make'. If you want a graphical build, you will
254   need to add 'TILES=y' on the 'make' command line.
255
256 * When the process finishes, you should be able to run crawl right from the
257   source directory by typing './crawl'
258
259 * If you get a message about missing SDL.h even though you do have contribs
260   installed, your version of msys may suffer from a bug that has been fixed
261   since.  Please either update msys, or delete /mingw/bin/sdl-config so it
262   won't interfere with the copy shipped with Crawl.
263
264 * For you stubborn types who insist on using separate msys and git installs,
265   make sure git.exe is in your PATH when trying to build from git! Otherwise,
266   util/gen_ver.pl will most likely fail to generate build.h.
267
268 Building on Windows (cygwin)
269 ----------------------------
270
271 * Get Cygwin from http://www.cygwin.com/. When installing, ensure that the
272   following packages are selected: gcc, g++, make, flex, bison,
273   libncurses-devel.  If you'd like to build from git, install the git-core
274   package.  You may also want to install diff, patch, and other such tools.
275
276 * Once Cygwin is installed, open a Cygwin bash shell (use the Start menu or
277   desktop icon, do not double-click bash.exe in Explorer).
278
279 * cd to the the Crawl source directory. For instance, if you have the crawl
280   sources in c:\crawl\source, you would type 'cd /cygdrive/c/crawl/source'.
281
282 * Follow the Linux build instructions to build Crawl.
283
284 Building on Windows (MSVC)
285 --------------------------
286
287 * If you do not have Visual Studio 2012 you can get the free Express edition
288   (for Desktop) from http://www.microsoft.com/visualstudio/eng/downloads
289   (look for Visual Studio Express 2012 for Windows Desktop).
290
291 * You'll need a perl environment, there are links to several Windows binaries
292   you can choose from at http://www.perl.org/get.html
293
294 * In the Crawl source, run gen-all.cmd which is in source/util/. This step
295   must be executed any time you update to a new version of the source (or
296   if you have modified tile data or unrandarts).
297
298 * The first time you compile, you need to build the Contribs solution. This
299   compiles various libraries which crawl itself needs to build. This only
300   needs to be performed the first time you build, or if the contribs are
301   ever updated (extremely rare). To do this open and compile Contribs.sln
302   in source/contrib.
303
304 * Open crawl-ref.sln in Visual Studio, this is in source/MSVC/.
305
306 * You can now select Debug or Release from the drop-down build configurations
307   menu on the main toolbar (it should be next to "Local Windows Debugger");
308   crawl.exe can them be compiled by selecting "Build Solution" in the BUILD
309   menu. You can quickly run it by selecting "Start without Debugging" in the
310   debug menu (or debug with "Start Debugging" but the game will run extremely
311   slowly). Note: the Release build can still be debugged using the Visual
312   Studio debugger.
313
314 * Better support for Python (for the webserver project) and Lua (for the dat
315   project) can be installed with these extensions:
316
317   Python Tools for Visual Studio
318   http://pytools.codeplex.com/releases
319
320   Ports of VsLua to Visual Studio 2012
321   http://www.dbfinteractive.com/forum/index.php?topic=5873.0
322   http://pouet.net/topic.php?which=9087
323
324   Try at your own risk, but the first one has been tested and found to be
325   effective.
326
327 Building Tiles versions
328 -----------------------
329
330 * On most platforms, you can simply type:
331     make TILES=y
332
333 * If you compiled the ASCII binary before, you'll need to run 'make clean'
334   before running 'make'.
335
336 * All platforms require the same prerequisites listed in the other sections
337   above for building each of these platforms.
338
339 * All platforms additionally require the development versions of the
340   following software packages installed.
341
342     * SDL (http://www.libsdl.org/download-1.2.php)
343     * SDL_image (http://www.libsdl.org/projects/SDL_image/)
344     * libpng (http://www.libpng.org/pub/png/libpng.html)
345     * Freetype 2 (http://www.freetype.org/download.html)
346
347   On Linux, these can be installed via a package manager (apt-get, emerge,
348   yum, etc).
349
350   On Mac OS X, these will be compiled automatically when you build the Xcode
351   project.
352
353   On Windows (MinGW or Cygwin), these will be compiled as needed when you
354   run 'make TILES=y'.
355
356 * If you want both ASCII and Tiles binaries you need to compile them
357   separately, rename one of them, and copy them into the same Crawl
358   directory.
359
360
361 *****************************************************************************
362 Data files
363 ----------
364
365 Crawl looks for several data files when starting up. They include:
366
367 * Special level and vault layout (dat/*.des) files.
368 * Core Lua code (dat/dlua/*.lua).
369 * Descriptions for monsters and game features (dat/descript/*.txt).
370 * Definitions for monster dialogue and randart names (dat/database/*.txt).
371
372 All these files are in the source tree under source/dat.
373
374 Crawl will also look for documentation files when players invoke the help
375 system.  These files are available under the docs directory.
376
377 Your built Crawl binary must be able to find these files, or it will not
378 start.
379
380 If Crawl is built without an explicit DATA_DIR_PATH (this is the most common
381 setup), it will search for its data files under the current directory, and
382 if it can't find them there, one level above the current directory.  In
383 short, it uses these search paths: ., ./dat, ./docs, .., ../dat, ../docs.
384
385
386 *****************************************************************************
387
388 The level compiler
389 ------------------
390
391 Crawl uses a level compiler to read the level design (.des) files in the
392 source/dat directory.
393
394 If you're using one of standard makefile, the steps described in this
395 section are performed automatically:
396
397 The level compiler source is in the source/util directory (levcomp.lpp and
398 levcomp.ypp).  The steps involved in building the level compiler are:
399
400 * Run flex on levcomp.lpp to produce the levcomp.lex.cc lexer.
401 * Run bison on levcomp.ypp to produce the levcomp.tab.cc parser and
402   levcomp.tab.h
403 * Compile the resulting C++ source files and levcomp.cc and link the object
404   files into the Crawl executable.
405
406 For convenience on systems that don't have flex/bison, pre-generated
407 intermediate files are provided under source/prebuilt.  The makefiles
408 provided with the Crawl source distribution will use these pre-generated
409 files automatically if flex/bison is not available.
410
411
412 *****************************************************************************
413 Optional Libraries (Lua and PCRE)
414 ---------------------------------
415
416 Lua
417 ---
418
419 Security on multiuser systems (Unix):
420
421 As of 0.8, setuid and setgid installs are no longer supported, thus any
422 previous concerns are no longer applicable.  Lua user scripts are sandboxed
423 and should be generally safe even on public servers (besides increasing the
424 attack surface).
425
426 As of 0.3, the Lua source is included with Crawl.  It will be used if you
427 don't have Lua headers installed.  Note that we don't provide security
428 support for Lua, and thus if you run a public server or a kiosk, it is
429 strongly recommended to use system Lua which does receive security updates
430 from whatever distribution you use.
431
432
433 PCRE
434 ----
435 As of 0.6.0, PCRE 7.9 source is included with Crawl.  It is enabled by
436 default.  The sources in contrib/pcre are identical to the 7.9 distro except
437 for the use of a custom-made Makefile instead of the automake system that
438 was in place previously.
439
440 On Unixes, you're better served by the existing POSIX regular expression
441 support.  If you want PCRE, your package management system is again your
442 best bet.  Remember to install development headers, not just the plain
443 library.
444
445
446 Unicode
447 -------
448 As of 0.8, Unicode support is included in all ports.  Still, you might need
449 to ensure your terminal can display non-basic glyphs.
450
451 On Unix, you want an UTF-8 locale.  All modern distributions install one by
452 default, but you might have somehow dropped required settings.  To check
453 this, run "locale charmap", which should say "UTF-8".  If it's not, please
454 ensure either LANG, LC_ALL or LC_CTYPE is set.  A typical line would be
455 "export LC_ALL=en_US.UTF-8".
456
457 On Windows, the console behaves differently for TrueType and legacy (bitmap)
458 fonts.  The latter (mostly) work only on certain language editions of
459 Windows, such as English, and even there, they work adequately only for
460 Crawl's default settings.  For anything more, please select one of TrueType
461 fonts.  If, like one of our players, you are deeply attached to the looks of
462 bitmap fonts, you can download a corrected version of the Terminal font from
463 http://www.yohng.com/software/terminalvector.html