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