Further stab refactoring
[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. MSYS2 users
61 should have Git if they followed the installation instructions in the MSYS2
62 section. Linux users can just install the 'git' or 'git-core' package with
63 whatever package manager they use. Note that there used to be another package
64 called 'git' (now 'gnuit') going around which stands for 'GNU interactive
65 tools'. This is not what you 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 (MSYS2)
222 ---------------------------
223
224 MSYS2 which is a Cygwin-derived software distro for Windows that can build
225 native applications. We recommend Windows users try this method first for
226 compiling crawl, since it is tested by our active Windows developers. You can
227 download the MSYS2 installer from the following website:
228
229 https://msys2.github.io/
230
231 Follow all of the steps you see on that page to install MSYS2, but please read
232 the additional notes below. The note for after Step 6 is particularly important
233 to be able to start the MSYS2 shell.
234
235 * Download and run the MSYS2 installer exe at the top that is appropriate for
236   your processor, either the 32-bit or 64-bit. The 32-bit installer file has
237   the prefix 'msys2-i686', and the 64-bit version has the prefix
238   'msys2-x86_64'. Most modern systems have 64-bit processors, but you can check
239   your system under Start->About this Computer or (e.g. Windows 10)
240   Start->Settings->About.
241
242 * The installer will put all MSYS2/MinGW files into a folder of your choice,
243   which defaults to 'C:\msys64'. You should not reuse any previous folder made
244   with previous installs of MSYS (from msysgit and/or win-builds.org) or MSYS2
245   (from Git for Windows SDK). However if you have crawl-related work files from
246   such directories that you'd like to carry over, you can copy them to
247   e.g. 'C:\msys64\home\<Username>', where <Username> is your Windows
248   username. This is the path to your home directory in this new MSYS2
249   installation.
250
251 * After Step 6, where you update the installed packages, you'll see an update
252   message telling you to close the MSYS2 terminal and to update the Windows
253   shortcuts used to start MSYS2. The shortcut you'll use to start MSYS2 will be
254   either 'MinGW-w64 Win64 Shell' (64-bit systems) or 'MinGW-w64 Win32 Shell'
255   (32-bit systems), both of which you can find under the MSYS2 group in your
256   Start menu Applications list.
257
258   You need to change the Target of this shortcut. On some systems you can
259   Right-click the shortcut and choosing Properties, and on later systems
260   (e.g. Windows 10), you Right-click, choose More->Open File Location,
261   right-click the file in the File manager window that appears, and then choose
262   Properties. From the Properties dialog, update the Target field according to
263   the message you saw in Step 6. For 64-bit systems, the necessary Target
264   should look like:
265
266   C:\msys64\msys2_shell.cmd -mingw64
267
268   For 32-bit systems:
269
270   C:\msys64\msys2_shell.cmd -mingw32
271
272   NOTE: The update message refers to a Target of 'MSYS2_ROOT\msys2_shell.cmd',
273   but the 'MSYS2_ROOT' in this path should be replaced with the directory where
274   you installed MSYS2, which by default is 'C:\msys64'.
275
276 * After updating the shortcut above, you must close the MSYS2 shell and restart
277   it from the shortcut you've updated. Run the final update in Step 7 before
278   proceeding to the steps below. You can start the MSYS2 shell at any time
279   using the updated shortcut.
280
281   NOTE: You generally don't want to use the shortcut called 'MSYS2 Shell', as
282   this starts a shell for working with Cygwin-based MSYS2 components. Building
283   crawl in this environment is currently not supported.
284
285 Install Git and the development packages, and compile crawl:
286
287 * To install git and the base development packages, run the following command
288   from the MSYS2 shell:
289
290   pacman -S base-devel git
291
292   Accept the default action to install all packages in base-devel, and say yes
293   to any questions about installing packages or removing packages due to
294   conflicts.
295
296 * Install the mingw-w64 gcc toolchain for your system. For a 64-bit system,
297   run:
298
299   pacman -S mingw-w64-x86_64-toolchain
300
301   For a 32-bit system, run:
302
303   pacman -S mingw-w64-i686-toolchain
304
305   After the packages install, you're ready to build crawl!
306
307 * To get the crawl source, you can follow the steps in the Source Code Checkout
308   section above to clone crawl into your MSYS2 home directory. If you've
309   downloaded the source elsewhere, cd to that Crawl source directory. For
310   instance, if you have the crawl sources in c:\crawl\source, you would type
311   'cd /c/crawl/source'.
312
313 * Build Crawl by running 'make'. If you want a graphical build, you will need
314   to add ' TILES=y' on the 'make' command line.
315
316 * When the build process finishes, you can run crawl.exe directly from the
317   source directory in the MSYS2 shell. For Tiles, type './crawl', and for
318   console, type 'start crawl', which will open Crawl in a new console window
319   (necessary for it to run properly). Both versions can also be started by
320   double-clicking crawl.exe using the graphical file explorer.
321
322 * For you stubborn types who insist on using separate MSYS and git installs,
323   make sure git.exe is in your PATH when trying to build from git! Otherwise,
324   util/gen_ver.pl will most likely fail to generate build.h.
325
326 NOTE: If you have the older compilation environment of msysgit with Win-Builds
327 gcc or a separate install of MSYS2 that otherwise differs from the steps above,
328 you may need to add a 'NO_PKGCONFIG=y' argument when building Crawl. This makes
329 the build use the contribs included in the Crawl distribution instead of those
330 installed in your MSYS environment. If you do want to use these outside
331 libraries, omit 'NO_PKGCONFIG=y', but you will likely need to use some of the
332 Crawl contribs. You can make the build use a specific Crawl contrib library
333 over ones installed in your MSYS by adding any of the following make arguments,
334 which can be used in any combination:
335
336   BUILD_LUA=y BUILD_ZLIB=y BUILD_SQLITE=y BUILD_SDL2=y BUILD_SDL2IMAGE=y
337
338
339 Building on Windows (Cygwin)
340 ----------------------------
341
342 * Get Cygwin from http://www.cygwin.com/. When installing, ensure that the
343   following packages are selected: gcc, g++, make, flex, bison,
344   libncurses-devel. If you'd like to build from git, install the git-core
345   package. You may also want to install diff, patch, and other such tools.
346
347 * Once Cygwin is installed, open a Cygwin bash shell (use the Start menu or
348   desktop icon, do not double-click bash.exe in Explorer).
349
350 * cd to the the Crawl source directory. For instance, if you have the crawl
351   sources in c:\crawl\source, you would type 'cd /cygdrive/c/crawl/source'.
352
353 * Follow the Linux build instructions to build Crawl.
354
355 Building on Windows (MSVC)
356 --------------------------
357
358 * If you do not have Visual Studio 2012 you can get the free Express edition
359   (for Desktop) from http://www.microsoft.com/visualstudio/eng/downloads (look
360   for Visual Studio Express 2012 for Windows Desktop).
361
362 * You'll need a perl environment, there are links to several Windows binaries
363   you can choose from at http://www.perl.org/get.html
364
365 * In the Crawl source, run gen-all.cmd which is in source/util/. This step must
366   be executed any time you update to a new version of the source (or if you
367   have modified tile data or unrandarts).
368
369 * The first time you compile, you need to build the Contribs solution. This
370   compiles various libraries which crawl itself needs to build. This only needs
371   to be performed the first time you build, or if the contribs are ever updated
372   (extremely rare). To do this open and compile Contribs.sln in source/contrib.
373
374 * Open crawl-ref.sln in Visual Studio, this is in source/MSVC/.
375
376 * You can now select Debug or Release from the drop-down build configurations
377   menu on the main toolbar (it should be next to "Local Windows Debugger");
378   crawl.exe can them be compiled by selecting "Build Solution" in the BUILD
379   menu. You can quickly run it by selecting "Start without Debugging" in the
380   debug menu (or debug with "Start Debugging" but the game will run extremely
381   slowly). Note: the Release build can still be debugged using the Visual
382   Studio debugger.
383
384 * Better support for Python (for the webserver project) and Lua (for the dat
385   project) can be installed with these extensions:
386
387   Python Tools for Visual Studio
388   http://pytools.codeplex.com/releases
389
390   Ports of VsLua to Visual Studio 2012
391   http://www.dbfinteractive.com/forum/index.php?topic=5873.0
392   http://pouet.net/topic.php?which=9087
393
394   Try at your own risk, but the first one has been tested and found to be
395   effective.
396
397 *****************************************************************************
398
399 Data files
400 ----------
401
402 Crawl looks for several data files when starting up. They include:
403
404 * Special level and vault layout (dat/*.des) files.
405 * Core Lua code (dat/dlua/*.lua).
406 * Descriptions for monsters and game features (dat/descript/*.txt).
407 * Definitions for monster dialogue and randart names (dat/database/*.txt).
408
409 All these files are in the source tree under source/dat.
410
411 Crawl will also look for documentation files when players invoke the help
412 system. These files are available under the docs directory.
413
414 Your built Crawl binary must be able to find these files, or it will not start.
415
416 If Crawl is built without an explicit DATA_DIR_PATH (this is the most common
417 setup), it will search for its data files under the current directory, and if
418 it can't find them there, one level above the current directory. In short, it
419 uses these search paths: ., ./dat, ./docs, .., ../dat, ../docs.
420
421 The level compiler
422 ------------------
423
424 Crawl uses a level compiler to read the level design (.des) files in the
425 source/dat directory.
426
427 If you're using one of standard makefile, the steps described in this section
428 are performed automatically:
429
430 The level compiler source is in the source/util directory (levcomp.lpp and
431 levcomp.ypp). The steps involved in building the level compiler are:
432
433 * Run flex on levcomp.lpp to produce the levcomp.lex.cc lexer.
434 * Run bison on levcomp.ypp to produce the levcomp.tab.cc parser and
435   levcomp.tab.h
436 * Compile the resulting C++ source files and levcomp.cc and link the object
437   files into the Crawl executable.
438
439 For convenience on systems that don't have flex/bison, pre-generated
440 intermediate files are provided under source/prebuilt. The makefiles provided
441 with the Crawl source distribution will use these pre-generated files
442 automatically if flex/bison is not available.
443
444 Lua
445 ---
446
447 The Lua source is included with Crawl. It will be used if you don't have Lua
448 headers installed. Note that we don't provide security support for Lua, and
449 thus if you run a public server or a kiosk, it is strongly recommended to use
450 system Lua which does receive security updates from whatever distribution you
451 use.
452
453 PCRE
454 ----
455
456 PCRE 8.12, with a custom build system but otherwise unchanged, is included with
457 Crawl. It is enabled by default on Windows; otherwise, unless you build with
458 BUILD_PCRE (to use the contrib) or USE_PCRE (to use a development package from
459 your manager), the system POSIX regex will be used.
460
461 Unicode
462 -------
463
464 On Unix, you want an UTF-8 locale. All modern distributions install one by
465 default, but you might have somehow dropped required settings. To check this,
466 run "locale charmap", which should say "UTF-8". If it's not, please ensure
467 either LANG, LC_ALL or LC_CTYPE is set. A typical line would be "export
468 LC_ALL=en_US.UTF-8".
469
470 On Windows, the console behaves differently for TrueType and legacy (bitmap)
471 fonts. The latter (mostly) work only on certain language editions of Windows,
472 such as English, and even there, they work adequately only for Crawl's default
473 settings. For anything more, please select one of TrueType fonts. If, like one
474 of our players, you are deeply attached to the looks of bitmap fonts, you can
475 download a corrected version of the Terminal font from
476 http://www.yohng.com/software/terminalvector.html