Merge pull request #758 from ebering/banished-cleanup
[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/10
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.
50
51 There's no reason Crawl shouldn't work on other modern systems, especially
52 Unixy ones, although some porting may be needed.
53
54
55 Source Code Checkout
56 --------------------
57
58 If you don't already have the source code downloaded (in the form of a .zip or
59 .tar.bz2 file), you can obtain the latest source code from Git. MSYS2 users
60 should have Git if they followed the installation instructions in the MSYS2
61 section. Linux users can just install the 'git' or 'git-core' package with
62 whatever package manager they use. Note that there used to be another package
63 called 'git' (now 'gnuit') going around which stands for 'GNU interactive
64 tools'. This is not what you want.
65
66 Once you have Git installed, you just need to do:
67
68     git clone https://github.com/crawl/crawl.git
69
70 And then to get the contributing libraries, enter the newly cloned repository
71 via 'cd crawl' and type:
72
73     git submodule update --init
74
75 This should get you all you need to build Crawl from source.
76
77
78 Optional libraries
79 ------------------
80
81 Crawl can be built with some optional features:
82
83 * Sounds
84 * User Lua scripts
85
86 Crawl also uses a level compiler to compile special level definitions; to make
87 changes to the level compiler, you'll need the flex and bison/byacc tools
88 (Other lex/yaccs may also work). More details are available below.
89
90 Sound can be provided by SDL2_mixer (the default), by WINMM on Windows (defined
91 by WINMM_PLAY_SOUNDS in sound.h), or by an external command on Unix systems
92 (SOUND_PLAY_COMMAND in sound.h). To enable this, append SOUND=y to the make
93 invocation.
94
95 Crawl includes Lua 5.1.4 in its submodules. Crawl uses Lua for dungeon
96 generation. In addition, Crawl has a (rudimentary) Lua interface for users to
97 run scripts which can do things such as conditionalise parts of the
98 .crawlrc/init.txt. Such user Lua scripts are enabled by default, but can be
99 turned off by appending NO_LUA_BINDINGS=y to the make invocation.
100
101
102 Building on Unix (Linux, *BSD, Solaris, etc.)
103 ---------------------------------------------
104
105 To install or not to install:
106
107 If only one user on the system (you) is going to be playing Crawl, you do not
108 need to use "make install". A simple "make" will build Crawl in the source
109 directory, where you can run it as "./crawl".
110
111
112 Prerequisites (Debian):
113
114 On Debian-based systems (Ubuntu, Mint, ...), you can get all dependencies by
115 typing the following as root/sudo:
116
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
121 (the last six 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
127     apt-get install ccache binutils-gold
128     less /usr/share/doc/ccache/README.Debian
129
130
131 Prerequisites (Fedora):
132
133 On Fedora, and possibly other RPM-based systems, you can get the dependencies
134 by running the following as root:
135
136     dnf install gcc gcc-c++ make bison flex ncurses-devel compat-lua-devel \
137       sqlite-devel zlib-devel pkgconfig SDL-devel SDL_image-devel libpng-devel \
138       freetype-devel dejavu-sans-fonts dejavu-sans-mono-fonts
139
140 (the last six are needed only for tile builds). As with Debian, this package
141 list avoids the need for the bundled "contribs".
142
143 ccache can be installed with:
144
145     dnf install ccache
146
147
148 Prerequisites (Void):
149
150 On Void Linux you can get all dependencies by running the following as root:
151
152     xbps-install make gcc perl flex bison pkg-config ncurses-devel lua51-devel \
153       sqlite-devel zlib-devel pngcrush dejavu-fonts-ttf SDL2-devel \
154       SDL2_mixer-devel SDL2_image-devel freetype-devel
155
156 (the last six are needed only for tile builds).
157
158 ccache can be installed with:
159
160     xbps-install ccache
161
162
163 Prerequisites (other systems):
164
165 GNU gcc and g++, GNU make, libncursesw or libcursesw. You need the development
166 headers for ncurses - they may not be installed by default on some Unixes.
167
168 For tile builds, you need FreeDesktop's pkg-config, X11 and opengl headers.
169 The latter are likely to come from mesa sources.
170
171 flex and bison are optional but highly recommended. Recent versions of byacc
172 are also fine (edit your makefile appropriately).
173
174 You need to link with a curses library that understands Unicode characters,
175 usually named libncursesw (the development headers for libncursesw are usually
176 in /usr/include/ncursesw).
177
178
179 Building:
180
181 * cd to the source directory.
182
183 * Most users can simply type 'make' without any extra flags, and get a working
184   build as a result. If just typing 'make' works for you, then you shouldn't
185   need to read any further. BSD and Solaris users may have to use 'gmake'
186   instead of 'make'.
187
188 * For information Makefile settings beyond what is here, see the documentation
189   in comments in the Makefile itself.
190
191 * If you want a graphical (tiled) build, then you should add 'TILES=y' to the
192   'make' command-line, like so:
193
194     make TILES=y
195
196   Note that the graphical build requires that you have development libraries
197   installed for SDL, SDL_image, libpng, zlib, and freetype. If your system
198   doesn't have these installed, you can usually get them via your package
199   manager (apt-get, emerge, yum, etc).
200
201   If you would rather, you can go to the source/contrib directory and type
202   'make', and the required libraries should be built for you.
203
204 * If you want to install Crawl system-wide rather than play from the build
205   directory, you need to specify a directory to hold the save and data files.
206   Specifying a prefix of /usr or /usr/local will default SAVEDIR to "~/.crawl"
207   and DATADIR to share/crawl (relative to the prefix). SAVEDIR must be
208   writeable and owned by the user running crawl, so except for special cases it
209   should be inside "~" (home directory).
210
211 * To be specific, specifying a prefix means adding "prefix=foldername" to your
212   'make' command. Specifying a prefix is not mutually exclusive with specifying
213   a SAVEDIR; you can set them to completely unrelated directories if desired.
214
215 * If you're installing Crawl for multiple users, run 'make install' as root.
216   Crawl will be copied into the directory specified by 'prefix' (see above).
217   The data directory will be created if necessary, and the level layout, tile
218   and help files will be copied there.
219
220 * If you do not want players to be able to script Crawl with Lua, add
221   'NO_LUA_BINDINGS=y' to the 'make' command-line. This removes functionality
222   like autofight, and Lua scripts have been enabled on public servers for many
223   years without any security issues, so there is no real reason to do so.
224
225
226 Building on Mac OS X
227 --------------------
228
229 Before building on Mac OS X, you need a working copy of Xcode and the
230 associated command line tools. For recent versions of OS X, Xcode can be
231 installed through the AppStore as a free download; the associated command line
232 tools can then be installed by opening Xcode, opening the Preferences dialog,
233 and clicking Install on the Command Line Tools line in the Download tab.
234
235 Mac builds then use the Unix build process described above. To build Crawl on
236 a Mac you could use the following example command lines.
237
238 For the console version:
239   make
240 For the graphical version:
241   make TILES=y
242
243
244 Building on Windows (MSYS2)
245 ---------------------------
246
247 MSYS2 which is a Cygwin-derived software distro for Windows that can build
248 native applications. We recommend Windows users try this method first for
249 compiling crawl, since it is tested by our active Windows developers. You can
250 download the MSYS2 installer from the following website:
251
252 https://msys2.github.io/
253
254 You generally want to install the 64-bit version of MSYS2 unless you have a
255 specific reason to build a 32-bit version of crawl. Follow all of the steps you
256 see on that page to install MSYS2, but please read the additional notes below.
257 In particular, when starting the MSYS2 Shell, be sure to run the 64-bit MinGW
258 version of MSYS2 and *not* the version labeled 'MSYS2 MSYS'.
259
260 * The installer will put all MSYS2/MinGW files into a folder of your choice,
261   which defaults to 'C:\msys64'. If you have crawl-related work files from
262   other directories that you'd like to carry over, you can copy them into
263   'C:\msys64\home\<Username>', where <Username> is your Windows username. This
264   is the path to your home directory in this new MSYS2 installation.
265
266 * After the installer finishes, you'll want to start the MSYS2 Shell to follow
267   steps 5-7 in order to update your installation. Be sure to use the menu entry
268   that's labeled MSYS2 MinGW 64-bit and *not* the one labeled 'MSYS2 MSYS'.
269   After each update step, restart the MSYS2 shell before the next step.
270
271 After MSYS2 is fully installed and updated, follow steps below to install
272 development packages and compile Crawl. The commands shown below should be run
273 from within the MSYS2 Shell.
274
275 * To install git and the base development packages, run:
276
277   pacman -S base-devel git
278
279   Accept the default action to install all packages in base-devel, and say yes
280   to any questions about installing packages or removing packages due to
281   conflicts.
282
283 * To install the mingw-w64 GCC toolchain for your system, run:
284
285   pacman -S mingw-w64-x86_64-toolchain
286
287   At this point you may need to add the newly installed toolchain to your path.
288   You can do this with the following line, either at the command line (for that
289   shell instance only) or in the file `~/.bashrc` to make it permanent:
290
291   export PATH=$PATH:/mingw64/bin
292
293   To test that this worked, run:
294
295   gcc -v
296
297   After the packages are installed and gcc runs, you're ready to build crawl!
298
299 * To get the Crawl source, you can follow the steps in the Source Code Checkout
300   section above to clone Crawl into your MSYS2 home directory. If you've
301   downloaded the source elsewhere, first 'cd' to that Crawl source directory.
302   For example, if you have the Crawl sources in c:\crawl\source, you would run:
303
304   cd /c/crawl/source
305
306 * Build the console version of Crawl by simply running:
307
308   make
309
310   If you want a graphical build, you will need to run add 'TILES=y':
311
312   make TILES=y
313
314 * When the build process finishes, you can run crawl.exe directly from the
315   source directory in the MSYS2 shell. For Tiles, type './crawl', and for
316   console, type 'start crawl', which will open Crawl in a new console window
317   (necessary for it to run properly). Both versions can also be started by
318   double-clicking crawl.exe using the graphical file explorer.
319
320 Building on Windows (Cygwin)
321 ----------------------------
322
323 * Get Cygwin from http://www.cygwin.com/. When installing, ensure that the
324   following packages are selected: gcc, g++, make, flex, bison,
325   libncurses-devel. If you'd like to build from git, install the git-core
326   package. You may also want to install diff, patch, and other such tools.
327
328 * Once Cygwin is installed, open a Cygwin bash shell (use the Start menu or
329   desktop icon, do not double-click bash.exe in Explorer).
330
331 * cd to the the Crawl source directory. For instance, if you have the Crawl
332   sources in c:\crawl\source, you would type 'cd /cygdrive/c/crawl/source'.
333
334 * Follow the Linux build instructions to build Crawl.
335
336 Building on Windows 10 (Linux Subsystem)
337 --------------------------------------------------------------------
338
339 * Follow the instructions on Microsoft's website at
340   https://docs.microsoft.com/en-us/windows/wsl/install-win10 to set up the
341   Windows Subsystem for Linux.
342
343 * Make sure to run 'apt-get update' to get the latest versions of the package
344   lists, if using Ubuntu.
345
346 * Follow the Linux instructions to build Crawl.
347
348 * Console and Webtiles will work without any further configuration. To get SDL
349   tiles to work, you need an X server running on Windows; Xming is an option
350   that has worked in the past. If you run into an error about not finding a
351   matching GLX visual, try running:
352
353   export SDL_VIDEO_X11_VISUALID=
354
355
356 Building on Windows (MSVC)
357 --------------------------
358
359 * This build process is not currently maintained and is unlikely to be
360   straightforward in versions of MSVC besides those explicitly mentioned
361   here. If you get it to work on a more recent version, please let us know
362   and submit a patch!
363
364 * If you do not have Visual Studio 2012 you can get the free Express edition
365   (for Desktop) from http://www.microsoft.com/visualstudio/eng/downloads (look
366   for Visual Studio Express 2012 for Windows Desktop).
367
368 * You'll need a perl environment, there are links to several Windows binaries
369   you can choose from at http://www.perl.org/get.html
370
371 * In the Crawl source, run gen-all.cmd which is in source/util/. This step must
372   be executed any time you update to a new version of the source (or if you
373   have modified tile data or unrandarts).
374
375 * The first time you compile, you need to build the Contribs solution. This
376   compiles various libraries which Crawl itself needs to build. This only needs
377   to be performed the first time you build, or if the contribs are ever updated
378   (extremely rare). To do this open and compile Contribs.sln in source/contrib.
379
380 * Open crawl-ref.sln in Visual Studio, this is in source/MSVC/.
381
382 * You can now select Debug or Release from the drop-down build configurations
383   menu on the main toolbar (it should be next to "Local Windows Debugger");
384   crawl.exe can them be compiled by selecting "Build Solution" in the BUILD
385   menu. You can quickly run it by selecting "Start without Debugging" in the
386   debug menu (or debug with "Start Debugging" but the game will run extremely
387   slowly). Note: the Release build can still be debugged using the Visual
388   Studio debugger.
389
390 * Better support for Python (for the webserver project) and Lua (for the dat
391   project) can be installed with these extensions:
392
393   Python Tools for Visual Studio
394   http://pytools.codeplex.com/releases
395
396   Ports of VsLua to Visual Studio 2012
397   http://www.dbfinteractive.com/forum/index.php?topic=5873.0
398   http://pouet.net/topic.php?which=9087
399
400   Try at your own risk, but the first one has been tested and found to be
401   effective.
402
403 *****************************************************************************
404
405 Data files
406 ----------
407
408 Crawl looks for several data files when starting up. They include:
409
410 * Special level and vault layout (dat/*.des) files.
411 * Core Lua code (dat/dlua/*.lua).
412 * Descriptions for monsters and game features (dat/descript/*.txt).
413 * Definitions for monster dialogue and randart names (dat/database/*.txt).
414
415 All these files are in the source tree under source/dat.
416
417 Crawl will also look for documentation files when players invoke the help
418 system. These files are available under the docs directory.
419
420 Your built Crawl binary must be able to find these files, or it will not start.
421
422 If Crawl is built without an explicit DATA_DIR_PATH (this is the most common
423 setup), it will search for its data files under the current directory, and if
424 it can't find them there, one level above the current directory. In short, it
425 uses these search paths: ., ./dat, ./docs, .., ../dat, ../docs.
426
427 The level compiler
428 ------------------
429
430 Crawl uses a level compiler to read the level design (.des) files in the
431 source/dat directory.
432
433 If you're using one of standard makefile, the steps described in this section
434 are performed automatically:
435
436 The level compiler source is in the source/util directory (levcomp.lpp and
437 levcomp.ypp). The steps involved in building the level compiler are:
438
439 * Run flex on levcomp.lpp to produce the levcomp.lex.cc lexer.
440 * Run bison on levcomp.ypp to produce the levcomp.tab.cc parser and
441   levcomp.tab.h
442 * Compile the resulting C++ source files and levcomp.cc and link the object
443   files into the Crawl executable.
444
445 For convenience on systems that don't have flex/bison, pre-generated
446 intermediate files are provided under source/prebuilt. The makefiles provided
447 with the Crawl source distribution will use these pre-generated files
448 automatically if flex/bison is not available.
449
450 Lua
451 ---
452
453 The Lua source is included with Crawl. It will be used if you don't have Lua
454 headers installed. Note that we don't provide security support for Lua, and
455 thus if you run a public server or a kiosk, it is strongly recommended to use
456 system Lua which does receive security updates from whatever distribution you
457 use.
458
459 PCRE
460 ----
461
462 PCRE 8.12, with a custom build system but otherwise unchanged, is included with
463 Crawl. It is enabled by default on Windows; otherwise, unless you build with
464 BUILD_PCRE (to use the contrib) or USE_PCRE (to use a development package from
465 your manager), the system POSIX regex will be used.
466
467 Unicode
468 -------
469
470 On Unix, you want an UTF-8 locale. All modern distributions install one by
471 default, but you might have somehow dropped required settings. To check this,
472 run "locale charmap", which should say "UTF-8". If it's not, please ensure
473 either LANG, LC_ALL or LC_CTYPE is set. A typical line would be "export
474 LC_ALL=en_US.UTF-8".
475
476 On Windows, the console behaves differently for TrueType and legacy (bitmap)
477 fonts. The latter (mostly) work only on certain language editions of Windows,
478 such as English, and even there, they work adequately only for Crawl's default
479 settings. For anything more, please select one of TrueType fonts. If, like one
480 of our players, you are deeply attached to the looks of bitmap fonts, you can
481 download a corrected version of the Terminal font from
482 http://www.yohng.com/software/terminalvector.html