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