sys/winnt/Install.nt

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