Fix braces
[crawl.git] / crawl-ref / INSTALL.md
1 # Install instructions for Dungeon Crawl Stone Soup (DCSS)
2
3 ## Contents
4
5 * [Getting DCSS To Run](#getting-dcss-to-run)
6 * [Compiling](#compiling)
7   * [Ubuntu / Debian](#ubuntu--debian)
8   * [Fedora](#fedora)
9   * [Other Linux / Unix](#other-linux--unix)
10   * [macOS](#macOS)
11   * [Windows](#windows)
12     * [MSYS2 (Recommended)](#msys2-recommended)
13     * [Windows Subsystem for Linux (WSL)](#windows-subsystem-for-linux-wsl)
14     * [Visual Studio](#visual-studio)
15 * [Advanced](#advanced)
16   * [ccache](#ccache)
17   * [Installing For All Users](#installing-for-all-users)
18   * [.des Level Compiler](#des-level-compiler)
19   * [Code Coverage](#code-coverage)
20   * [Lua](#lua)
21   * [PCRE](#pcre)
22   * [Unicode](#unicode)
23 * [Getting Help](#getting-help)
24
25 ## Getting DCSS To Run
26
27 You can download prebuilt versions of DCSS from the
28 [DCSS homepage](https://crawl.develz.org/download.htm).
29
30 If you're having any trouble running these versions, try asking for help in
31 [any of the community forums detailed in the README](../README.md#community).
32
33 The rest of this file deals with compiling DCSS from source.
34
35 ## Compiling
36
37 Here's the basic workflow. Please read the section for your OS below for more
38 detailed instructions.
39
40 ```sh
41 # Clone the repository
42 git clone https://github.com/crawl/crawl.git
43 cd crawl
44
45 # Either install dependencies from your OS package manager (eg apt, yum)
46 apt install ...
47 # or use DCSS's packaged dependencies
48 git submodule update --init
49
50 # Build DCSS (remove TILES=y for console mode)
51 cd crawl-ref/source
52 make -j4 TILES=y
53
54 # Play DCSS by running the compiled binary
55 ./crawl
56 ```
57
58 ### Packaged Dependencies
59
60 DCSS uses Lua, SDL, SQLite and several other third party packages. Generally
61 you should use the versions supplied by your OS's package manager. If that's
62 not possible, you can use the versions packaged with DCSS.
63
64 To use packaged dependencies:
65
66 1. Clone the repository with Git (you can't use a tarball - the dependencies
67    use Git submodules).
68 2. Run `git submodule update --init` in the repository.
69 3. Compile as per above.
70
71 ### Ubuntu / Debian
72
73 These instructions may work for other DPKG-based distros.
74
75 ```sh
76 # python-is-python3 is required for Ubuntu 20.04 and newer
77 sudo apt install build-essential libncursesw5-dev bison flex liblua5.1-0-dev \
78 libsqlite3-dev libz-dev pkg-config python3-yaml binutils-gold python-is-python3
79
80 # Dependencies for tiles builds
81 sudo apt install libsdl2-image-dev libsdl2-mixer-dev libsdl2-dev \
82 libfreetype6-dev libpng-dev ttf-dejavu-core advancecomp pngcrush
83 ```
84
85 Then follow [the above compilation steps](#compiling).
86
87 ### Fedora
88
89 These instructions may work for other RPM-based distros.
90
91 ```sh
92 sudo dnf install gcc gcc-c++ make bison flex ncurses-devel compat-lua-devel \
93 sqlite-devel zlib-devel pkgconfig python3-yaml
94
95 # Dependencies for tiles builds:
96 sudo dnf install SDL2-devel SDL2_image-devel libpng-devel freetype-devel \
97 dejavu-sans-fonts dejavu-sans-mono-fonts advancecomp pngcrush
98 ```
99
100 Then follow [the above compilation steps](#compiling).
101
102 ## Other Linux / Unix
103
104 You need the following dependencies:
105
106 * GNU make
107 * gcc / clang
108 * perl
109 * pkg-config
110 * Python 3 and PyYAML
111 * libncurses
112 * flex / bison (optional)
113
114 You can install these dependencies from your OS package manager, or use DCSS's
115 packaged versions (as described in [Packaged
116 Dependencies](#packaged-dependencies) above):
117
118 * lua 5.1
119 * sqlite
120 * zlib
121 * pcre
122 * zlib
123 * freetype (tiles builds only)
124 * DejaVu fonts (tiles builds only)
125 * SDL2 (tiles builds only)
126 * SDL2_image (tiles builds only)
127 * libpng (tiles builds only)
128
129 Then follow [the above compilation steps](#compiling).
130
131 ## macOS
132
133 1. Before building on macOS, you need a working copy of Xcode and the
134    associated command line tools.
135     1. Install Xcode from the App Store
136     2. Open Xcode and say yes if you are prompted to install optional developer
137        tools. (You can quit Xcode after this completes.)
138     3. Run `xcode-select --install` in a Terminal
139
140 2. You will also need to install DCSS's bundled dependencies:
141
142     ```sh
143     cd crawl
144     git submodule update --init
145     ```
146
147 3. And install PyYAML:
148
149     ```sh
150     pip install pyyaml
151     ```
152
153 3. If you want to build a macOS application, add `mac-app-tiles` to your make
154    command, eg: `make -j4 mac-app-tiles TILES=y`. This will create an application in
155    `mac-app-zips/` of the source directory.
156
157 Then follow [the above compilation steps](#compiling).
158
159 ## Windows
160
161 ### MSYS2 (Recommended)
162
163 This is the only currently recommended process for building DCSS on windows.
164 It is also possible to cross-compile windows builds; see the release guide
165 for instructions.
166
167 MSYS2 is a Cygwin-derived software distro for Windows that can build
168 native applications; you will interact with the build process in a unix-like
169 shell interface. You can download the MSYS2 installer from the
170 [MSYS2 github page](https://msys2.github.io/)
171
172 You generally want to install the 64-bit version of MSYS2 unless you have a
173 specific reason to build a 32-bit version of crawl. Follow all of the steps you
174 see on that page to install MSYS2, but please read the additional notes below.
175 In particular, when starting the MSYS2 Shell, be sure to run the 64-bit MinGW
176 version of the MSYS2 shell and *not* the version labeled 'MSYS2 MSYS' or the
177 32-bit version.
178
179 The installer will put all MSYS2/MinGW files into a folder of your choice,
180 which defaults to `C:\msys64`. If you have crawl-related work files from
181 other directories that you'd like to carry over, you can copy them into
182 `C:\msys64\home\<Username>`, where `<Username>` is your Windows username. This
183 is the path to your MSYS2 home directory. From the MSYS2 shell you can always
184 get back to here with `cd ~`.
185
186 After the installer finishes, start the MSYS2 shell ("MSYS2 MinGW 64-bit")
187 and do steps 5-6 from the MSYS2 install instructions in order to update your
188 installation. These steps are repeated here:
189
190     5. At the command line, run `pacman -Syu` to update the core packages.
191        Then restart your MSYS2 shell. (The installer will force you to restart.)
192
193     6. At the command line, run `pacman -Su` to update all packages.
194
195 After MSYS2 is fully installed and updated, follow steps below to install
196 development packages and compile DCSS. The commands shown below should be run
197 from within the MSYS2 Shell.
198
199 1. To install git and the base development packages, run:
200
201     ```sh
202     pacman -S base-devel git
203     ```
204
205     Accept the default action to install all packages in base-devel, and say yes
206     to any questions about installing packages or removing packages due to
207     conflicts.
208
209 2. To install the mingw-w64 GCC toolchain for your system, run:
210
211     ```sh
212     pacman -S mingw-w64-x86_64-toolchain
213     ```
214
215 3. At this point on current MSYS2 versions, your development environment should
216   be complete. You can test it by running:
217
218     ```sh
219     gcc -v
220     ```
221
222     If this works, you're all set. If it doesn't, you may be an an older version
223     of MSYS2 and need to manually add the newly installed toolchain to your
224     path. To do so, run the following line, either at the command line (for
225     that shell instance only) or in the file `~/.bashrc` to make it permanent:
226
227     ```sh
228     export PATH=$PATH:/mingw64/bin
229     ```
230
231 4. To install PyYAML, you can install it from either pacman or Pip/PyPA:
232
233     ```sh
234     pacman -S mingw-w64-x86_64-python-yaml
235     # or
236     pacman -S mingw-w64-x86_64-python-pip
237     pip install pyyaml
238     ```
239
240     You can verify PyYAML is installed by running `python -m yaml`, which should
241     give an error like `'yaml' is a package and cannot be directly imported`
242     (rather than `No module named yaml`).
243
244 5. To get the DCSS source, follow the steps in the [Getting The
245    Source](#getting-the-source) section above to clone DCSS into your MSYS2
246    home directory. We recommend using the MSYS2-installed version of git for
247    these steps. In brief:
248
249     1. `cd` to the location where you would like the crawl repository to be. It
250        will clone into a folder named `crawl`. Your home directory (`cd ~`) is
251        a reasonable choice.
252     2. Run `git clone https://github.com/crawl/crawl.git`.
253     3. Run `cd crawl/crawl-ref/source`.
254     4. Run `git submodule update --init`.
255
256 6. Build DCSS by simply running:
257
258     ```sh
259     # console build
260     make
261     # tiles build
262     make TILES=y
263     ```
264
265     If you want a debug build, add the target `debug` to the above commands (eg
266     `make debug TILES=y`).
267
268 7. When the build process finishes, you can run crawl.exe directly from the
269    source directory in the MSYS2 shell. For Tiles, type `./crawl.exe`, and for
270    console, type `start crawl`, which will open DCSS in a new command.exe
271    window (the Windows version of DCSS requires a command.exe shell and will
272    not run in an MSYS2 shell). Both versions can also be started by
273    double-clicking `crawl.exe` using the graphical file explorer.
274
275 8. If you want to build the installer or zipped packages instead,
276    you need to install zip and nsis:
277
278     ```sh
279     pacman -S zip
280     # and
281     pacman -S mingw-w64-x86_64-nsis
282     ```
283
284     Then build by running:
285
286     ```sh
287     # installer
288     make package-windows-installer
289     # zips
290     make package-windows-zips
291     ```
292
293 ### Windows Subsystem for Linux (WSL)
294
295 These instructions have been successfully tested with Ubuntu only.
296
297 1. [Follow the instructions on Microsoft's
298    website](https://docs.microsoft.com/en-us/windows/wsl/install-win10) at to
299    set up the Windows Subsystem for Linux.
300
301 2. Follow the [Ubuntu instructions](#ubuntu--debian) to build DCSS.
302
303 3. Console and Webtiles will work without any further configuration. To get SDL
304    tiles to work, you need an X server running on Windows; Xming is an option
305    that has worked in the past. If you run into an error about not finding a
306    matching GLX visual, try running:
307
308     ```sh
309     export SDL_VIDEO_X11_VISUALID=
310     ```
311
312 ### Visual Studio
313
314 This build process is currently unsupported, and unlikely to be straightforward
315 in versions of MSVC besides those explicitly mentioned here.
316
317 This build is tested on Visual Studio 2017 15.8.7 on Windows 8.1 and 10.
318 Tested configurations are `Debug/Release;Console/Tiles;Win32/x64`, Python and
319 Lua support for editing are untested, and a webtiles build is not available.
320
321 1. To get the DCSS source, follow the steps in the [Getting The
322    Source](#getting-the-source) section above.
323
324     ```sh
325     git clone https://github.com/crawl/crawl.git
326     git submodule update --init
327     ```
328
329 2. Install a perl environment, [Perl provides links to several Windows
330    binaries](http://www.perl.org/get.html).
331
332 3. In the DCSS source, run `gen-all.cmd` inside `crawl-ref/source/util/`. This
333    step must be executed any time you update to a new version of the source (or
334    if you have modified tile data or unrandarts).
335
336 4. The first time you compile, you need to build the `Contribs` solution. This
337    compiles various libraries which DCSS itself needs to build. This
338    needs to be performed the first time you build, when changing to the `Debug`
339    configuration, and when the contribs are
340    updated. To do this open and compile `Contribs.sln` in
341    `crawl-ref/source/contrib`. Make sure to set `Release` or `Debug` (not the
342    library versions), as well as the desired architecture (Win32 or x64). Then
343    build (or re-build) the solution.
344
345 5. Open `crawl-ref.sln` in Visual Studio, this is in `crawl-ref/source/MSVC/`.
346
347 6. Select `Debug` or `Release` from the build configurations menu on the main
348    toolbar; `crawl.exe` is compiled by selecting "Build Solution" in the BUILD
349    menu.
350
351 7. To build the `Debug` version:
352
353    1. First build `Release` following the instructions above
354    2. Set the `Debug` configuration
355    3. Re-build the `Contribs`
356    4. Re-build with the `Debug` configuration set
357
358    Building the `Debug` version without first building the `Release`
359    configuration will result in an error on startup. The `Release` build can
360    still be debugged using the Visual Studio debugger.
361
362 ### Maintenance notes:
363
364 MSVC solution files are finicky. Opening the "All Configurations" or
365 "All Platforms" will automatically change settings. This is typically unwanted.
366
367 Troubleshooting tips:
368
369 - Make sure Windows Universal C Runtime is installed in MSVC.
370 - Build Release before rebuilding both solutions with Debug
371 - Use "Rebuild Solution" to make sure all files are rewritten
372 - Make sure all projects use `/MD` (or `/MDd` for the debug version)
373 - Make sure the appropriate (`/MD` or `/MDd`) CRT libraries are included for
374   SDL, crawl, and tilegen
375   (https://msdn.microsoft.com/en-us/library/abx4dbyh.aspx)
376 - Make sure `libpng.dll`, `SDL2.dll`, and `SDL2_image.dll` are in
377   `crawl-ref/source` after building the `Contribs` solution. These are copied
378   post-build from their original location in
379   `source/contrib/bin/8.0/$(Platform)`.
380 - Make sure `freetype.lib`, `libpng.lib`, `lua.lib`, `pcre.lib`, `SDL2.lib`,
381   `SDL2_image.lib`, `SDL2main.lib`, `sqlite.lib`, and `zlib.lib` are in
382   `source/contrib/bin/8.0/$(Platform)` after building the `Contribs` solution.
383 - Make sure `crawl.exe` and `tilegen.exe` are in `crawl-ref/source` after
384   building the `crawl-ref` solution.
385 - `tilegen.exe` runs early during the `crawl.exe` build process, using
386   `libpng.dll` to build PNG files inside `source/rtiles`. Breaking tilegen
387   (e.g. by building a different `Contribs` configuration) after building these
388   png files correctly will result in `tilegen.exe` crashing during the crawl
389   build process, but will not stop the build from working.  `fresh.bat` inside
390   the MSVC folder will clear these files, making sure `tilegen.exe` stops the
391   build process if it fails.
392
393 ## Advanced
394
395 DCSS looks for several data files when starting up. They include:
396
397 * Special level and vault layout (`dat/*.des`) files.
398 * Core Lua code (`dat/dlua/*.lua`).
399 * Descriptions for monsters and game features (`dat/descript/*.txt`).
400 * Definitions for monster dialogue and randart names (`dat/database/*.txt`).
401
402 All these files are in the source tree under `source/dat`.
403
404 DCSS will also look for documentation files when players invoke the help
405 system. These files are available under the docs directory.
406
407 Your built DCSS binary must be able to find these files, or it will not start.
408
409 If DCSS is built without an explicit `DATA_DIR_PATH` (this is the most common
410 setup), it will search for its data files under the current directory, and if
411 it can't find them there, one level above the current directory. In short, it
412 uses these search paths: `.`, `./dat`, `./docs`, `..`, `../dat`, `../docs`.
413
414 ### ccache
415
416 If you're recompiling DCSS many times (eg while developing features), `ccache`
417 can significantly speed up this process. It is generally easy to install and
418 set up.
419
420 On Linux, try installing the `ccache` with your package manager. You will need
421 to add the ccache directory to your `PATH`.
422
423 On macOS, run `brew install ccache` and follow the instructions to update your
424 `PATH`.
425
426 ### Installing For All Users
427
428 You might want to install DCSS if you want to allow all users on your machine
429 to play it.
430
431 Use `make install prefix=/usr/local` to build and install DCSS.
432
433 Make options:
434
435 * `prefix`: Specify the prefix to install to. You probably want `/usr` or
436   `/usr/local`
437 * `SAVEDIR`: defaults to `~/.crawl`
438 * `DATADIR`: defaults to `$prefix/share/crawl`
439
440 ### .des level compiler
441
442 DCSS uses a level compiler to read the level design (.des) files in the
443 `source/dat` directory.
444
445 If you're using one of standard makefile, the steps described in this section
446 are performed automatically:
447
448 The level compiler source is in the `source/util` directory (`levcomp.lpp` and
449 `levcomp.ypp`). The steps involved in building the level compiler are:
450
451 * Run `flex` on `levcomp.lpp` to produce the `levcomp.lex.cc` lexer.
452 * Run `bison` on `levcomp.ypp` to produce the `levcomp.tab.cc` parser and
453   `levcomp.tab.h`
454 * Compile the resulting C++ source files and `levcomp.cc` and link the object
455   files into the DCSS executable.
456
457 For convenience on systems that don't have flex/bison, pre-generated
458 intermediate files are provided under `source/prebuilt`. The makefiles provided
459 with the DCSS source distribution will use these pre-generated files
460 automatically if flex/bison is not available.
461
462 ### Code Coverage
463
464 Code coverage requires some more package to be installed. See
465 [testing.md](crawl-ref/docs/develop/testing.md) for more info.
466
467 ### Lua
468
469 The Lua source is included with DCSS. It will be used if you don't have Lua
470 headers installed. Note that we don't provide security support for Lua, and
471 thus if you run a public server or a kiosk, it is strongly recommended to use
472 system Lua which does receive security updates from whatever distribution you
473 use.
474
475 ### PCRE
476
477 PCRE 8.12, with a custom build system but otherwise unchanged, is included with
478 DCSS. It is enabled by default on Windows; otherwise, unless you build with
479 `BUILD_PCRE=y` (to use the contrib) or `USE_PCRE=y` (to use a development
480 package from your manager), the system POSIX regex will be used.
481
482 ### Unicode
483
484 On Unix, you want an UTF-8 locale. All modern distributions install one by
485 default, but you might have somehow dropped required settings. To check this,
486 run `locale charmap`, which should say `UTF-8`. If it's not, please ensure
487 either `LANG`, `LC_ALL` or `LC_CTYPE` is set. A typical line would be `export
488 LC_ALL=en_US.UTF-8`.
489
490 On Windows, the console behaves differently for TrueType and legacy (bitmap)
491 fonts. The latter (mostly) work only on certain language editions of Windows,
492 such as English, and even there, they work adequately only for DCSS's default
493 settings. For anything more, please select one of TrueType fonts. If, like one
494 of our players, you are deeply attached to the looks of bitmap fonts, you can
495 [download a corrected version of the Terminal
496 font](http://www.yohng.com/software/terminalvector.html)
497
498 ## Getting Help
499
500 The best place to ask for help is `##crawl-dev` on Freenode IRC, where
501 developers chat.
502
503 You can also try [any of the community forums detailed in the
504 README](../README.md#community).