SCCS Id: @(#)Install.dos 3.4 2000/08/02 Copyright (c) NetHack PC Development Team 1990-2000. NetHack may be freely redistributed. See license for details. ============================================================== Instructions for compiling and installing NetHack 3.4 on a DOS system ====================================================== (or, How to make PC NetHack 3.4) Last revision: August 2, 2000 Credit for a runnable full PC NetHack 3.4 goes to the PC Development team of Paul Winner, Kevin Smolkowski, Michael Allison, Yitzhak Sapir, Bill Dyer, Timo Hakulinen, Yamamoto Keizo, Mike Threepoint, Mike Stephenson, Stephen White, Ken Washikita and Janet Walz. The present port is based on the previous effort of Pierre Martineau, Stephen Spackman, Steve Creps, Mike Threepoint, Mike Stephenson, Norm Meluch and Don Kneller. CONTENTS: I. Dispelling the Myths II. Compiling on a DOS machine Appendix A - Building the "official binaries" Appendix B - Building other binaries Appendix C - Microsoft C Compiler notes Appendix D - DJGPP Compiler (gcc ported to msdos) notes Appendix E - Borland C++ Compiler notes Appendix F - Microsoft C Compiler Warnings Appendix G - Additional Notes Appendix H - Contacting Us I. Dispelling the Myths: Compiling NetHack is not as easy as it sounds, nor as hard as it looks, however it will behoove you to read this entire file through before beginning the task. We have provided the proper makefiles for building NetHack using the following compilers: Microsoft C 7.0 and Microsoft Visual C++ Professional (MSVC) 1.52c djgpp V2.0 or later Borland C V3.1 For specific details concerning each compiler, please see the corresponding appendix. The makefile named Makefile.MSC is for use with Microsoft's NMAKE, the make utility that ships with the Microsoft C Compiler version 7.0 and above, including the 16-bit Microsoft Visual C++ Professional. The makefile named Makefile.GCC is for use with GNU Make that accompanies djgpp. The makefile named Makefile.BC is for use with Borland's make that accompanies Borland C 3.1. Other versions of Borland's make may or may not work, but version 3.7 (of MAKE) is known to not work. If you want to build a copy of NetHack that is identical to the "official binaries", please see appendix A. You may find it useful to obtain copies of lex (flex) and yacc (bison or byacc). While not strictly necessary to compile nethack, they are required should you desire to make any changes to the level and dungeon compilers. Flex and Bison are included with the DJGPP distribution and are also available on many archive sites. II. To compile your copy of NetHack on a DOS machine: (or "just follow these few 'simple' steps outlined below.") 1. It almost goes without saying that you should make sure that your tools are set up and running correctly. 2. Make sure all the NetHack files are in the appropriate directory structure. You should have a main directory with subdirectories dat, doc, include, src, sys\share, sys\msdos, util, win\tty and win\share. Other subdirectories may also be included in your distribution, but they are not necessary for use with DOS. You can delete them to save space. If you are using MSC7 or MSVC, the makefile will create an additional working directory src\o. Required Source Directories for DOS NetHack: (top) | ------------------------------------------------- | | | | | | | util dat doc include src sys win | | ------ ----- | | | | share msdos tty share Check the file "Files" in your top level directory for an exact listing of what files are in which directory. In order for the Makefiles to work, all the source files must be in the proper locations. If you downloaded or ftp'd the sources from a UNIX system, the lines will probably end in UNIX-style newlines, instead of the carriage return and line feed pairs used by DOS. Some programs have trouble with them, so you may need to convert them (with a utility like Rahul Dhesi's "flip"). 3. A few files in the NetHack distribution are uuencoded because they contain non-ascii characters, or binary information. To use them they must first be decoded using a uudecode utility (available from your local archive site). After reading the descriptions of these files below, uudecode the ones that you will need in order to build NetHack with the options that you have decided you want. The uuencoded files that are relevant to NetHack on a DOS machine include: nhico.uu Optional. This uudecodes into a MS-Windows compatible ICON. You only need to uudecode this if you plan on launching NetHack from MS-Windows, and want a unique Nethack ICON to use. nhpif.uu Optional. This uudecodes into a MS-Windows compatible PIF file which may be used to launch NetHack from the MS-Windows program manager. You only need to uudecode this if you plan on launching NetHack from within MS-Windows. termcap.uu Optional. Termcap support is no longer required for building NetHack, though you can if you want to. The file termcap.uu is the fixed version of the Fred Fish termcap library. If you have modified pcconf.h to define TERMLIB as well as commented out the default #define NO_TERMS, then you will need to run a uudecode utility on termcap.uu to generate the file termcap.zip. termcap.zip contains several files of termcap routines. Using them with NetHack involves very little knowledge of the UNIX concept of a termcap database; mostly you need to know enough to set a TERM environment variable. You can unzip termcap.zip in the sys/share directory, but if you are going to use it, it is probably better to unzip a copy in a special directory and copy the library files to where your linker can find them. NetHack versions since 3.1.2 no longer enable the use of termcap in the default configuration, or with the official binaries. Makefiles are included should you want to build your own termcap library file. Makemsc.lib works with Microsoft C (MSC and MSVC) and generates termcap.lib, Makegcc.lib works with DJGPP and generates libtermc.a. 4. Go to the sys/msdos directory and ensure that the file setup.bat has MSDOS style end-of-line characters rather than UNIX style end-of-line characters. You can do that using a utility like Rahul Dhesi's "flip", or by invoking the MSDOS edit utility on setup.bat and saving the file without making any changes. Failure to do this will prevent the bat file from executing completely, yet no warning message will be given. Run the setup.bat batch file with one of the following as the argument: MSC For Microsoft C and its NMAKE. GCC For djgpp and GNU MAKE. BC For Borland C++ 3.1, and Borland's MAKE. The appropriate and necessary Makefile movements will be accomplished for you, as well as verifying a few files and fixing a few file names on FAT systems with long file name support. 5. Now go to the include subdirectory to check a couple of the header files there. Things *should* work as they are, but since you have probably set up your system in some sort of custom configuration it doesn't hurt to check out the following: First check config.h according to the comments to match your system and desired set of features. Mostly you need to check the WIZARD option, and check TERMLIB and COMPRESS. Also be sure to leave DLB support commented out in config.h. MSDOS has support for DLB, but it must be done through the Makefile, rather than config.h, to ensure that the necessary packaging steps are done. We've managed to enable all the special features. You may include all or as few of them as you wish. To conserve disk space, you may wish to disable LOGFILE and NEWS. Also check pcconf.h, which should not need much editing (if you are including random.c, and if you do not require termcap for screen management). If you are not including random.c you will need to comment out RANDOM. There are several options available for screen management with this release of PC NetHack. The features #define TERMLIB, #define ANSI_DEFAULT, and #define NO_TERMS in pcconf.h control the various options. The NO_TERMS feature (the default) has the advantage of not needing a DEVICE=ANSI.SYS statement in config.sys. The supplied sources and header files are distributed with support for NO_TERMS enabled. NO_TERMS will not work with TERMLIB, nor with ANSI_DEFAULT defined. The NO_TERMS feature uses internal routines for screen management, and may be an ideal choice if your play machine is industry standard (has an IBM compatible BIOS). Should you choose to leave NO_TERMS defined, define only one of the two screen access methods. If compiling for Microsoft compilers, use SCREEN_BIOS; if using DJGPP, you can choose between SCREEN_BIOS and SCREEN_DJGPPFAST. Never, never, ever choose both. Bad things will happen. We are not kidding. If you leave the #define TERMLIB commented in pcconf.h to disable use of termcap routines, then your screen management must rely on either the NO_TERMS feature described above, or the ANSI_DEFAULT feature. Either of these will make your job a bit easier than if you choose to use TERMLIB. If you elect to include TERMLIB support, you may compile with both TERMLIB and ANSI_DEFAULT, and simply not set your TERM variable if you do not wish to use the termcap file settings. You will need to uudecode the termcap library in sys\share if you are using the TERMLIB feature. 6. If you want to change the high score list behavior, examine the top of topten.c, in the src directory. You may want to change the definitions of PERSMAX, POINTSMIN, and ENTRYMAX. We set POINTSMIN to 51 and ENTRYMAX to 50 to keep the size of the score list down. 7. Go to the src directory and edit the top of your Makefile. Be sure the directory you want the game installed in (GAMEDIR) actually exists. If you elected to use termcap (TERMLIB defined), then uncomment the TERMLIB macro in your Makefile that points to the location of the library. That is, TERMLIB = should be TERMLIB = (SSYS)\termlib.lib If you are recompiling after patching your sources, or if you got your files from somewhere other than the official distribution, "touch makedefs.c" to ensure that certain files (onames.h and pm.h) are remade, lest potentially troublesome timestamps fool your make utility. a) For Borland C++ 3.1, Choose an overlay schema by setting SCHEMA to 1 or 2. If you change the overlay schema, you will need to recompile all the object modules from scratch since the overlay schema is information is used during compile time for Borland C++, unlike Microsoft C which does it during link time. b) For Microsoft C 7.0 or greater, and Microsoft Visual C++ The only overlay schema available is Schema3 so you don't have to choose one. The Makefile is set up for it already. The overlay description file src\Schema3.def is created from sys\msdos\Schema3.MSC by setup.bat. If you elected to add graphical tile support, set TILESUPPORT to Y. Set USE_DLB to Y if you wish to place NetHack's many runtime files into a special archive that NetHack can utilize. This is highly recommended! In fact, we haven't tested NetHack without it for several releases now. 8. Now that everything is set up, what you do next depends on which compiler and version you are using. You will need to execute either step 8a, or step 8b, or step 8c, but only one of them. a) For Microsoft C 7.0 or greater, and Microsoft Visual C++ Go to the src directory, and "nmake install". b) For djgpp Go to the src directory, and using the GNU Make utility, "make install". c) For Borland C V3.1 Go to the src directory, and using the Borland Make utility, "make -N install". Depending on your particular machine and compiler, you can either grab a cup of coffee or go home for the day. Your computer will be occupied for quite some time. If all goes well, you will get an NetHack executable. 9. If you chose DLB support (recommended), make sure that the file nhdat got copied into the game directory. If you didn't choose DLB support, make sure the support files -- data, rumors, cmdhelp, opthelp, help, hh,history, guidebook.txt license, and all the *.lev files -- were copied to the game directory. If not, move them there from the dat directory yourself. rumors can be created manually be entering "makedefs -r", data by entering "makedefs -d". Make sure the files NetHack1.tib and NetHacko.tib made it to your game directory. Copy them from src to the game directory yourself if necessary. Make sure the files defaults.nh and termcap made it to your game directory. If not, go to sys\share and copy NetHack.cnf to your game directory as defaults.nh. The name in previous versions was nethack.cnf, but the CNF extension conflicted with the MS Windows speed-dialer, making the file hidden on many machines. If you changed your build settings to include TERMCAP support, copy termcap to your game directory. Also, make sure the file msdoshlp.txt made it to your game directory. If it didn't, move it from sys\msdos to your game directory yourself. 10. In your game directory, review the settings in defaults.nh and adjust them according to your style of play. Some new options that you might be interested in are "menustyle" (for tailoring new object selection interface), and "video" (for turning on graphical tiles). On Borland C++, the soundcard:autodetect option enables pc speaker sound in NetHack if you compiled with PCMUSIC set in pcconf.h. It is rumored that this also works with djgpp, but the PCMUSIC setting in pcconf.h must be uncommented manually. 11. Play NetHack. If it works, you're done! Appendix A - Building the "official binaries" If you wish to build a copy of NetHack identical to the ones that the pc team distributes, simply do the following: 1. 16-bit Real Mode Overlaid version Use the 16-bit Microsoft Visual C++ V1.52c compiler Paths below are relative to the top of your unpacked NetHack source distribution: md \games\nethack cd sys\msdos setup MSC cd ..\..\src nmake install 2. 32-bit Protected Mode DPMI version Use the 32-bit djgpp compiler V2.03 or greater Paths below are relative to the top of your unpacked NetHack source distribution: md \games\nethackd cd sys\msdos setup GCC cd ..\..\src make install Appendix B - Building other binaries Make sure that USE_DLB and TILESUPPORT (if using Microsoft C or Borland C) are both set to be turned on in the appropriate makefile. For an overlaid binary built with Microsoft C 7.00, make no changes to any of the defines and use the Makefile.MSC as distributed. For an overlaid binary built with Borland C++ 3.1, make no changes to any of the defines and use the makefile Makefile.BC as distributed. For the 32-bit binary built with DJGPP (playable on a 386 or better machine only), make no changes to any of the defines and use the Makefile.GCC as distributed. Make sure the following files have been converted from the unix style "^J" end of line, to the msdos style "^M^J": license, help, hh, termcap, history, cmdhelp wizhelp and defaults.nh. Uudecode nhico.uu nhpif.uu. Place all the files in a clean directory and test. Appendix C - Microsoft C Compilers Officially, support is no longer provided for MSC versions prior to 7.0. For versions of MSC 7.0 and greater (including Visual C++ ), a single Makefile is used, and it is MS NMAKE specific. It is executed from the src directory. It makes several passes over the files in order to produce overlays. MSC Version 7.0 works with or without the August 1992 patch. MSVC Professional 1.52c works as distributed. In some rare cases you may encounter a problem with the compiler where it stops part way through the build with a memory error. Things proceed normally after starting 'nmake install' once again. The problem, although annoying if it happens, does not affect the code generation or the final executable. MSC Version 7.0 and MSVC take advantage of the CL environment variables to set the compiler flags, as they exceed the MSDOS limitation of 128 characters on the command line. Please read the Makefile carefully and select those options that go with the compiler. The Makefile will set the CL environment variable within the context of the build, so you do not have to do it elsewhere. Microsoft C version 7.0 and Microsoft Visual C++ Professional versions up to 1.52c. Microsoft's MOVE overlay facility is suitable for building overlaid versions of NetHack. A single Makefile is used, and it is NMAKE specific. It is executed from the src directory. It is stored in the distribution as sys/msdos/Makefile.MSC. It is moved to the src directory (with the new name 'Makefile') by setup.bat when invoked like so: "setup MSC". The Microsoft Visual C++ Professional compiler utilizes the same Makefiles and instructions for compiling as Microsoft C version 7.0. Appendix D - DJGPP Compiler (gcc ported to msdos) If you have a 386 or better machine, you are in luck. You can compile NetHack without spending money on a compiler. DJGPP is available free from many archive sites. At the time of this release in August 2000, the URL http://www.delorie.com/djgpp/zip-picker.html/ had information on how to obtain djgpp and what pieces to get. Setting up DJGPP is more than adequately explained in the documentation that comes with it. Be sure to pick up the yacc and flex built with DJGPP if you intend to do any modification of the special levels or dungeon compilers. They should be available at the same place you got djgpp. The latest version of djgpp, V2.03 will produce a binary that will run under Microsoft Windows, or any other DPMI provider. djgpp also comes with a DPMI provider called CWSDPMI. Place CWSDPMI.EXE in your path and it will be used in the absence of any other DPMI provider. If you want to use the built-in DJGPP screen routines, uncomment SCREEN_DJGPPFAST in pcconf.h (the default for djgpp). Note that some of these routines are broken under early versions of the compiler, so we pick and choose the ones that work. See video.c for details. Appendix E - Borland C++ Compiler Officially, support is not provided for any version of Borland C++ or Turbo C++ other than Borland C++ 3.1. It does not work with Borland C++ 4.5 yet, and versions 4.0 and 5.0 have not been tested. We believe that compiling with the version of Turbo C++ equivalent to Borland C++ 3.1 should work. For Borland C++ 3.1, a single Makefile is used, and it is specific to Borland's MAKE version 3.6. It is executed from the src directory and makes several passes over the files in order to produce overlays. Borland C++ 3.1 Borland's VROOMM overlay facility is suitable for building overlaid versions of NetHack. A single Makefile is used, and it is MAKE 3.6 specific. It is executed from the src directory. It is stored in the distribution as sys/msdos/Makefile.BC. It is moved to the src directory (with the new name 'Makefile') by setup.bat. Remember to type 'make -N install' rather than just 'make install'. The -N option is required. Make sure to set the directories BCTOP and related directories in Makefile. to the correct directory. There are problems in running the newest versions of flex and bison from the all-purpose Makefile so you should leave DO_YACC and DO_LEX as is. Turbo C++ As explained, this has not been tested. However, if you want to test if Turbo C++ works, provided that the copy of Borland's MAKE you have is version 3.6 (you can check this by running MAKE in an empty directory), you are welcome to try. If Turbo C++ does not define __BORLANDC__, just put the line: #define __BORLANDC__ __TURBOC__ at the very very top of hack.h. If it works, be sure to tell us. Appendix F - Microsoft C Compiler Warnings If you are using MSC for your compile with any of the /W levels set, you can expect warnings. The list below are those warnings that we are aware of and our recommendation for dealing with them. You can use the warning disable pragma to ignore them if you wish. (NOTE: this is not a complete list of all warnings you might receive, only those for which we feel we can safely provide guidance on.) C4131 (function:uses old-style declarator) You should ignore this warning. In order to make the source code as portable as possible, only old-style declarators are used so that as many compilers as possible can use the same code. C4706 (Assignment within conditional expression) This is a perfectly valid construction. These warnings have not produced any problems. C4761 (Integral size mismatch in argument; conversion supplied) These should be no problem. Prototyping compilers will do the con- version, and non-prototyping compilers will go through int anyway. Appendix G - Additional Notes 1) Save files and bones files from previous versions of NetHack will not work with this NetHack. Don't bother trying to keep them. Record (score) files from before 3.0 patchlevel 7 will almost work, but you need to make one change manually to them: At the end of each line is a word or phrase specifying what killed the player. Change the string to start with the words "killed by", "killed by a", or "killed by an" (whichever is appropriate). If the death was petrification, it should read "petrified by" instead of "killed by". Don't change "starvation", "quit", "escaped", or "ascended". 2) To install an update of NetHack after changing something, type 'nmake' for Microsoft C, 'make -N' for Borland C++, and 'make' for DJGPP from the src directory. If you add, delete, or reorder monsters or objects, or you change the format of saved level files, delete any save and bones files. (Trying to use such files sometimes produces amusing confusions on the game's part, but usually crashes.) If you made changes to any of the level compiler software, you may have to delete dgn_flex.c, dgn_yacc.c, lev_flex.c, and lev_yacc.c from the util directory to ensure that they are remade. This is not officially supported for Borland C++. 3) During linking the Microsoft Overlay Linker will need temporary storage space. Make sure you have about a meg of free disk wherever you have defined your temporary storage. Appendix H - Contacting the Development Team If you discover a bug and wish to report it please send mail to: nethack-bugs@nethack.org If you have comments or suggestions, feel free to drop us a line c/o DevTeam@nethack.org