sys/winnt/Install.nt

   1          Copyright (c) NetHack Development Team 1990-2019
   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: 1554784481 2019/04/09 04:34:41 $
   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 Alex Kompel, Dion Nicolaas, Yitzhak Sapir, Derek S. Ray, Michael Allison,
  18 Pasi Kallinen, Bart House, and Janet Walz contributed to the maintainance
  19 of the tty and graphical windows versions of NetHack 3.6.2.
  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 2017 Community Edition or
  25     a copy of Microsoft Visual Studio 2019 Community Edition
  26
  27     OR
  28
  29   o (Untested for 3.6) A copy of MinGW. MinGW is a collection of header
  30     files and import libraries with which native Windows32 programs
  31     can be built; the MinGW distribution contains the GNU Compiler
  32     Collection. You can download MinGW at
  33         http://www.mingw.org/
  34     Earlier versions of MinGW will not allow you to build the Windows
  35     Graphical version.
  36
  37 /---------------------------------------------\
  38 |    Directories for a Win32 NetHack build    |
  39 \---------------------------------------------/
  40
  41
  42                  (NetHack-top) ----------------------(optional-pdcurses-top)
  43                        |                                        |
  44   ----------------------------------------------          --------------
  45   |     |     |        |      |     |          |          |            |
  46  util  dat   doc    include  src   sys        win      pdcurses      wincon
  47                                     |          |
  48                                  ------    --------
  49                                  |    |    |      |
  50                              share  winnt tty   win32
  51                                                   |
  52                                                 vs2017
  53
  54
  55 /--------------------------------------------------------\
  56 | Building And Running Using Visual Studio 2017          |
  57 \--------------------------------------------------------/
  58
  59 If you are NOT using Visual Studio 2017 IDE, or you prefer to build
  60 using a Make utility and a Makefile proceed to "Building Using Make".
  61
  62 When using either Visual Studio 2017, you simply need to load the
  63 solution file within the IDE, build the solution and  run the version
  64 of NetHack you wish to run.
  65
  66 The Visual Studio 2017 NetHack solution file can be found here:
  67     win\win32\vs2017\NetHack.sln
  68
  69 You can use that same win\win32\vs2017\NetHack.sln with Visual Studio 2019,
  70 but you may have to retarget the projects:
  71     Windows SDK Version: 10.0.17763.0  [ There have been some reports of
  72                                          difficulties if you instead choose
  73                                          "10.0 (latest installed version)" ]
  74     Platform Toolset: Upgrade to v142
  75
  76
  77 Before executing the steps to build listed in the next paragraph,
  78 decide if you want to include optional curses window-port. See
  79 the note just below entitled "Optional curses window-port support."
  80
  81 So the steps are:
  82     1. Launch the IDE.
  83     2. Open the appropriate solution file.
  84     3. Select the build configuration you wish to use (Release, Debug, etc.).
  85     4. From the build menu, select build solution.
  86     5. Type F5 to start debugging.
  87
  88 You can also build all the projects for all platforms and configurations
  89 using a "build.bat" batch file found in the same directory as the solution.
  90
  91 Open a developer command prompt for the version of Visual Studio you are
  92 using.  Change to the directory win\win32\vs2017 and run "build.bat".
  93
  94  * Optional curses window-port support *
  95
  96 Starting with 3.6.2, the community patch for a window-port that uses
  97 curses was incorporated into the NetHack source code tree. That window-port,
  98 which evolved from work originally done by Karl Garrison, has been used in
  99 several NetHack variants and on nethack.alt.org and on
 100 www.hardfought.org/nethack/.
 101
 102 If you want to include the curses window-port support in your Visual Studio
 103 build, you will have to first obtain the PDCurses sources from
 104 https://github.com/wmcbrine/PDCurses
 105 and have them available prior to building NetHack. There are two ways to
 106 enable curses window-port support during the VS build: Either set the
 107 environment variable PDCURSES to a folder containing a PDCurses
 108 repository/source-tree
 109     OR
 110 Place the PDCurses folder alongside the NetHack source repository prior
 111 to proceeding with steps 1 through 5 above.
 112
 113
 114 /-------------------------------------------\
 115 | Building From the Command Line Using Make |
 116 \-------------------------------------------/
 117
 118 --------------------------------------------------------------------------
 119 -- Beginning of prerequisite step --
 120
 121 The first step in building either version of NetHack via Makefile is to
 122 execute sys\winnt\nhsetup.bat to move some files to their required locations.
 123
 124 From the command prompt:
 125         cd sys\winnt
 126         nhsetup
 127
 128 From a Windows explorer window:
 129         double-click on nhsetup.bat
 130
 131 If you wish to build from the command line, proceed to "BUILDING FROM
 132 THE COMMAND LINE."
 133
 134 -- end of prerequisite step --
 135 --------------------------------------------------------------------------
 136
 137 Two different versions of NetHack will be built for Windows from the
 138 command line using the Makefile approach:
 139     A tty port utilizing the Win32 Console I/O subsystem, Console
 140         NetHack;
 141     A Win32 native port built on the Windows API, Graphical NetHack or
 142         NetHackW.
 143
 144 The executable for Console NetHack will be named NetHack.exe. The
 145 executable for Graphical NetHack will be named NetHackW.exe. The
 146 Makefile configuration will build both; NetHackW.exe and NetHack.exe
 147 will be able to use the same datafiles, save files and bones files.
 148
 149 Since the last official release of NetHack, compilers and computer
 150 architectures have evolved and you can now choose whether to build
 151 a 32-bit x86 version, or a 64-bit x64 version.  The default Makefile
 152 is set up for a 32-bit x86 version, but that's only because it will
 153 run on the most number of existing Windows environments.
 154
 155 NetHack's save files and bones files in the 3.6.2 release have not yet
 156 evolved enough to allow them to interchange between the 32-bit version
 157 and the 64-bit version (or between different platforms). Hopefully
 158 that will change in an upcoming release.
 159
 160 I. Dispelling the Myths:
 161
 162     Compiling NetHack for Windows is not as easy as it sounds, nor as hard
 163     as it looks, however it will behoove you to read this entire section
 164     through before beginning the task.
 165
 166     We have provided a Makefile for each of the following compilers:
 167
 168         o Microsoft Visual Studio 2015 or 2017 C++ Compiler
 169           The Community Editions are fine and available at no cost
 170         o MinGW 2.0 (with GCC 3.2)
 171
 172     The Microsoft Visual Studio makefile was created for use
 173     with MS NMAKE which is provided with the Microsoft compiler.
 174     The supplied Makefile may work with earlier versions of the Microsoft
 175     compiler, but that has not been tested.
 176
 177     The GCC Makefile was created for use with GNU Make version 3.79.1,
 178     which comes with the MinGW package.
 179
 180     You may find it useful to obtain copies of lex (flex) and yacc
 181     (bison, or byacc).  While not strictly necessary to compile nethack,
 182     they are required should you desire to make any changes to the level
 183     and dungeon compilers.
 184
 185 II. To compile your copy of NetHack on a Windows machine:
 186
 187 Setting Up
 188
 189 1.  It almost goes without saying that you should make sure that your
 190     tools are set up and running correctly.  That includes ensuring that
 191     all the necessary environment variables for the compiler environment
 192     are set correctly.
 193
 194     Change your current directory to the src subfolder of the nethack
 195     source tree.
 196         cd src
 197
 198     GCC
 199
 200     For the GCC Makefile, add <mingw>\bin to your path, where <mingw>
 201     is your MinGW root directory.).
 202
 203     Change your current directory to src subfolder of the nethack
 204     source tree.
 205         cd src
 206
 207 2.  Starting with 3.6.2, the community patch for an optional curses
 208     window-port was incorporated into the NetHack source code tree. That
 209     window-port, which evolved from work originally done by Karl Garrison,
 210     has been used in several NetHack variants and on nethack.alt.org and
 211     on www.hardfought.org/nethack/. The optional curses window-port is
 212     available for Windows, Mac OS X, and Unix (and also DOS).
 213
 214     If you want to include the optional curses window-port support in your
 215     command line Makefile build, you will have to first obtain the
 216     PDCurses sources from https://github.com/wmcbrine/PDCurses
 217     and have that source code tree available prior to building NetHack.
 218     Edit your Makefile and in Question 4 of the four decisions you can
 219     make in there, uncomment these two lines:
 220         ADD_CURSES=Y
 221         PDCURSES_TOP=..\..\pdcurses
 222
 223     Adjust the PDCURSES_TOP macro so that it points to the correct
 224     location for the top of the PDCurses source tree if it differs from
 225     the path shown.
 226
 227 3.  Make sure all the necessary files are in the appropriate directory
 228     structure.  You should have a main NetHack top directory with
 229     subdirectories dat, doc, include, src, sys\share, sys\winnt,
 230     win\tty, util.
 231
 232     If you are including the optional Curses window port into your
 233     build,then you will need the top of the PDCurses sources in a
 234     folder parallel to the top of the NetHack folder (or you will need
 235     to change the value of the PDCURSES_TOP macro in the Makefile to
 236     specify the appropriate location.
 237
 238     (You can check the file "Files" in your top level directory for a
 239      more complete listing of what file is in which directory.)
 240
 241     If you downloaded or ftp'd the sources from a UNIX system, the lines
 242     will probably end in UNIX-style newlines, instead of the carriage
 243     return and line feed pairs used by Windows.  Some programs have
 244     trouble with them, so you may need to convert them. The compiler
 245     should not have any problems with them however.
 246
 247 4.  Edit your Makefile if you wish, but it is not required unless
 248     you are altering the build options.
 249
 250     If you are recompiling after patching your sources, or if you got
 251     your files from somewhere other than the official distribution,
 252     "touch makedefs.c" to ensure that certain files (onames.h and pm.h)
 253     are remade, lest potentially troublesome timestamps fool your make
 254     (or nmake) utility.
 255
 256 Compiling
 257
 258 5.  Now that everything is set up...
 259
 260     For the Visual Studio compiler, as mentioned above, you should now be
 261     at the command prompt to carry out the build and your current
 262     directory should be the src subdirectory in the NetHack source tree.
 263
 264     In the src subdirectory, issue this command:
 265                 nmake install
 266
 267     For GCC:
 268         Change your current directory to the NetHack src directory.
 269         Issue this command:
 270                 mingw32-make -f Makefile.gcc install
 271
 272     If you get any errors along the way then something has not been set
 273     up correctly. The time it takes to compile depends on your
 274     particular machine of course, but you should be able to go for lunch
 275     and return to find everything finished.  The less memory, and slower
 276     your machine, the longer the lunch you may take. :-)
 277
 278     In any case, it is likely that the command prompt window where you
 279     are doing the compiling will be occupied for a while.  If all goes
 280     well, you will get an NetHack executable.
 281
 282 Notes:
 283
 284 1.  To install an update of NetHack after changing something, change
 285     your current directory to src and issue the appropriate command for
 286     your compiler:
 287
 288     For Microsoft compiler:
 289         nmake
 290
 291     For GCC:
 292         mingw32-make -f Makefile.gcc
 293
 294     If you add, delete, or reorder monsters or objects, or you change
 295     the format of saved level files, delete any save and bones files.
 296     (Trying to use such files sometimes produces amusing confusions on
 297     the game's part, but usually crashes.)
 298
 299     If you made changes to any of the level compiler software, you may
 300     have to delete dgn_flex.c, dgn_yacc.c, lev_flex.c, and lev_yacc.c
 301     from the util directory to ensure that they are remade.
 302
 303 2.  Depending on the build and compiler and tools used above, the
 304     executable produced by the TTY build is either:
 305       - a 32-bit (x86), flat-address space, non-overlayed .exe file,
 306         which should run on any recent Win32 environment.
 307     or
 308       - a 64-bit (x64) .exe file,
 309         which should run on any 64-bit Windows O/S.
 310
 311     Note that saved games are NOT compatible between the 32-bit and the
 312     64-bit versions at this time.
 313
 314 NetHack.exe is the tty version. NetHackW.exe is the graphical version.
 315 Play NetHack.
 316
 317 PROBLEMS
 318
 319     If you discover a bug and wish to report it, or if you have comments
 320     or suggestions we recommend using our "Contact Us" web page at:
 321         http://www.nethack.org/common/contact.html
 322
 323     If you don't have access to the web, or you want to send us a patch
 324     to the NetHack source code feel free to drop us a line c/o:
 325         DevTeam (at) nethack.org
 326
 327     Happy NetHacking!