From 6adb570984828b2c36de2952c18e722641fbf802 Mon Sep 17 00:00:00 2001 From: dshaligram Date: Wed, 22 Nov 2006 08:44:28 +0000 Subject: Merged stone_soup r15:451 into trunk part 2 (non-source changes). git-svn-id: https://crawl-ref.svn.sourceforge.net/svnroot/crawl-ref/trunk@453 c06c8d41-db1a-0410-9941-cceddc491573 --- crawl-ref/INSTALL | 277 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 277 insertions(+) create mode 100644 crawl-ref/INSTALL (limited to 'crawl-ref/INSTALL') diff --git a/crawl-ref/INSTALL b/crawl-ref/INSTALL new file mode 100644 index 0000000000..6e8e26f1ee --- /dev/null +++ b/crawl-ref/INSTALL @@ -0,0 +1,277 @@ +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 , 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. + +flex and bison are optional but highly recommended. Recent versions of byacc are +also fine. + +* 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 +------------------ +(NOTE: The level compiler is not in its final form yet; these instructions are +likely to change for future releases.) + +Crawl uses a level compiler to convert the human-readable level design (.des) +files in the source/dat directory into code that's compiled into Crawl. + +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 with mapdef.cc (in the main source + directory) and levcomp.cc to produce the levcomp executable. + +Once you've built the level compiler, run it on the .des files in source/dat and +append the results to mapdefs.ixx: + +levcomp(.exe) mapdefs.ixx < dat/vaults.des +levcomp(.exe) -a mapdefs.ixx < dat/splev.des +(the -a option tells levcomp to append to mapdefs.ixx instead of overwriting the +existing contents.) + +When mapdefs.ixx is built, Crawl can be compiled as before. mapdefs.ixx is +#included in maps.cc. + +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. + +If you're using an Integrated Development Environment and don't want to modify +the level design files at all, a pre-generated mapdefs.ixx is provided in +source/prebuilt - you can add source/prebuilt as an include directory and build +Crawl as before. (This is not necessary if you're using Xcode on OS X +- the Xcode project provided with the source distribution is aware of the level +compiler and will build and use it automatically.) + +***************************************************************************** +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 + + +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. -- cgit v1.2.3-54-g00ecf