path: root/crawl-ref/INSTALL

Install instructions for Dungeon Crawl Stone Soup (DCSS)
--------------------------------------------------------
(Last updated on 20061107 for Dungeon Crawl Stone Soup 0.1.3.)

Building Dungeon Crawl Stone Soup
---------------------------------
Crawl Stone Soup is known to compile successfully on the following platforms as
of version 0.1:

- Any Unix with a recent gcc (and g++), GNU make and libncurses, including
  Linux and Mac OS X.
- Microsoft Windows NT/2000/XP. The game will also run on Windows 9X and ME.
  DOS binaries can also be compiled on Windows NT+.

The only supported compiler is gcc (available on almost all Unixes, and as djgpp
for DOS, and MinGW for Windows).

Other platforms are unsupported, but you should be able to build Crawl on
pretty much any operating system with a modern C++ compiler (full support for
the standard C++ library, in particular <string>, the collection classes and
<algorithm> is necessary) and the curses library.


Optional libraries
------------------
Crawl can be built with some optional features:
* Sounds
* Regular expressions
* Lua support

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.

Sounds must be enabled by editing AppHdr.h (uncomment SOUND_PLAY_COMMAND on
Unixes or WINMM_PLAY_SOUNDS on Windows).

Regular expressions require libpcre on non-Unix operating systems. On Unixes,
the standard POSIX regular expression support is adequate for Crawl's needs.

Lua support requires liblua, which you can build by downloading the sources from
www.lua.org. On most Unixes, you can also use the native package management
system to easily install lua.


Makefile system
---------------
Crawl uses a selector makefile (under source/makefile) to control what platform
it's building for. Your first step in building Crawl should be to edit
source/makefile and point it at the correct platform makefile. For instance, if
you're building for Windows, you'd use MAKEFILE=makefile.mgw to build with MinGW
for Windows (# is used for comments in makefiles).

Consult the operating-system specific sections for detailed information on
building Crawl.


Building on Unix (Linux, *BSD, Solaris, etc.)
---------------------------------------------

* Prerequisites:

GNU gcc and g++, GNU make, libncurses or libcurses. You need the
development headers for ncurses - they may not be installed by default
on some Unixes.

flex and bison are optional but highly recommended. Recent versions of
byacc are also fine (edit your makefile appropriately).

* Building:

* cd to the source directory (you can safely ignore the dolinks.sh and
  domake.sh scripts).

* Edit makefile and make sure that MAKEFILE=makefile.unix is uncommented and
  all other MAKEFILE= lines are commented out.

* Edit AppHdr.h and check that SAVE_DIR_PATH, SAVE_PACKAGE_CMD and
  LOAD_UNPACKAGE_CMD are set correctly for your system. If you do not want your
  saves packaged in a zip archive, it's safe to comment out SAVE_PACKAGE_CMD and
  LOAD_UNPACKAGE_CMD.

* If you don't have flex or bison, edit makefile.unix and set DOYACC := n. If
  you want to use byacc instead of bison, edit makefile.unix and set YACC :=
  byacc. On some Linuxes you may not have lex symlinked to flex, in which case
  you'll have to set LEX := flex in makefile.unix.

* Run make to build the normal (non-wizard) Crawl. On systems such as Solaris,
  you may have to use gmake for GNU make. Make sure your make identifies itself
  as GNU make when you do make --version.

* If you have Lua, you can edit AppHdr.h and uncomment
        // #define CLUA_BINDINGS
  then add -llua to your LIB = line in makefile.unix, and rebuild to compile with
  Lua support.


Building on Mac OS X
--------------------
You can follow the Linux instructions to build Crawl (but note you still need to
install Xcode to get gcc and make), or alternatively you can use Xcode.

* Crawl has been tested with Xcode 2.4 under OS X 10.4.7 on both PPC and Intel
  machines, but is likely to be buildable with earlier versions.

* Make sure Xcode is installed. Xcode should be available on the OS X install
  DVD if you haven't already installed it.

* Open the Xcode project (Crawl.xcodeproj) under the "source" directory.

* Hit Build in Xcode.

* The default build configuration, Release, will build a ppc/i386 Universal
  binary suitable for play on all OS X 10.3.9 or newer systems. The other build
  configurations are intended for development and may not result in a binary
  that can be distributed to others.

* You can also use makefile.osx, which will run xcodebuild from the command line.

* If you have Lua installed, you can add your lua headers and liblua library to
  the 'Crawl' target in the Xcode project, uncomment the '#define CLUA_BINDINGS'
  line in AppHdr.h, and rebuild to compile with Lua support.


Building on Windows
-------------------

NOTE: Building for Windows+MinGW on Windows 9x/ME may work, but we've not tested
it. You may be better off using the DOS build instructions if you're on 9x/ME.

We've also not tested or updated the makefile for Borland C++. We strongly
recommend using MinGW if possible.

* Install MinGW from http://www.mingw.org. The MinGW 5.0.2 installer is best so
  you don't have to fiddle with individual packages (you can mess with the
  individual packages if you like to, of course). If you want to edit the level
  compiler, also get the flex and bison packages (available from the GnuWin32
  project on Sourceforge: http://gnuwin32.sourceforge.net/).

* Make sure you have g++ and mingw32-make in your path.

* cd to the the Crawl source directory.

* Build Crawl by running
        mingw32-make MAKEFILE=makefile.mgw

* If you have Lua and/or libpcre, you can edit AppHdr.h and uncomment 
  these lines:
        // #define CLUA_BINDINGS
  and
        // #define REGEX_PCRE
  Note that there are multiple // #define REGEX_PCRE lines in AppHdr.h - find
  the one in the Windows-specific section.

* If you have flex and bison, edit makefile.mgw and set DOYACC := y.

* Add -llua and -lpcre to the LIB line in makefile.mgw as:
        LIB = -lwinmm -static -llua -lpcre
  and build Crawl to include Lua and regex support.

* When you're done, you should have crawl.exe under a "rel" subdirectory.


Building on DOS
---------------

* Install djgpp from http://www.delorie.com/djgpp/. Don't forget to include C++
  support when the Zip picker asks for what you want. You may also have to
  download GNU make as a separate package. It's important to follow the install
  instructions carefully, because bad installs can produce rather confusing
  error messages.

* Make sure gxx and make are in your PATH.

* If you want to modify the level compiler, install the djgpp flex, bison and m4
  packages and set DOYACC := y in makefile.dos.

* cd to the Crawl source directory.

* Build Crawl by running
        make MAKEFILE=makefile.dos

* If you have Lua and/or PCRE, edit makefile.dos and change this line:
        CFLAGS = -D$(OS_TYPE) $(EXTRA_FLAGS)
  to
        CFLAGS = -D$(OS_TYPE) $(EXTRA_FLAGS) -DCLUA_BINDINGS -DREGEX_PCRE
  Add -llua and -lpcre to the LIB line in makefile.dos, like so:
        LIB = -llua -lpcre
  then build Crawl.

* When the build is done, crawl.exe should be in the source directory.

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

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 the standard makefiles, 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.

*****************************************************************************
Optional Libraries
------------------

Lua
---
NOTE: When linking in Lua, the makefile LIB line usually looks like this:

LIB = -llua

If you're using Lua older than 5.1, though, the Lua library comprises of *two*
libraries: liblua and liblualib (yes, confusing), so you need

LIB = -llua -llualib

This also depends on how you install Lua - some package management
systems build just the plain old liblua.so even for pre 5.1 Lua. If in
doubt, try both "-llua -llualib" and "-llua".

On many Linuxes, the package management system installs Lua libraries
including the version number, so the linker option becomes something
like:

LIB = -llua50


Getting Lua:

On Unixes your package management system is the best way to get Lua. Make
sure to install the development headers and not just the naked library.

On Windows, Lua binaries are available on luaforge.net. You should find links to
get binaries from www.lua.org.

On DOS, you get the joy of compiling Lua yourself. It's not hard, and you can
use the existing Windows support in the Lua makefiles with some minor
modifications, but you may be better served using the official Crawl Stone Soup
binaries if you want Lua with your Crawl and don't want to compile Lua.


PCRE
----
On Unixes, you're better served by the existing POSIX regular expression
support. If you want PCRE, your package management system is again your best
bet. Remember to install development headers, not just the plain library.

On Windows, PCRE binaries are available from 
http://gnuwin32.sourceforge.net/packages/pcre.htm

On DOS you get the joy of building PCRE yourself. It's a little more annoying
than building Lua (you have to roll your own makefile), but not by much.