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.2: - Any Unix with a recent gcc (and g++), GNU make and libncurses, including Linux and Mac OS X. "Recent" is defined as gcc 3.3 or newer. - 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 , the collection classes and 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. * If you want to install Crawl for multiple users, edit makefile.unix and set SAVEDIR and DATADIR to appropriate directories. This is not necessary if only one user is going to play Crawl. Also check INSTALLDIR and change it if necessary. * Edit AppHdr.h and check that 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 (or don't want to use) 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 Unixes, you may not have flex (but have some other lex), in which case you'll have to set LEX := lex 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're installing Crawl for multiple users, run make install. Crawl will be copied into the directory specified by INSTALLDIR. The save and data directories will be created if necessary, and the level layout (.des) and help files will be copied to the data directory. * 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. See the section on Lua (below) for more information. Building on Mac OS X -------------------- You can follow the Unix instructions to build Crawl (but note you still need to install Xcode to get gcc and make), or alternatively you can use Xcode. Note that the Unix instructions will build Crawl assuming that your terminal can display 16 colours. If you're planning to use Terminal.app (which supports only 8 colours), you should follow the Mac build instructions below. * 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 (MinGW) --------------------------- NOTE: You cannot build Windows binaries on Windows 9x/ME using the MinGW makefile supplied. If you're on 9x/ME, you can choose to use the Cygwin build instructions, or build a binary on a Windows NT/2k/XP system (the binary will run on 9x), or build a DOS binary. * 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 Windows (cygwin) ---------------------------- * Get Cygwin from http://www.cygwin.com/. When installing, ensure that the following packages are selected: gcc, g++, make, flex, bison. If you'd like to build from svn, install the svn client. You may also want to install diff and patch if you'd like to apply third party patches, or create your own. * Once Cygwin is installed, open a Cygwin bash shell (use the Start menu, do not double-click bash.exe in Explorer). cd to the Crawl source directory. * Follow the Linux build instructions to build Crawl. Building for DOS (djgpp) ------------------------ * 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 and PCRE) --------------------------------- 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 (Debian, for instance), the package management system installs Lua libraries including the version number, so the linker option becomes something like: LIB = -llua50 Lua include path: On Unix, Lua headers may be installed in /usr/include (unlikely), or in a subdirectory of /usr/include (such as /usr/include/lua50/). If the headers are in a subdirectory, you need to add this directory to the include path in your makefile.unix: INCLUDES = -I/usr/include/ncurses -I/usr/include/lua50 On other platforms, the Lua headers should usually be installed in your compiler's include directory, or a subdirectory. If it's in a subdirectory, you'll need to add the full directory path to your includes line. 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.