Install instructions for Dungeon Crawl Stone Soup (DCSS)
--------------------------------------------------------

Getting Crawl to run
--------------------

This file describes how to compile a runtime executable of Crawl from the
source code. If you're trying to compile Crawl yourself, skip ahead to the next
section, "Building Crawl".

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 Crawl
--------------

Crawl is known to run on the following platforms:

- Any Unix with GNU or BSD userland.
- Mac OS X.
- Android.
- Microsoft Windows 2000/XP/Vista/7/8/10

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.

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. MSYS2 users
should have Git if they followed the installation instructions in the MSYS2
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 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 sound.h), or by an external command on Unix systems
(SOUND_PLAY_COMMAND in sound.h). To enable this, append SOUND=y to the make
invocation.

Crawl 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 python-yaml libsdl2-image-dev \
      libsdl2-mixer-dev libsdl2-dev libfreetype6-dev libpng-dev ttf-dejavu-core

(the last six 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 python-yaml 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 (Void):

On Void Linux you can get all dependencies by running the following as root:

    xbps-install make gcc perl flex bison pkg-config ncurses-devel lua51-devel \
      sqlite-devel zlib-devel python-yaml pngcrush dejavu-fonts-ttf \
      SDL2-devel SDL2_mixer-devel SDL2_image-devel freetype-devel

(the last six are needed only for tile builds).

ccache can be installed with:

    xbps-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.

Python and PyYAML is required to parse some data files.

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'.

* For information Makefile settings beyond what is here, see the documentation
  in comments in the Makefile itself.

* 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).

* To be specific, specifying a prefix means adding "prefix=foldername" to your
  'make' command. Specifying a prefix is not mutually exclusive with specifying
  a SAVEDIR; you can set them to completely unrelated directories if desired.

* 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. To build Crawl on
a Mac you could use the following example command lines.

For the console version:
  make
For the graphical version:
  make TILES=y


Building on Windows (MSYS2)
---------------------------

This is the only currently recommended process for building Crawl on windows.
It is also possible to cross-compile windows builds; see the release guide
for instructions.

MSYS2 is a Cygwin-derived software distro for Windows that can build
native applications; you will interact with the build process in a unix-like
shell interface. You can download the MSYS2 installer from the following
website:

https://msys2.github.io/

You generally want to install the 64-bit version of MSYS2 unless you have a
specific reason to build a 32-bit version of crawl. Follow all of the steps you
see on that page to install MSYS2, but please read the additional notes below.
In particular, when starting the MSYS2 Shell, be sure to run the 64-bit MinGW
version of the MSYS2 shell and *not* the version labeled 'MSYS2 MSYS' or the
32-bit version.

* The installer will put all MSYS2/MinGW files into a folder of your choice,
  which defaults to 'C:\msys64'. If you have crawl-related work files from
  other directories that you'd like to carry over, you can copy them into
  'C:\msys64\home\<Username>', where <Username> is your Windows username. This
  is the path to your MSYS2 home directory. From the MSYS2 shell you can always
  get back to here with `cd ~`.

* After the installer finishes, start the MSYS2 shell ("MSYS2 MinGW 64-bit")
  and do steps 5-6 from the MSYS2 install instructions in order to update your
  installation. These steps are repeated here:

    5. At the command line, run `pacman -Syu` to update the core packages.
       Then restart your MSYS2 shell. (The installer will force you to restart.)

    6. At the command line, run `pacman -Su` to update all packages.

After MSYS2 is fully installed and updated, follow steps below to install
development packages and compile Crawl. The commands shown below should be run
from within the MSYS2 Shell.

* To install git and the base development packages, run:

  pacman -S base-devel git

  Accept the default action to install all packages in base-devel, and say yes
  to any questions about installing packages or removing packages due to
  conflicts.

* To install the mingw-w64 GCC toolchain for your system, run:

  pacman -S mingw-w64-x86_64-toolchain

* At this point on current MSYS2 versions, your development environment should
  be complete. You can test it by running:

  gcc -v

  If this works, you're all set. If it doesn't, you may be an an older version
  of MSYS2 and need to manually add the newly installed toolchain to your
  path. To do so, run the following line, either at the command line (for
  that shell instance only) or in the file `~/.bashrc` to make it permanent:

  export PATH=$PATH:/mingw64/bin

  After the packages are installed and gcc runs, you're ready to build crawl!

* To install PyYAML, you can install it from Pip/PyPA:

  pacman -S mingw64/mingw-w64-x86_64-python2-pip
  pip install pyyaml

  You can verify PyYAML is installed by running `python -m yaml`, which should
  give an error like "'yaml' is a package and cannot be directly imported"
  (rather than "No module named yaml").

* To get the Crawl source, follow the steps in the Source Code Checkout
  section above to clone Crawl into your MSYS2 home directory. We recommend
  using the MSYS2-installed version of git for these steps. In brief:

  1. `cd` to the location where you would like the crawl repository to be. It
     will clone into a folder named `crawl`. Your home directory (`cd ~`) is
     a reasonable choice.
  2. Run `git clone https://github.com/crawl/crawl.git`.
  3. Run `cd crawl/crawl-ref/source`.
  4. Run `git submodule update --init`.

* Build the console version of Crawl by simply running:

  make

  If you want a graphical build, you will need to add 'TILES=y':

  make TILES=y

  If you want a debug build, add the target `debug` to the above commands.
  For building packages, see instructions in the release guide.

* When the build process finishes, you can run crawl.exe directly from the
  source directory in the MSYS2 shell. For Tiles, type './crawl.exe', and for
  console, type 'start crawl', which will open Crawl in a new command.exe
  window (the Windows version of Crawl requires a command.exe shell and will
  not run in an MSYS2 shell). Both versions can also be started by
  double-clicking crawl.exe using the graphical file explorer.

Building on Windows (Cygwin)
----------------------------

* This build process is not currently supported.

* 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 10 (Linux Subsystem)
--------------------------------------------------------------------

* Follow the instructions on Microsoft's website at
  https://docs.microsoft.com/en-us/windows/wsl/install-win10 to set up the
  Windows Subsystem for Linux.

* Make sure to run 'apt-get update' to get the latest versions of the package
  lists, if using Ubuntu.

* Follow the Linux instructions to build Crawl.

* Console and Webtiles will work without any further configuration. To get SDL
  tiles to work, you need an X server running on Windows; Xming is an option
  that has worked in the past. If you run into an error about not finding a
  matching GLX visual, try running:

  export SDL_VIDEO_X11_VISUALID=


Building on Windows (MSVC)
--------------------------

* This build process is currently unofficially supported, and unlikely
  to be straightforward in versions of MSVC besides those explicitly mentioned
  here.

* You will need to download crawl, as well as its submodules. The easiest way to do
  this is with the commands
  `git clone https://github.com/crawl/crawl.git`
  `git submodule update --init`

* This build is tested on Visual Studio 2017 15.8.7 on Windows 8.1 and 10.
  Supported configurations are Debug/Release;Console/Tiles;Win32/x64

* 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 inside crawl-ref/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).

* To build the Debug version, first build Release, then re-build with the Debug
  configuration set. You will need to re-build the Contribs solution as well.
  Building the Debug version without first building the Release configuration will
  result in an error on startup.

* 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 crawl-ref/source/contrib.
  Make sure to set "Release" or "Debug" (not the library versions), as well as
  the desired architecture (Win32 or x64). Then build (or re-build) the solution.

* Open crawl-ref.sln in Visual Studio, this is in crawl-ref/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"). Note: the Release build can
  still be debugged using the Visual Studio debugger.

* Building the webserver and Lua (for the dat project) is untested as of now.

* 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.

* Maintenance notes:

  MSVC solution files are finicky. Opening the "All Configurations" or
  "All Platforms" will automatically change settings. This is typically unwanted.

  Troubleshooting tips:

  Make sure Windows Universal C Runtime is installed in MSVC.

  Build Release before rebuilding both solutions with Debug

  Use "Rebuild Solution" to make sure all files are rewritten

  Make sure all projects use /MD (or /MDd for the debug version)

  Make sure the appropriate (/MD or /MDd) CRT libraries are included for SDL,
  crawl, and tilegen (https://msdn.microsoft.com/en-us/library/abx4dbyh.aspx)

  Make sure libpng.dll, SDL2.dll, and SDL2_image.dll are in crawl-ref/source
  after building the Contribs solution. These are copied post-build from their
  original location in source/contrib/bin/8.0/$(Platform).

  Make sure freetype.lib, libpng.lib, lua.lib, pcre.lib, SDL2.lib, SDL2_image.lib,
  SDL2main.lib, sqlite.lib, and zlib.lib are in source/contrib/bin/8.0/$(Platform)
  after building the Contribs solution.

  Make sure crawl.exe and tilegen.exe are in crawl-ref/source after building the
  crawl-ref solution.

  Tilegen runs early during the crawl.exe build process, using libpng.dll to build PNG files
  inside source/rtiles. Breaking tilegen (e.g. by building a different Contribs configuration)
  after building these png files correctly will result in tilegen crashing during the crawl build
  process, but will not stop the build from working (until it breaks for some other reason). fresh.bat
  inside the MSVC folder will clear these files, making sure tilegen stops the build process if it fails.

  tilegen depends on SDL2, SDL2_image, and libpng.
  crawl depends on SDL2, SDL2_image, libpng, lua, pcre, sqlite, zlib, and the CRT libraries.
  freetype uses the zlib source directory as an include.
  libpng depends on zlib, and uses the zlib source directory as an include.
  SDL2_image depends on SDL2 and SDL2main.
  SDL2 depends on winmm.lib,imm32.lib,version.lib, and the CRT libraries.

*****************************************************************************

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
