sys/winnt/Install.nt

   1          Copyright (c) NetHack Development Team 1990-2002
   2          NetHack may be freely redistributed.  See license for details.
   3          ==============================================================
   4                  Instructions for compiling and installing
   5              NetHack 3.4 on a Windows 9x, NT, 2000, or XP system
   6          ==============================================================
   7                  Last revision: $Date: 2003/10/14 01:31:25 $
   8
   9 Credit for the porting of NetHack to the Win32 Console Subsystem goes to
  10 the NT Porting Team started by Michael Allison.
  11
  12 Credit for the Win32 Graphical version of NetHack (aka "NetHack for
  13 Windows" or NetHackW) goes to Alex Kompel who initially developed and
  14 contributed the port.
  15
  16 The PC Windows porting team consisting of Michael Allison, David Cohrs,
  17 Alex Kompel, Dion Nicolaas, Yitzhak Sapir, and Janet Walz maintained the
  18 tty and graphical win32 versions of NetHack 3.4.3.
  19
  20 You can build either the TTY version of NetHack or the Windows Graphical
  21 version.  In either case you can use one of the following build
  22 environments:
  23
  24   o A copy of Microsoft Visual C V6.0 SP3 or later.  Things may work with
  25     an earlier version of the compiler, but the current code has not
  26     been tested with an earlier version.
  27
  28         OR
  29
  30   o A copy of Borland C 5.5.1 command line tools.  Borland has made a
  31     version of its command line tools available for download after
  32     registration at:
  33         http://www.borland.com/bcppbuilder/freecompiler/
  34
  35     OR
  36
  37   o A copy of MinGW 2.0. MinGW is a collection of header files and import
  38     libraries with which native Windows32 programs can be made; the
  39     MinGW 2.0 distribution contains the GNU Compiler Collection.
  40     You can download MinGW at
  41         http://www.mingw.org/
  42     Earlier versions of MinGW will not allow you to build the Windows
  43     Graphical version.
  44
  45 In addition to the makefiles that allow you to build NetHack from the
  46 command line, there is also a set of project files and a workspace file
  47 that allow you to build the Windows Graphical version from Microsoft
  48 Visual C's IDE (Integrated Development Environment.)
  49
  50
  51 FIRST STEP
  52
  53 The first step in building either version of NetHack is to execute
  54 sys\winnt\nhsetup.bat.
  55
  56 From the command prompt:
  57         cd sys\winnt
  58         nhsetup
  59
  60 From a Windows explorer window:
  61         double-click on nhsetup.bat
  62
  63 A "binary" directory will be created off the top of the NetHack source
  64 tree to house the completed build.
  65
  66 A build subdirectory will also be created off the top of the NetHack
  67 source tree, and many files appropriate for a graphical build will be
  68 moved there.
  69
  70 If you wish to build from the command line, proceed to "BUILDING FROM
  71 THE COMMAND LINE."
  72 If you wish to build using Visual C's IDE, proceed now to "BUILDING
  73 USING VISUAL C'S IDE."
  74
  75
  76 BUILDING FROM THE COMMAND LINE
  77
  78 You can built two different versions of NetHack for Win32 from the
  79 command line:
  80     A tty port utilizing the Win32 Console I/O subsystem, Console
  81         NetHack;
  82     A Win32 native port built on the Windows API, Graphical NetHack or
  83         NetHackW.
  84
  85 The executable for Console NetHack will be named NetHack.exe. The
  86 executable for Graphical NetHack will be named NetHackW.exe. You can opt
  87 to build both; they will be able to use the same datafiles, save files
  88 and bones files.
  89
  90 I. Dispelling the Myths:
  91
  92     Compiling NetHack for Win32 is not as easy as it sounds, nor as hard
  93     as it looks, however it will behoove you to read this entire section
  94     through before beginning the task.
  95
  96     We have provided a Makefile for each of the following compilers:
  97
  98         o Microsoft Visual C++ V6.0 SP3 or greater
  99         o Borland C 5.5.1
 100         o MinGW 2.0 (with GCC 3.2)
 101
 102     The Microsoft Visual C Makefile was created for use with MS NMAKE
 103     which is provided with the Microsoft compiler. The supplied Makefile
 104     may work with earlier versions of the Microsoft 32-bit compiler, but
 105     that has not been tested.
 106
 107     The Borland C Makefile was created for use with Borland MAKE which
 108     is provided with the Borland compiler.
 109
 110     The GCC Makefile was created for use with GNU Make version 3.79.1,
 111     which comes with the MinGW package.
 112
 113     You may find it useful to obtain copies of lex (flex) and yacc
 114     (bison, or byacc).  While not strictly necessary to compile nethack,
 115     they are required should you desire to make any changes to the level
 116     and dungeon compilers.
 117
 118 II. To compile your copy of NetHack on a Windows NT/2000/XP machine:
 119
 120 Setting Up
 121
 122 1.  It almost goes without saying that you should make sure that your
 123     tools are set up and running correctly.  That includes ensuring that
 124     all the necessary environment variables for the compiler environment
 125     are set correctly.  (Examples: For the Microsoft compiler by
 126     executing vcvars32.bat, which is probably in the bin directory of
 127     your compilers directory tree. For the Borland Makefile, you can
 128     simply invoke the Make utility from the Makefile's directory (For
 129     the standard Borland compiler installation you can just use the
 130     explicit path "c:\borland\bcc55\bin\make /f Makefile.bcc".  For the
 131     GCC Makefile, add <mingw>\bin to your path, where <mingw> is your
 132     MinGW root directory.)
 133
 134 2.  Make sure all the NetHack files are in the appropriate directory
 135     structure.  You should have a main directory with subdirectories
 136     dat, doc, include, src, sys\share, sys\winnt, util, and binary (The
 137     "binary" directory was created by nhsetup.bat earlier if you
 138     followed the steps appropriately).
 139
 140     For Console NetHack you need win\tty in addition to these; for
 141     Graphical NetHack you need win\win32 in addition to these.
 142
 143     Other subdirectories may also be included in your distribution, but
 144     they are not necessary for building the TTY version for the Win32
 145     console subsystem.  You can delete them to save space.
 146
 147     Required Directories for a Win32 Console NetHack:
 148
 149                             top
 150                              |
 151         ----------------------------------------------------/ /-----
 152         |       |     |        |       |     |          |        |
 153        util    dat   doc    include   src   sys        win     binary
 154                                              |          |
 155                                           ------      -----
 156                                           |    |      |
 157                                        share  winnt  tty
 158
 159
 160     Required Directories for a Win32 Graphical NetHack:
 161
 162                             top
 163                              |
 164         ----------------------------------------------------/ /-----
 165         |       |     |        |       |     |          |        |
 166        util    dat   doc    include   src   sys        win     binary
 167                                              |          |
 168                                           ------      -----
 169                                           |    |          |
 170                                        share  winnt      win32
 171
 172     Check the file "Files" in your top level directory for an exact
 173     listing of what file is in which directory.  In order for the
 174     Makefiles to work, all the source files must be in the proper
 175     locations.
 176
 177     If you downloaded or ftp'd the sources from a UNIX system, the lines
 178     will probably end in UNIX-style newlines, instead of the carriage
 179     return and line feed pairs used by Windows.  Some programs have
 180     trouble with them, so you may need to convert them. The compiler
 181     should not have any problems with them however.
 182
 183 3.  Now go to the include subdirectory to check a couple of the header
 184     files there.  Things *should* work as they are, but since you have
 185     probably set up your system in some sort of custom configuration it
 186     doesn't hurt to check out the following:
 187
 188     First check config.h according to the comments to match your system
 189     and desired set of features.  Mostly you need to check section 4 and
 190     5.
 191
 192     You may include all or as few of the special game features as you
 193     wish (they are located last in the file).
 194
 195 4.  Edit your Makefile.
 196
 197     For building Console NetHack, ensure that GRAPHICAL is set to "N",
 198     or commented out. For building Graphical NetHack, set GRAPHICAL to
 199     "Y".
 200
 201     Optional step:
 202         If you elected not to use the high-quality BSD random number
 203         routines by commenting out RANDOM in ntconf.h, comment out (or
 204         set equal to nothing) the RANDOM macro in your Makefile.
 205
 206     If you are recompiling after patching your sources, or if you got
 207     your files from somewhere other than the official distribution,
 208     "touch makedefs.c" to ensure that certain files (onames.h and pm.h)
 209     are remade, lest potentially troublesome timestamps fool your make
 210     (or nmake) utility.
 211
 212 Compiling
 213
 214 5.  Now that everything is set up, change your current directory to src.
 215
 216     For Microsoft compiler:
 217         nmake install
 218
 219     For Borland compiler:
 220         make /f Makefile.bcc install
 221
 222     For GCC:
 223         mingw32-make -f Makefile.gcc install
 224
 225     If you get any errors along the way then something has not been set
 226     up correctly. The time it takes to compile depends on your
 227     particular machine of course, but you should be able to go for lunch
 228     and return to find everything finished.  The less memory, and slower
 229     your machine, the longer the lunch you may take. :-)
 230
 231     In any case, it is likely that the command prompt window where you
 232     are doing the compiling will be occupied for a while.  If all goes
 233     well, you will get an NetHack executable.
 234
 235 Notes:
 236
 237 1.  To install an update of NetHack after changing something, change
 238     your current directory to src and issue the appropriate command for
 239     your compiler:
 240
 241     For Microsoft compiler:
 242         nmake
 243
 244     For Borland compiler:
 245         make /f Makefile.bcc
 246
 247     For GCC:
 248         mingw32-make -f Makefile.gcc
 249
 250     If you add, delete, or reorder monsters or objects, or you change
 251     the format of saved level files, delete any save and bones files.
 252     (Trying to use such files sometimes produces amusing confusions on
 253     the game's part, but usually crashes.)
 254
 255     If you made changes to any of the level compiler software, you may
 256     have to delete dgn_flex.c, dgn_yacc.c, lev_flex.c, and lev_yacc.c
 257     from the util directory to ensure that they are remade.
 258
 259 2.  The executable produced by the TTY build is a 32-bit, flat-address
 260     space, non-overlayed .exe file, which should run on any true Win32
 261     environment with console I/O support.
 262
 263     The executable built by the graphical built is a 32-bit,
 264     flat-address space, non-overlayed .exe file, which should run on any
 265     true Win32 graphical environment.
 266
 267     To run NetHack, proceed to RUNNING NETHACK.
 268
 269
 270 BUILDING USING VISUAL C'S IDE
 271
 272 Only the Win32 native port built on the Windows API, or Graphical
 273 NetHack, can be built using the Visual C IDE.
 274
 275 I. Dispelling the Myths:
 276
 277     Compiling NetHack using the Visual C IDE is straightforward, as long
 278     as you have your compiler and tools correctly installed.
 279
 280     It is again assumed that you already changed your directory to
 281     sys\winnt and executed:
 282         nhsetup
 283     as described at the top of this document. If you didn't, you must go
 284     back and do so before proceeding.
 285
 286 II. To compile your copy of NetHack for Windows on a Windows NT/2000/XP
 287     machine using the Visual C IDE:
 288
 289 Setting Up
 290
 291 1.  It almost goes without saying that you should make sure that your
 292     tools are set up and running correctly. (For the Microsoft Visual C
 293     IDE it should correctly fire up when you choose it in your Start |
 294     Programs menus.)
 295
 296 2.  Make sure all the NetHack files are in the appropriate directory
 297     structure.  You should have a main directory with subdirectories
 298     dat, doc, include, src, sys\share, sys\winnt, util, win\win32, and
 299     at this point you should also have a build directory and a binary
 300     directory (both created by nhsetup.bat executed from sys\winnt
 301     earlier.)
 302
 303     Other subdirectories may also be included in your distribution, but
 304     they are not necessary for building the graphical version of NetHack
 305     (you can delete them to save space if you wish.)
 306
 307     Required Directories for building Graphical NetHack with the Visual
 308     C IDE:
 309
 310                             top
 311                              |
 312         -----------------------------------------/ /---------------
 313         |     |    |      |     |   |      |           |       |
 314        util  dat  doc  include src sys    win        build    binary
 315                                     |      |
 316                                   ------   -----
 317                                   |    |       |
 318                                share  winnt  win32
 319
 320     Those last two (build and binary) are created during the building
 321     process.  They are not disributed as part of the NetHack source
 322     distribution.  nhsetup.bat creates the build directory and moves a
 323     few files into it, including the Visual C project files.  The
 324     "binary" directory will house everything you need to play the game
 325     after building is complete.
 326
 327     Check the file "Files" in your top level directory for an exact
 328     listing of what file is in which directory.  In order for the build
 329     process to work, all the source files must be in the proper
 330     locations.  Remember that nhsetup.bat moves/copies many files around
 331     to their intended locations for building NetHack.
 332
 333     If you downloaded or ftp'd the sources from a UNIX system, the lines
 334     will probably end in UNIX-style newlines, instead of the carriage
 335     return and line feed pairs used by Windows.  Visual C project files
 336     and workspace files (dsp and dsw files) in particular need to have
 337     their lines end in carriage-return-line-feed or they won't work
 338     properly.
 339
 340 3.  Ready your tool.
 341     Note: It's possible to build a graphical version using the Makefile,
 342     as explained above. However, the IDE build has full game
 343     functionality and is the officially released build.
 344
 345     Start the Visual C IDE. In the Visual C IDE menus, choose:
 346         File | Open Workspace
 347
 348 4.  Set up for the build.
 349
 350     In the Visual C "Open Workspace" dialog box, navigate to the top of
 351     your NetHack source directory.
 352
 353     In there, highlight "nethack.dsw" and click on Open.
 354     Once the workspace has been opened, you should see the following
 355     list in the Visual C selection window:
 356       + dgncomp files
 357       + dgnstuff files
 358       + dlb_main files
 359       + levcomp files
 360       + levstuff files
 361       + makedefs files
 362       + nethackw files
 363       + recover files
 364       + tile2bmp files
 365       + tilemap files
 366       + uudecode files
 367
 368     On the Visual C menus, choose:
 369         Project | Set Active Project | NetHackW
 370
 371     On the Visual C menus again, choose either:
 372         Build | Set Active Configuration | NetHackW - Win32 Release
 373     or
 374         Build | Set Active Configuration | NetHackW - Win32 Debug
 375
 376     The first will create the Release build of NetHackW which does not
 377     contain all the debugging information and is smaller, and runs
 378     quicker.  The second will create the Debug build of NetHackW and
 379     will spend a lot of time writing debug information to the disk as
 380     the game is played. Unless you are debugging or enhancing NetHack
 381     for Windows, choose the Release build.
 382
 383 Building
 384
 385 5.  Start your build.
 386
 387     On the Visual C menus once again, choose:
 388         Build | Build NetHackW.exe
 389     This starts the build.  It is likely that the IDE message window
 390     where you are doing the compiling will be occupied for a while.
 391
 392 6.  If all has gone well to this point, you should now have a NetHack
 393     executable called NetHackW.exe in the "binary" directory, along with
 394     all the support files that it needs.
 395
 396
 397 RUNNING NETHACK
 398
 399 I. Checking the installation:
 400     Make sure all of the support files -- Guidebook.txt, license,
 401     Defaults.nh, NetHack.exe or NetHackW.exe, nhdat, and recover.exe --
 402     were copied to the game directory.  If not, move them there
 403     yourself.
 404
 405     Edit Defaults.nh to reflect your particular setup and personal
 406     preferences, by following the comments.  As with all releases since
 407     3.2.1, HACKDIR defaults to the same directory as that where the
 408     NetHack.exe or NetHackW.exe executable resides.  You only need to
 409     set HACKDIR in defaults.nh if, for some reason, you wish to override
 410     that (be careful).
 411
 412 II. Executing the game
 413
 414 1.  Running from the command prompt:
 415
 416     If you add the directory containing the NetHack executable to your
 417     PATH, you can just type "nethack" or "nethack -umike" or "nethackw"
 418     or "nethackw -umike" to start it up.  Alternatively, you can
 419     explicitly invoke it with a command such as
 420     "c:\nethack\binary\nethack.exe" or "c:\nethack\binary\nethackw.exe"
 421     (specifying whatever drive and directory your NetHack executable
 422     resides in) each time.
 423
 424 2.  Running from a Windows shortcut.
 425
 426     If you will be running it by launching it from a shortcut, just use
 427     the following information when setting up the shortcut.
 428
 429         Description      :  NetHack 3.4.3 Console version
 430         Command Line     :  C:\NETHACK\BINARY\NETHACK.EXE
 431
 432         Description      :  NetHack 3.4.3 Graphical Interface
 433          Command Line     :  C:\NETHACK\BINARY\NETHACKW.EXE
 434
 435    (changing the directory to the appropriate one of course)
 436
 437 III. Play NetHack.  If it works, you're done!
 438
 439
 440 PROBLEMS
 441
 442     If you discover a bug and wish to report it, or if you have comments
 443     or suggestions we recommend using our "Contact Us" web page at:
 444         http://www.nethack.org/common/contact.html
 445
 446     If you don't have access to the web, or you want to send us a patch
 447     to the NetHack source code feel free to drop us a line c/o:
 448         DevTeam (at) nethack.org
 449
 450     Happy NetHacking!