1 SCCS Id: @(#)Install.dos 3.3 2000/08/02 2 3 Copyright (c) NetHack PC Development Team 1990-2000. 4 NetHack may be freely redistributed. See license for details. 5 ============================================================== 6 Instructions for compiling and installing 7 NetHack 3.3 on a DOS system 8 ====================================================== 9 (or, How to make PC NetHack 3.3) 10 Last revision: August 2, 2000 11 12Credit for a runnable full PC NetHack 3.3 goes to the PC Development team 13of Paul Winner, Kevin Smolkowski, Michael Allison, Yitzhak Sapir, Bill Dyer, 14Timo Hakulinen, Yamamoto Keizo, Mike Threepoint, Mike Stephenson, 15Stephen White, Ken Washikita and Janet Walz. The present port is based 16on the previous effort of Pierre Martineau, Stephen Spackman, Steve Creps, Mike 17Threepoint, Mike Stephenson, Norm Meluch and Don Kneller. 18 19CONTENTS: 20 21 I. Dispelling the Myths 22 II. Compiling on a DOS machine 23 Appendix A - Building the "official binaries" 24 Appendix B - Building other binaries 25 Appendix C - Microsoft C Compiler notes 26 Appendix D - DJGPP Compiler (gcc ported to msdos) notes 27 Appendix E - Borland C++ Compiler notes 28 Appendix F - Microsoft C Compiler Warnings 29 Appendix G - Additional Notes 30 Appendix H - Contacting Us 31 32I. Dispelling the Myths: 33 34 Compiling NetHack is not as easy as it sounds, nor as hard as it looks, 35 however it will behoove you to read this entire file through before 36 beginning the task. 37 38 We have provided the proper makefiles for building NetHack using the 39 following compilers: 40 Microsoft C 7.0 and Microsoft Visual C++ Professional (MSVC) 1.52c 41 djgpp V2.0 or later 42 Borland C V3.1 43 44 For specific details concerning each compiler, please see the 45 corresponding appendix. 46 47 The makefile named Makefile.MSC is for use with Microsoft's NMAKE, 48 the make utility that ships with the Microsoft C Compiler version 7.0 49 and above, including the 16-bit Microsoft Visual C++ Professional. 50 51 The makefile named Makefile.GCC is for use with GNU Make that 52 accompanies djgpp. 53 54 The makefile named Makefile.BC is for use with Borland's make that 55 accompanies Borland C 3.1. Other versions of Borland's make may or 56 may not work, but version 3.7 (of MAKE) is known to not work. 57 58 If you want to build a copy of NetHack that is identical to the 59 "official binaries", please see appendix A. 60 61 You may find it useful to obtain copies of lex (flex) and yacc (bison 62 or byacc). While not strictly necessary to compile nethack, they are 63 required should you desire to make any changes to the level and dungeon 64 compilers. Flex and Bison are included with the DJGPP distribution and 65 are also available on many archive sites. 66 67II. To compile your copy of NetHack on a DOS machine: 68 (or "just follow these few 'simple' steps outlined below.") 69 701. It almost goes without saying that you should make sure that your tools 71 are set up and running correctly. 72 732. Make sure all the NetHack files are in the appropriate directory 74 structure. You should have a main directory with subdirectories 75 dat, doc, include, src, sys\share, sys\msdos, util, win\tty and 76 win\share. Other subdirectories may also be included in your 77 distribution, but they are not necessary for use with DOS. You can 78 delete them to save space. If you are using MSC7 or MSVC, the makefile 79 will create an additional working directory src\o. 80 81 Required Source Directories for DOS NetHack: 82 83 (top) 84 | 85 ------------------------------------------------- 86 | | | | | | | 87 util dat doc include src sys win 88 | | 89 ------ ----- 90 | | | | 91 share msdos tty share 92 93 Check the file "Files" in your top level directory for an exact 94 listing of what files are in which directory. In order for the 95 Makefiles to work, all the source files must be in the proper 96 locations. 97 98 If you downloaded or ftp'd the sources from a UNIX system, the lines 99 will probably end in UNIX-style newlines, instead of the carriage 100 return and line feed pairs used by DOS. Some programs have trouble 101 with them, so you may need to convert them (with a utility like 102 Rahul Dhesi's "flip"). 103 1043. A few files in the NetHack distribution are uuencoded because 105 they contain non-ascii characters, or binary information. To use 106 them they must first be decoded using a uudecode utility (available 107 from your local archive site). After reading the descriptions 108 of these files below, uudecode the ones that you will need in order 109 to build NetHack with the options that you have decided you want. 110 111 The uuencoded files that are relevant to NetHack on a DOS machine 112 include: 113 114 nhico.uu Optional. This uudecodes into a MS-Windows compatible 115 ICON. You only need to uudecode this if you plan on 116 launching NetHack from MS-Windows, and want a unique 117 Nethack ICON to use. 118 119 nhpif.uu Optional. This uudecodes into a MS-Windows compatible 120 PIF file which may be used to launch NetHack from the 121 MS-Windows program manager. You only need to uudecode 122 this if you plan on launching NetHack from within 123 MS-Windows. 124 125 termcap.uu Optional. Termcap support is no longer required for 126 building NetHack, though you can if you want to. 127 The file termcap.uu is the fixed version 128 of the Fred Fish termcap library. If you have modified 129 pcconf.h to define TERMLIB as well as commented out 130 the default #define NO_TERMS, then you will need to 131 run a uudecode utility on termcap.uu to generate the 132 file termcap.zip. termcap.zip contains several files 133 of termcap routines. Using them with NetHack involves 134 very little knowledge of the UNIX concept of a termcap 135 database; mostly you need to know enough to set a TERM 136 environment variable. You can unzip termcap.zip in the 137 sys/share directory, but if you are going to use it, it 138 is probably better to unzip a copy in a special directory 139 and copy the library files to where your linker can find 140 them. NetHack versions since 3.1.2 no longer enable 141 the use of termcap in the default configuration, or 142 with the official binaries. 143 144 Makefiles are included should you want to build your own 145 termcap library file. Makemsc.lib works with Microsoft 146 C (MSC and MSVC) and generates termcap.lib, Makegcc.lib 147 works with DJGPP and generates libtermc.a. 148 1494. Go to the sys/msdos directory and ensure that the file setup.bat 150 has MSDOS style end-of-line characters rather than UNIX style 151 end-of-line characters. You can do that using a utility like 152 Rahul Dhesi's "flip", or by invoking the MSDOS edit utility on 153 setup.bat and saving the file without making any changes. Failure to 154 do this will prevent the bat file from executing completely, yet no 155 warning message will be given. 156 157 Run the setup.bat batch file with one of the following as the argument: 158 159 MSC For Microsoft C and its NMAKE. 160 161 GCC For djgpp and GNU MAKE. 162 163 BC For Borland C++ 3.1, and Borland's MAKE. 164 165 The appropriate and necessary Makefile movements will be accomplished 166 for you, as well as verifying a few files and fixing a few file names 167 on FAT systems with long file name support. 168 1695. Now go to the include subdirectory to check a couple of the header 170 files there. Things *should* work as they are, but since you have 171 probably set up your system in some sort of custom configuration 172 it doesn't hurt to check out the following: 173 174 First check config.h according to the comments to match your system and 175 desired set of features. Mostly you need to check the WIZARD option, 176 and check TERMLIB and COMPRESS. Also be sure to leave DLB support 177 commented out in config.h. MSDOS has support for DLB, but it must be 178 done through the Makefile, rather than config.h, to ensure that the 179 necessary packaging steps are done. 180 181 We've managed to enable all the special features. You may include all 182 or as few of them as you wish. To conserve disk space, you may wish 183 to disable LOGFILE and NEWS. 184 185 Also check pcconf.h, which should not need much editing (if you are 186 including random.c, and if you do not require termcap for screen 187 management). If you are not including random.c you will need to 188 comment out RANDOM. 189 190 There are several options available for screen management with this 191 release of PC NetHack. The features #define TERMLIB, #define 192 ANSI_DEFAULT, and #define NO_TERMS in pcconf.h control the various 193 options. 194 195 The NO_TERMS feature (the default) has the advantage of not needing a 196 DEVICE=ANSI.SYS statement in config.sys. The supplied sources and 197 header files are distributed with support for NO_TERMS enabled. 198 NO_TERMS will not work with TERMLIB, nor with ANSI_DEFAULT defined. 199 The NO_TERMS feature uses internal routines for screen management, and 200 may be an ideal choice if your play machine is industry standard (has 201 an IBM compatible BIOS). 202 203 Should you choose to leave NO_TERMS defined, define only one of the two 204 screen access methods. If compiling for Microsoft compilers, use 205 SCREEN_BIOS; if using DJGPP, you can choose between SCREEN_BIOS 206 and SCREEN_DJGPPFAST. Never, never, ever choose both. Bad things 207 will happen. We are not kidding. 208 209 If you leave the #define TERMLIB commented in pcconf.h to disable use 210 of termcap routines, then your screen management must rely on either 211 the NO_TERMS feature described above, or the ANSI_DEFAULT feature. 212 Either of these will make your job a bit easier than if you choose to 213 use TERMLIB. If you elect to include TERMLIB support, you may compile 214 with both TERMLIB and ANSI_DEFAULT, and simply not set your TERM variable 215 if you do not wish to use the termcap file settings. You will need 216 to uudecode the termcap library in sys\share if you are using the TERMLIB 217 feature. 218 2196. If you want to change the high score list behavior, examine the top of 220 topten.c, in the src directory. You may want to change the definitions of 221 PERSMAX, POINTSMIN, and ENTRYMAX. We set POINTSMIN to 51 and ENTRYMAX to 222 50 to keep the size of the score list down. 223 2247. Go to the src directory and edit the top of your Makefile. Be sure the 225 directory you want the game installed in (GAMEDIR) actually exists. 226 227 If you elected to use termcap (TERMLIB defined), then uncomment the 228 TERMLIB macro in your Makefile that points to the location of the 229 library. 230 231 That is, TERMLIB = 232 should be TERMLIB = (SSYS)\termlib.lib 233 234 If you are recompiling after patching your sources, or if you got your 235 files from somewhere other than the official distribution, "touch 236 makedefs.c" to ensure that certain files (onames.h and pm.h) are remade, 237 lest potentially troublesome timestamps fool your make utility. 238 239 a) For Borland C++ 3.1, 240 241 Choose an overlay schema by setting SCHEMA to 1 or 2. If you change 242 the overlay schema, you will need to recompile all the object modules 243 from scratch since the overlay schema is information is used during 244 compile time for Borland C++, unlike Microsoft C which does it during 245 link time. 246 247 b) For Microsoft C 7.0 or greater, and Microsoft Visual C++ 248 249 The only overlay schema available is Schema3 so you don't have to 250 choose one. The Makefile is set up for it already. The overlay 251 description file src\Schema3.def is created from sys\msdos\Schema3.MSC 252 by setup.bat. 253 254 If you elected to add graphical tile support, set TILESUPPORT to Y. 255 256 Set USE_DLB to Y if you wish to place NetHack's many runtime files into 257 a special archive that NetHack can utilize. This is highly recommended! 258 In fact, we haven't tested NetHack without it for several releases now. 259 2608. Now that everything is set up, what you do next depends on which 261 compiler and version you are using. You will need to execute either 262 step 8a, or step 8b, or step 8c, but only one of them. 263 264 a) For Microsoft C 7.0 or greater, and Microsoft Visual C++ 265 266 Go to the src directory, and "nmake install". 267 268 b) For djgpp 269 270 Go to the src directory, and using the GNU Make utility, 271 "make install". 272 273 c) For Borland C V3.1 274 275 Go to the src directory, and using the Borland Make utility, 276 "make -N install". 277 278 279 Depending on your particular machine and compiler, you can either 280 grab a cup of coffee or go home for the day. Your computer will be 281 occupied for quite some time. If all goes well, you will get an 282 NetHack executable. 283 2849. If you chose DLB support (recommended), make sure that the file nhdat 285 got copied into the game directory. 286 287 If you didn't choose DLB support, make sure the support files -- 288 data, rumors, cmdhelp, opthelp, help, hh,history, guidebook.txt 289 license, and all the *.lev files -- were copied to the game directory. 290 If not, move them there from the dat directory yourself. rumors can 291 be created manually be entering "makedefs -r", data by entering 292 "makedefs -d". 293 294 Make sure the files NetHack1.tib and NetHacko.tib made it to your game 295 directory. Copy them from src to the game directory yourself if 296 necessary. 297 298 Make sure the files defaults.nh and termcap made it to your game 299 directory. If not, go to sys\share and copy NetHack.cnf to 300 your game directory as defaults.nh. The name in previous versions was 301 nethack.cnf, but the CNF extension conflicted with the MS Windows 302 speed-dialer, making the file hidden on many machines. 303 304 If you changed your build settings to include TERMCAP support, copy 305 termcap to your game directory. 306 307 Also, make sure the file msdoshlp.txt made it to your game directory. 308 If it didn't, move it from sys\msdos to your game directory 309 yourself. 310 31110. In your game directory, review the settings in defaults.nh and adjust 312 them according to your style of play. Some new options that you might 313 be interested in are "menustyle" (for tailoring new object selection 314 interface), and "video" (for turning on graphical tiles). 315 316 On Borland C++, the soundcard:autodetect option enables pc speaker 317 sound in NetHack if you compiled with PCMUSIC set in pcconf.h. It 318 is rumored that this also works with djgpp, but the PCMUSIC setting 319 in pcconf.h must be uncommented manually. 320 32111. Play NetHack. If it works, you're done! 322 323Appendix A - Building the "official binaries" 324 325 If you wish to build a copy of NetHack identical to the ones that 326 the pc team distributes, simply do the following: 327 3281. 16-bit Real Mode Overlaid version 329 Use the 16-bit Microsoft Visual C++ V1.52c compiler 330 331 Paths below are relative to the top of your unpacked 332 NetHack source distribution: 333 334 md \games\nethack 335 cd sys\msdos 336 setup MSC 337 cd ..\..\src 338 nmake install 339 3402. 32-bit Protected Mode DPMI version 341 Use the 32-bit djgpp compiler V2.03 or greater 342 343 Paths below are relative to the top of your unpacked 344 NetHack source distribution: 345 346 md \games\nethackd 347 cd sys\msdos 348 setup GCC 349 cd ..\..\src 350 make install 351 352 353Appendix B - Building other binaries 354 355 Make sure that USE_DLB and TILESUPPORT (if using Microsoft C or Borland 356 C) are both set to be turned on in the appropriate makefile. 357 358 For an overlaid binary built with Microsoft C 7.00, make no changes to 359 any of the defines and use the Makefile.MSC as distributed. 360 361 For an overlaid binary built with Borland C++ 3.1, make no changes to 362 any of the defines and use the makefile Makefile.BC as distributed. 363 364 For the 32-bit binary built with DJGPP (playable on a 386 or 365 better machine only), make no changes to any of the defines and use 366 the Makefile.GCC as distributed. 367 368 Make sure the following files have been converted from the 369 unix style "^J" end of line, to the msdos style "^M^J": 370 license, help, hh, termcap, history, cmdhelp wizhelp and 371 defaults.nh. 372 373 Uudecode nhico.uu nhpif.uu. 374 375 Place all the files in a clean directory and test. 376 377Appendix C - Microsoft C Compilers 378 379 Officially, support is no longer provided for MSC versions prior to 380 7.0. For versions of MSC 7.0 and greater (including Visual C++ ), 381 a single Makefile is used, and it is MS NMAKE specific. It is executed 382 from the src directory. It makes several passes over the files in order 383 to produce overlays. 384 385 MSC Version 7.0 works with or without the August 1992 patch. 386 387 MSVC Professional 1.52c works as distributed. In some rare cases 388 you may encounter a problem with the compiler where it stops 389 part way through the build with a memory error. Things proceed 390 normally after starting 'nmake install' once again. The problem, 391 although annoying if it happens, does not affect the code generation 392 or the final executable. 393 394 MSC Version 7.0 and MSVC take advantage of the CL environment variables 395 to set the compiler flags, as they exceed the MSDOS limitation of 128 396 characters on the command line. Please read the Makefile carefully 397 and select those options that go with the compiler. The Makefile 398 will set the CL environment variable within the context of the build, 399 so you do not have to do it elsewhere. 400 401 402 Microsoft C version 7.0 and 403 Microsoft Visual C++ Professional versions up to 1.52c. 404 405 Microsoft's MOVE overlay facility is suitable for building overlaid 406 versions of NetHack. 407 408 A single Makefile is used, and it is NMAKE specific. It is executed 409 from the src directory. It is stored in the distribution as 410 sys/msdos/Makefile.MSC. It is moved to the src directory (with the 411 new name 'Makefile') by setup.bat when invoked like so: "setup MSC". 412 413 The Microsoft Visual C++ Professional compiler utilizes the same 414 Makefiles and instructions for compiling as Microsoft C version 7.0. 415 416Appendix D - DJGPP Compiler (gcc ported to msdos) 417 418 If you have a 386 or better machine, you are in luck. You can compile 419 NetHack without spending money on a compiler. DJGPP is available free 420 from many archive sites. 421 At the time of this release in August 2000, the URL 422 http://www.delorie.com/djgpp/zip-picker.html/ 423 had information on how to obtain djgpp and what pieces to get. 424 425 Setting up DJGPP is more than adequately explained in the documentation 426 that comes with it. Be sure to pick up the yacc and flex built with 427 DJGPP if you intend to do any modification of the special levels or 428 dungeon compilers. They should be available at the same place you got 429 djgpp. 430 431 The latest version of djgpp, V2.03 will produce a binary that will run 432 under Microsoft Windows, or any other DPMI provider. djgpp also comes 433 with a DPMI provider called CWSDPMI. Place CWSDPMI.EXE in your path 434 and it will be used in the absence of any other DPMI provider. 435 436 If you want to use the built-in DJGPP screen routines, uncomment 437 SCREEN_DJGPPFAST in pcconf.h (the default for djgpp). 438 Note that some of these routines are broken under early versions 439 of the compiler, so we pick and choose the ones that work. 440 See video.c for details. 441 442Appendix E - Borland C++ Compiler 443 444 Officially, support is not provided for any version of Borland C++ or 445 Turbo C++ other than Borland C++ 3.1. It does not work with Borland 446 C++ 4.5 yet, and versions 4.0 and 5.0 have not been tested. We believe 447 that compiling with the version of Turbo C++ equivalent to Borland C++ 448 3.1 should work. For Borland C++ 3.1, a single Makefile is used, and it 449 is specific to Borland's MAKE version 3.6. It is executed from the src 450 directory and makes several passes over the files in order to produce 451 overlays. 452 453 Borland C++ 3.1 454 455 Borland's VROOMM overlay facility is suitable for building overlaid 456 versions of NetHack. 457 458 A single Makefile is used, and it is MAKE 3.6 specific. It is executed 459 from the src directory. It is stored in the distribution as 460 sys/msdos/Makefile.BC. It is moved to the src directory (with the 461 new name 'Makefile') by setup.bat. 462 463 Remember to type 'make -N install' rather than just 'make install'. The 464 -N option is required. 465 466 Make sure to set the directories BCTOP and related directories in 467 Makefile. to the correct directory. There are problems in running the 468 newest versions of flex and bison from the all-purpose Makefile so you 469 should leave DO_YACC and DO_LEX as is. 470 471 Turbo C++ 472 473 As explained, this has not been tested. However, if you want to test if 474 Turbo C++ works, provided that the copy of Borland's MAKE you have is 475 version 3.6 (you can check this by running MAKE in an empty directory), 476 you are welcome to try. If Turbo C++ does not define __BORLANDC__, 477 just put the line: 478 #define __BORLANDC__ __TURBOC__ 479 at the very very top of hack.h. If it works, be sure to tell us. 480 481Appendix F - Microsoft C Compiler Warnings 482 483 If you are using MSC for your compile with any of the /W levels set, 484 you can expect warnings. The list below are those warnings that we 485 are aware of and our recommendation for dealing with them. You can 486 use the warning disable pragma to ignore them if you wish. (NOTE: 487 this is not a complete list of all warnings you might receive, only 488 those for which we feel we can safely provide guidance on.) 489 490C4131 (function:uses old-style declarator) 491 You should ignore this warning. In order to make the source code as 492 portable as possible, only old-style declarators are used so that as 493 many compilers as possible can use the same code. 494C4706 (Assignment within conditional expression) 495 This is a perfectly valid construction. These warnings have not 496 produced any problems. 497C4761 (Integral size mismatch in argument; conversion supplied) 498 These should be no problem. Prototyping compilers will do the con- 499 version, and non-prototyping compilers will go through int anyway. 500 501Appendix G - Additional Notes 502 5031) Save files and bones files from previous versions of NetHack will not 504 work with this NetHack. Don't bother trying to keep them. Record 505 (score) files from before 3.0 patchlevel 7 will almost work, but you need 506 to make one change manually to them: At the end of each line is a word or 507 phrase specifying what killed the player. Change the string to start with 508 the words "killed by", "killed by a", or "killed by an" (whichever is 509 appropriate). If the death was petrification, it should read "petrified 510 by" instead of "killed by". Don't change "starvation", "quit", "escaped", 511 or "ascended". 512 5132) To install an update of NetHack after changing something, type 'nmake' 514 for Microsoft C, 'make -N' for Borland C++, and 'make' for DJGPP 515 from the src directory. If you add, delete, or reorder monsters or 516 objects, or you change the format of saved level files, delete any save 517 and bones files. (Trying to use such files sometimes produces amusing 518 confusions on the game's part, but usually crashes.) 519 520 If you made changes to any of the level compiler software, you may have 521 to delete dgn_flex.c, dgn_yacc.c, lev_flex.c, and lev_yacc.c from the 522 util directory to ensure that they are remade. This is not officially 523 supported for Borland C++. 524 5253) During linking the Microsoft Overlay Linker will need temporary storage 526 space. Make sure you have about a meg of free disk wherever you have 527 defined your temporary storage. 528 529Appendix H - Contacting the Development Team 530 531 If you discover a bug and wish to report it please send mail to: 532 nethack-bugs@nethack.org 533 534 If you have comments or suggestions, feel free to drop us a line c/o 535 DevTeam@nethack.org 536 537 538