Apply my recent commits to trunk.

git-svn-id: https://crawl-ref.svn.sourceforge.net/svnroot/crawl-ref/trunk@9978 c06c8d41-db1a-0410-9941-cceddc491573

1 files changed, 427 insertions, 0 deletions

diff --git a/crawl-ref/INSTALL.txt b/crawl-ref/INSTALL.txt
new file mode 100644
index 0000000000..a3838a1983
--- /dev/null
+++ b/crawl-ref/INSTALL.txt
@@ -0,0 +1,427 @@
+Install instructions for Dungeon Crawl Stone Soup (DCSS)
+--------------------------------------------------------
+(Last updated on 20071202 for Dungeon Crawl Stone Soup 0.3.3.)
+
+Building Dungeon Crawl Stone Soup
+---------------------------------
+
+Crawl Stone Soup is known to compile successfully on the following
+platforms as of version 0.3:
+
+- 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 <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
+* User Lua scripts
+* Unicode characters for the map (Unix only).
+
+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.
+
+Stone Soup 0.3 includes Lua 5.1.2 in its source tree. 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 removing
+-DCLUA_BINDINGS from your makefile.
+
+Unicode support needs libncursesw and its header files; these are
+usually available in your operating system's package-management
+system. Unicode is not supported on Windows or DOS. Some systems, such
+as Mac OS X, may have Unicode support available in libncurses itself
+(i.e., without a separate libncursesw).
+
+
+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. When you're done building Crawl, look
+at the section "Data files" for important information on what files
+Crawl needs as it starts up.
+
+
+Building on Unix (Linux, *BSD, Solaris, etc.)
+---------------------------------------------
+
+Security:
+
+If you have untrusted local users, we highly recommend you do not
+install Crawl setgid or setuid. Just running "make install" will install
+Crawl setgid games, do *not* do this unless you're sure you trust your
+users.
+
+If you have untrusted users, the correct way to install a multiplayer
+Crawl is using a chrooted game launcher such as dgamelaunch.
+
+
+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:
+
+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).
+
+If you want to use Unicode, 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.) You also need to have a UTF-8 locale installed.
+You can then build Crawl with support for Unicode by setting
+UNICODE_GLYPHS = y in makefile.unix.
+
+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 do not want players to be able to script Crawl with Lua,
+  edit makefile.unix and remove -DCLUA_BINDINGS from the CFOTHERS line.
+
+
+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'd like users to be able to script Crawl with Lua, you can
+  edit AppHdr.h, uncomment
+        // #define CLUA_BINDINGS
+  and rebuild to compile with Lua support. See the section on Lua
+  for more information.
+
+
+Building on Windows (MinGW)
+---------------------------
+
+NOTE: You cannot build Windows binaries on Windows 9x/ME using the
+MinGW makefile supplied (which needs the cmd.exe shell of the Windows
+NT family). If you're on 9x/ME, you can 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 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 install
+
+* If you have flex and bison, edit makefile.mgw and set DOYACC := y.
+
+* 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,
+  libncurses-devel. 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
+
+* When the build is done, crawl.exe should be in the source directory.
+
+Building Tiles versions
+-----------------------
+
+* For Windows builds, run
+         make MAKEFILE=makefile_tiles.mgw
+
+* For Linux builds, run
+         make MAKEFILE=makefile_tiles.unix
+
+* For Mac OS X builds, run
+         make MAKEFILE=makefile_tiles.unix OSX=y
+
+* If you compiled the ASCII binary before you'll need to run make clean
+  before running make.
+
+* All platforms require the same prerequisites listed in the other
+  sections above for building each of these platforms.
+
+* All platforms additionally require the development versions of the following
+  software packages installed.
+
+    * SDL (http://www.libsdl.org/download-1.2.php)
+    * SDL_image (http://www.libsdl.org/projects/SDL_image/)
+    * libpng (http://www.libpng.org/pub/png/libpng.html)
+    * Freetype 2 (http://www.freetype.org/download.html)
+
+  On Mac OS X, these are expected to be installed via fink in /sw.  On Linux,
+  these can be installed via a package manager.  On Windows, they should be
+  installed, compiled, and the headers and libs placed in a location that the
+  compiler can find them via its default include and library paths.
+
+* If you want both ASCII and Tiles binaries you need to compile them
+  separately, rename one of them, and copy them into the same Crawl
+  directory.
+
+*****************************************************************************
+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/clua/*.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.
+
+If Crawl is built with an explicit DATA_DIR_PATH (for multiuser
+installs on Unix), it will look for its startup files strictly under
+that directory: $DIR, $DIR/dat, $DIR/docs.
+
+As Crawl loads its startup files, it will convert them to a binary
+format (so that future startups will be faster) and store these binary
+files in the saves directory. These binary files (with extensions .db,
+.dsc, .idx, .lk) can be safely deleted as long as there is no running
+Crawl, and they will be regenerated the next time Crawl starts.
+
+*****************************************************************************
+
+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
+---
+
+Security on multiuser systems (Unix):
+
+Enabling Lua user scripts is unsuitable for Crawl installed setuid or
+setgid - we have not audited the user scripting interface for
+security. If you're not planning to install Crawl setuid/setgid (not
+running set[ug]id is a good idea in general), you can enable the Lua
+user-script bindings safely.
+
+As of 0.3, the Lua source is included with Crawl. The only step needed
+to enable user-scripts is to uncomment CLUA_BINDINGS in AppHdr.h.
+
+
+PCRE
+----
+As of 0.4.2, PCRE 7.7 source is included with Crawl.  It is enabled
+by default.  The sources in pcre/util are identical to the 7.7 distro
+except for removed cmake, doc, and testdata folders (unused by Crawl)
+and a hand-rolled Makefile.
+
+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.
+
+Unicode (Unix only)
+-------------------
+
+Modern Unixes may support Unicode terminals (particularly xterms). If
+you have a terminal that can display Unicode characters, and an
+ncurses library that can handle Unicode (libncursesw, and its devel
+headers), you can build Crawl to display Unicode in the map: set
+UNICODE_GLYPHS = y in makefile.unix.
+
+On Mac OS X, libncurses includes Unicode support; makefile.unix should
+detect Mac OS automatically and link to libncurses when
+UNICODE_GLYPHS=y.
+
+NOTE: You may have libncursesw, but not have the header files; check
+that you have the header files installed as well, or you'll get a lot
+of errors. Crawl expects the ncursesw headers to be in
+/usr/include/ncursesw.
+
+After compiling Crawl with Unicode support, you still need to add the
+line "char_set = unicode" in your .crawlrc to tell Crawl to use
+Unicode. You may also need to set the locale in your terminal (notably
+on Mac OS) if the encoding does not default to UTF-8. To check this,
+run "locale charmap", which should say "UTF-8". If your encoding is
+not UTF-8, you can force it to UTF-8 on most systems by doing "export
+LC_ALL=en_US.UTF-8" or the equivalent, depending on your language
+locale and what shell you're using.
+
+Crawl tries to use en_US.UTF-8 as its default Unicode locale. If you
+do not have this locale installed, but do have some other UTF-8 locale,
+you can tell Crawl to use your preferred UTF-8 locale by setting
+UNICODE_LOCALE = ${foo}.UTF-8 in makefile.unix, where ${foo} is your
+locale name.
+
+You may not want to embed the locale in Crawl itself, but have Crawl
+use the locale as set in the environment LC_* variables. In such
+cases, you can use UNICODE_LOCALE = . in makefile.unix. Crawl will
+then use the locale as set in your environment.
+
+If you're playing Crawl on a remote machine, the remote Crawl should be
+built with Unicode support, it needs to have a UTF-8 locale installed,
+*and* your local terminal (where you're running telnet/ssh) needs to be
+able to decode UTF-8.