Reconnect kennysheep_demon_jail
[crawl.git] / crawl-ref / INSTALL.txt
1 Install instructions for Dungeon Crawl Stone Soup (DCSS)
2 --------------------------------------------------------
3
4 Getting Crawl to run
5 --------------------
6
7 This file describes how to compile a runtime executable of Crawl from the
8 source code. If you're trying to compile Crawl yourself, skip ahead to the next
9 section, "Building Crawl".
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 Crawl
39 --------------
40
41 Crawl is known to run on the following platforms:
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 also uses a level compiler to compile special level definitions; to make
88 changes to the level compiler, you'll need the flex and bison/byacc tools
89 (Other lex/yaccs may also work). More details are available below.
90
91 Sound can be provided by SDL2_mixer (the default), by WINMM on Windows (defined
92 by WINMM_PLAY_SOUNDS in AppHdr.h), or by an external command on Unix systems
93 (SOUND_PLAY_COMMAND in AppHdr.h). To enable this, append SOUND=y to the make
94 invocation.
95
96 Crawl includes Lua 5.1.4 in its submodules. Crawl uses Lua for dungeon
97 generation. In addition, Crawl has a (rudimentary) Lua interface for users to
98 run scripts which can do things such as conditionalise parts of the
99 .crawlrc/init.txt. Such user Lua scripts are enabled by default, but can be
100 turned off by appending NO_LUA_BINDINGS=y to the make invocation.
101
102
103 Building on Unix (Linux, *BSD, Solaris, etc.)
104 ---------------------------------------------
105
106 To install or not to install:
107
108 If only one user on the system (you) is going to be playing Crawl, you do not
109 need to use "make install". A simple "make" will build Crawl in the source
110 directory, where you can run it as "./crawl".
111
112
113 Prerequisites (Debian):
114
115 On Debian-based systems (Ubuntu, Mint, ...), you can get all dependencies by
116 typing the following as root/sudo:
117 apt-get install build-essential libncursesw5-dev bison flex liblua5.1-0-dev \
118   libsqlite3-dev libz-dev pkg-config libsdl2-image-dev libsdl2-mixer-dev    \
119   libsdl2-dev libfreetype6-dev libpng-dev ttf-dejavu-core
120 (the last five are needed only for tiles builds). This is the complete set,
121 with it you don't have a need for the bundled "contribs".
122
123 If you are going to be rebuilding after doing small changes a lot, it is
124 recommended that you also install and configure ccache and binutils-gold:
125 apt-get install ccache binutils-gold less /usr/share/doc/ccache/README.Debian
126
127
128 Prerequisites (Fedora):
129
130 On Fedora, and possibly other RPM-based systems, you can get the dependencies
131 by running the following as root:
132 dnf install gcc gcc-c++ make bison flex ncurses-devel compat-lua-devel \
133   sqlite-devel zlib-devel pkgconfig SDL-devel SDL_image-devel libpng-devel \
134   freetype-devel dejavu-sans-fonts dejavu-sans-mono-fonts
135 (the last six are needed only for tile builds). As with Debian, this package
136 list avoids the need for the bundled "contribs".
137
138 ccache can be installed with:
139 dnf install ccache
140
141
142 Prerequisites (other systems):
143
144 GNU gcc and g++, GNU make, libncursesw or libcursesw. You need the development
145 headers for ncurses - they may not be installed by default on some Unixes.
146
147 For tile builds, you need FreeDesktop's pkg-config, X11 and opengl headers.
148 The latter are likely to come from mesa sources.
149
150 flex and bison are optional but highly recommended. Recent versions of byacc
151 are also fine (edit your makefile appropriately).
152
153 You need to link with a curses library that understands Unicode characters,
154 usually named libncursesw (the development headers for libncursesw are usually
155 in /usr/include/ncursesw).
156
157
158 Building:
159
160 * cd to the source directory.
161
162 * Most users can simply type 'make' without any extra flags, and get a working
163   build as a result. If just typing 'make' works for you, then you shouldn't
164   need to read any further. BSD and Solaris users may have to use 'gmake'
165   instead of 'make'.
166
167 * If you want a graphical (tiled) build, then you should add 'TILES=y' to the
168   'make' command-line, like so:
169
170     make TILES=y
171
172   Note that the graphical build requires that you have development libraries
173   installed for SDL, SDL_image, libpng, zlib, and freetype. If your system
174   doesn't have these installed, you can usually get them via your package
175   manager (apt-get, emerge, yum, etc).
176
177   If you would rather, you can go to the source/contrib directory and type
178   'make', and the required libraries should be built for you.
179
180 * If you want to install Crawl system-wide rather than play from the build
181   directory, you need to specify a directory to hold the save and data files.
182   Specifying a prefix of /usr or /usr/local will default SAVEDIR to "~/.crawl"
183   and DATADIR to share/crawl (relative to the prefix). SAVEDIR must be
184   writeable and owned by the user running crawl, so except for special cases it
185   should be inside "~" (home directory).
186
187 * If you're installing Crawl for multiple users, run 'make install' as root.
188   Crawl will be copied into the directory specified by 'prefix' (see above).
189   The data directory will be created if necessary, and the level layout, tile
190   and help files will be copied there.
191
192 * If you do not want players to be able to script Crawl with Lua, add
193   'NO_LUA_BINDINGS=y' to the 'make' command-line. This removes functionality
194   like autofight, and Lua scripts have been enabled on public servers for many
195   years without any security issues, so there is no real reason to do so.
196
197
198 Building on Mac OS X
199 --------------------
200
201 Before building on Mac OS X, you need a working copy of Xcode and the
202 associated command line tools. For recent versions of OS X, Xcode can be
203 installed through the AppStore as a free download; the associated command line
204 tools can then be installed by opening Xcode, opening the Preferences dialog,
205 and clicking Install on the Command Line Tools line in the Download tab.
206
207 Mac builds then use the Unix build process described above, but require you to
208 add 'APPLE_GCC=y' to the 'make' command-line. In addition, to build the
209 graphical version of Crawl, you must add 'NO_PKGCONFIG=y' and 'CONTRIB_SDL=y'.
210
211 So, to build build Crawl on a Mac you could use the following example command
212 lines.
213
214 For the console version:
215   make APPLE_GCC=y
216 For the graphical version:
217   make APPLE_GCC=y NO_PKGCONFIG=y CONTRIB_SDL=y TILES=y
218
219
220 Building on Windows (MSYS2)
221 ---------------------------
222
223 MSYS2 which is a Cygwin-derived software distro for Windows that can build
224 native applications. We recommend Windows users try this method first for
225 compiling crawl, since it is tested by our active Windows developers. You can
226 download the MSYS2 installer from the following website:
227
228 https://msys2.github.io/
229
230 Follow all of the steps you see on that page to install MSYS2, but please read
231 the additional notes below. The note for after Step 6 is particularly important
232 to be able to start the MSYS2 shell.
233
234 * Download and run the MSYS2 installer exe at the top that is appropriate for
235   your processor, either the 32-bit or 64-bit. The 32-bit installer file has
236   the prefix 'msys2-i686', and the 64-bit version has the prefix
237   'msys2-x86_64'. Most modern systems have 64-bit processors, but you can check
238   your system under Start->About this Computer or (e.g. Windows 10)
239   Start->Settings->About.
240
241 * The installer will put all MSYS2/MinGW files into a folder of your choice,
242   which defaults to 'C:\msys64'. You should not reuse any previous folder made
243   with previous installs of MSYS (from msysgit and/or win-builds.org) or MSYS2
244   (from Git for Windows SDK). However if you have crawl-related work files from
245   such directories that you'd like to carry over, you can copy them to
246   e.g. 'C:\msys64\home\<Username>', where <Username> is your Windows
247   username. This is the path to your home directory in this new MSYS2
248   installation.
249
250 * After Step 6, where you update the installed packages, you'll see an update
251   message telling you to close the MSYS2 terminal and to update the Windows
252   shortcuts used to start MSYS2. The shortcut you'll use to start MSYS2 will be
253   either 'MinGW-w64 Win64 Shell' (64-bit systems) or 'MinGW-w64 Win32 Shell'
254   (32-bit systems), both of which you can find under the MSYS2 group in your
255   Start menu Applications list.
256
257   You need to change the Target of this shortcut. On some systems you can
258   Right-click the shortcut and choosing Properties, and on later systems
259   (e.g. Windows 10), you Right-click, choose More->Open File Location,
260   right-click the file in the File manager window that appears, and then choose
261   Properties. From the Properties dialog, update the Target field according to
262   the message you saw in Step 6. For 64-bit systems, the necessary Target
263   should look like:
264
265   C:\msys64\msys2_shell.cmd -mingw64
266
267   For 32-bit systems:
268
269   C:\msys64\msys2_shell.cmd -mingw32
270
271   NOTE: The update message refers to a Target of 'MSYS2_ROOT\msys2_shell.cmd',
272   but the 'MSYS2_ROOT' in this path should be replaced with the directory where
273   you installed MSYS2, which by default is 'C:\msys64'.
274
275 * After updating the shortcut above, you must close the MSYS2 shell and restart
276   it from the shortcut you've updated. Run the final update in Step 7 before
277   proceeding to the steps below. You can start the MSYS2 shell at any time
278   using the updated shortcut.
279
280   NOTE: You generally don't want to use the shortcut called 'MSYS2 Shell', as
281   this starts a shell for working with Cygwin-based MSYS2 components. Building
282   Crawl in this environment is currently not supported.
283
284 Install Git and the development packages, and compile crawl:
285
286 * To install git and the base development packages, run the following command
287   from the MSYS2 shell:
288
289   pacman -S base-devel git
290
291   Accept the default action to install all packages in base-devel, and say yes
292   to any questions about installing packages or removing packages due to
293   conflicts.
294
295 * Install the mingw-w64 gcc toolchain for your system. For a 64-bit system,
296   run:
297
298   pacman -S mingw-w64-x86_64-toolchain
299
300   For a 32-bit system, run:
301
302   pacman -S mingw-w64-i686-toolchain
303
304   After the packages install, you're ready to build crawl!
305
306 * To get the Crawl source, you can follow the steps in the Source Code Checkout
307   section above to clone Crawl into your MSYS2 home directory. If you've
308   downloaded the source elsewhere, cd to that Crawl source directory. For
309   instance, if you have the Crawl sources in c:\crawl\source, you would type
310   'cd /c/crawl/source'.
311
312 * Build Crawl by running 'make'. If you want a graphical build, you will need
313   to add ' TILES=y' on the 'make' command line.
314
315 * When the build process finishes, you can run crawl.exe directly from the
316   source directory in the MSYS2 shell. For Tiles, type './crawl', and for
317   console, type 'start crawl', which will open Crawl in a new console window
318   (necessary for it to run properly). Both versions can also be started by
319   double-clicking crawl.exe using the graphical file explorer.
320
321 * For you stubborn types who insist on using separate MSYS and git installs,
322   make sure git.exe is in your PATH when trying to build from git! Otherwise,
323   util/gen_ver.pl will most likely fail to generate build.h.
324
325 NOTE: If you have the older compilation environment of msysgit with Win-Builds
326 gcc or a separate install of MSYS2 that otherwise differs from the steps above,
327 you may need to add a 'NO_PKGCONFIG=y' argument when building Crawl. This makes
328 the build use the contribs included in the Crawl distribution instead of those
329 installed in your MSYS environment. If you do want to use these outside
330 libraries, omit 'NO_PKGCONFIG=y', but you will likely need to use some of the
331 Crawl contribs. You can make the build use a specific Crawl contrib library
332 over ones installed in your MSYS by adding any of the following make arguments,
333 which can be used in any combination:
334
335   BUILD_LUA=y BUILD_ZLIB=y BUILD_SQLITE=y BUILD_SDL2=y BUILD_SDL2IMAGE=y
336
337
338 Building on Windows (Cygwin)
339 ----------------------------
340
341 * Get Cygwin from http://www.cygwin.com/. When installing, ensure that the
342   following packages are selected: gcc, g++, make, flex, bison,
343   libncurses-devel. If you'd like to build from git, install the git-core
344   package. You may also want to install diff, patch, and other such tools.
345
346 * Once Cygwin is installed, open a Cygwin bash shell (use the Start menu or
347   desktop icon, do not double-click bash.exe in Explorer).
348
349 * cd to the the Crawl source directory. For instance, if you have the Crawl
350   sources in c:\crawl\source, you would type 'cd /cygdrive/c/crawl/source'.
351
352 * Follow the Linux build instructions to build Crawl.
353
354 Building on Windows (MSVC)
355 --------------------------
356
357 * If you do not have Visual Studio 2012 you can get the free Express edition
358   (for Desktop) from http://www.microsoft.com/visualstudio/eng/downloads (look
359   for Visual Studio Express 2012 for Windows Desktop).
360
361 * You'll need a perl environment, there are links to several Windows binaries
362   you can choose from at http://www.perl.org/get.html
363
364 * In the Crawl source, run gen-all.cmd which is in source/util/. This step must
365   be executed any time you update to a new version of the source (or if you
366   have modified tile data or unrandarts).
367
368 * The first time you compile, you need to build the Contribs solution. This
369   compiles various libraries which Crawl itself needs to build. This only needs
370   to be performed the first time you build, or if the contribs are ever updated
371   (extremely rare). To do this open and compile Contribs.sln in source/contrib.
372
373 * Open crawl-ref.sln in Visual Studio, this is in source/MSVC/.
374
375 * You can now select Debug or Release from the drop-down build configurations
376   menu on the main toolbar (it should be next to "Local Windows Debugger");
377   crawl.exe can them be compiled by selecting "Build Solution" in the BUILD
378   menu. You can quickly run it by selecting "Start without Debugging" in the
379   debug menu (or debug with "Start Debugging" but the game will run extremely
380   slowly). Note: the Release build can still be debugged using the Visual
381   Studio debugger.
382
383 * Better support for Python (for the webserver project) and Lua (for the dat
384   project) can be installed with these extensions:
385
386   Python Tools for Visual Studio
387   http://pytools.codeplex.com/releases
388
389   Ports of VsLua to Visual Studio 2012
390   http://www.dbfinteractive.com/forum/index.php?topic=5873.0
391   http://pouet.net/topic.php?which=9087
392
393   Try at your own risk, but the first one has been tested and found to be
394   effective.
395
396 *****************************************************************************
397
398 Data files
399 ----------
400
401 Crawl looks for several data files when starting up. They include:
402
403 * Special level and vault layout (dat/*.des) files.
404 * Core Lua code (dat/dlua/*.lua).
405 * Descriptions for monsters and game features (dat/descript/*.txt).
406 * Definitions for monster dialogue and randart names (dat/database/*.txt).
407
408 All these files are in the source tree under source/dat.
409
410 Crawl will also look for documentation files when players invoke the help
411 system. These files are available under the docs directory.
412
413 Your built Crawl binary must be able to find these files, or it will not start.
414
415 If Crawl is built without an explicit DATA_DIR_PATH (this is the most common
416 setup), it will search for its data files under the current directory, and if
417 it can't find them there, one level above the current directory. In short, it
418 uses these search paths: ., ./dat, ./docs, .., ../dat, ../docs.
419
420 The level compiler
421 ------------------
422
423 Crawl uses a level compiler to read the level design (.des) files in the
424 source/dat directory.
425
426 If you're using one of standard makefile, the steps described in this section
427 are performed automatically:
428
429 The level compiler source is in the source/util directory (levcomp.lpp and
430 levcomp.ypp). The steps involved in building the level compiler are:
431
432 * Run flex on levcomp.lpp to produce the levcomp.lex.cc lexer.
433 * Run bison on levcomp.ypp to produce the levcomp.tab.cc parser and
434   levcomp.tab.h
435 * Compile the resulting C++ source files and levcomp.cc and link the object
436   files into the Crawl executable.
437
438 For convenience on systems that don't have flex/bison, pre-generated
439 intermediate files are provided under source/prebuilt. The makefiles provided
440 with the Crawl source distribution will use these pre-generated files
441 automatically if flex/bison is not available.
442
443 Lua
444 ---
445
446 The Lua source is included with Crawl. It will be used if you don't have Lua
447 headers installed. Note that we don't provide security support for Lua, and
448 thus if you run a public server or a kiosk, it is strongly recommended to use
449 system Lua which does receive security updates from whatever distribution you
450 use.
451
452 PCRE
453 ----
454
455 PCRE 8.12, with a custom build system but otherwise unchanged, is included with
456 Crawl. It is enabled by default on Windows; otherwise, unless you build with
457 BUILD_PCRE (to use the contrib) or USE_PCRE (to use a development package from
458 your manager), the system POSIX regex will be used.
459
460 Unicode
461 -------
462
463 On Unix, you want an UTF-8 locale. All modern distributions install one by
464 default, but you might have somehow dropped required settings. To check this,
465 run "locale charmap", which should say "UTF-8". If it's not, please ensure
466 either LANG, LC_ALL or LC_CTYPE is set. A typical line would be "export
467 LC_ALL=en_US.UTF-8".
468
469 On Windows, the console behaves differently for TrueType and legacy (bitmap)
470 fonts. The latter (mostly) work only on certain language editions of Windows,
471 such as English, and even there, they work adequately only for Crawl's default
472 settings. For anything more, please select one of TrueType fonts. If, like one
473 of our players, you are deeply attached to the looks of bitmap fonts, you can
474 download a corrected version of the Terminal font from
475 http://www.yohng.com/software/terminalvector.html