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 $
10 Credit for the porting of NetHack to the Win32 Console Subsystem goes to
11 the NT Porting Team started by Michael Allison.
13 Credit for the Win32 Graphical version of NetHack (aka "NetHack for
14 Windows" or NetHackW) goes to Alex Kompel who initially developed and
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.
21 You can build a TTY version of NetHack and a Windows Graphical
22 version. You can use one of the following build environments:
24 o A copy of Microsoft Visual Studio 2013 Express
25 The current NetHack code has not been tested with earlier versions
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
35 Earlier versions of MinGW will not allow you to build the Windows
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.)
44 /-----------------------------------\
45 | FIRST STEP - MOVING THINGS AROUND |
46 \-----------------------------------/
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.
51 From the command prompt:
55 From a Windows explorer window:
56 double-click on nhsetup.bat
58 A "binary" directory will be created off the top of the NetHack source
59 tree to house the completed build.
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
65 If you wish to build from the command line, proceed to "BUILDING FROM
68 If you wish to build using Visual C's IDE, proceed now to "BUILDING
69 USING VISUAL C'S IDE."
71 /--------------------------------\
72 | BUILDING FROM THE COMMAND LINE |
73 \--------------------------------/
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
79 A Win32 native port built on the Windows API, Graphical NetHack or
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.
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.
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.
98 I. Dispelling the Myths:
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.
104 We have provided a Makefile for each of the following compilers:
106 o Microsoft Visual Studio 2013 Express Visual C++ Compiler
107 o MinGW 2.0 (with GCC 3.2)
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.
114 The GCC Makefile was created for use with GNU Make version 3.79.1,
115 which comes with the MinGW package.
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.
122 II. To compile your copy of NetHack on a Windows machine:
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
131 Visual Studio 2013 Express
133 The installation should have placed a command prompt option on the
134 Start menus that is properly configured for building:
136 Start | All Programs | Microsoft Visual Studio 2013 Express
138 Visual Studio Command Prompt 2013
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:
144 For a 32-bit x86 build (like the official binary):
145 cd "\Program Files (x86)\Microsoft Visual Studio 12.0\VC"
148 For a 64-bit x64 build:
149 cd "\Program Files (x86)\Microsoft Visual Studio 12.0\VC"
152 -----------------------------------------------------------
153 vcvarsall.bat | Compiler | Build-computer | Build output
154 argument | | architecture | architecture
155 --------------+------------+----------------+--------------
156 X86 | x86 32-bit | x86, x64 | x86
158 --------------+------------+----------------+--------------
159 x86_amd64 | x64 on x86 | x86, x64 | x64
161 --------------+------------+----------------+--------------
162 amd64 | x64 64-bit | x64 | x64
164 --------------+------------+----------------+--------------
165 amd64_x86 | x86 on | x64 | x86
167 -----------------------------------------------------------
169 Change your current directory to the src subfolder of the nethack
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.:
194 For the GCC Makefile, add <mingw>\bin to your path, where <mingw>
195 is your MinGW root directory.).
197 Change your current directory to src subfolder of the nethack
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).
207 For Console NetHack you need win\tty in addition to these; for
208 Graphical NetHack you need win\win32 in addition to these.
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.
214 Required Directories for a Win32 Console NetHack:
218 ----------------------------------------------------/ /-----
220 util dat doc include src sys win binary
227 Required Directories for a Win32 Graphical NetHack:
231 ----------------------------------------------------/ /-----
233 util dat doc include src sys win binary
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
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.
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:
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
259 You may include all or as few of the special game features as you
260 wish (they are located last in the file).
262 4. Edit your Makefile if you wish, but it is not required unless
263 you are altering the build options.
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
273 5. Now that everything is set up...
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.
279 In the src subdirectory, issue this command:
283 Change your current directory to the NetHack src directory.
285 mingw32-make -f Makefile.gcc install
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. :-)
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.
299 1. To install an update of NetHack after changing something, change
300 your current directory to src and issue the appropriate command for
303 For Microsoft compiler:
307 mingw32-make -f Makefile.gcc
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.)
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.
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.
323 - a 64-bit (x64) .exe file,
324 which should run on any 64-bit Windows O/S.
326 To run NetHack, proceed to RUNNING NETHACK.
328 /-------------------------------------------------\
329 | BUILDING USING VISUAL STUDIO 2013 EXPRESS IDE |
330 \-------------------------------------------------/
332 Only the native port built on the Windows API, or Graphical
333 NetHack, can be built using the Visual Studo 2013 Express IDE.
335 I. Dispelling the Myths:
337 Compiling NetHack using the Visual C IDE is straightforward, as long
338 as you have your compiler and tools correctly installed.
340 It is again assumed that you already changed your directory to
341 sys\winnt and executed:
343 as described at the top of this document. If you didn't, you must go
344 back and do so before proceeding.
346 II. To compile your copy of NetHack for Windows on a Windows machine
347 using the Visual Studio 2013 Express IDE:
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
355 Start | All Programs | Microsoft Visual Studio 2013 Express
357 Visual C++ 2013 Express
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
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.)
370 Required Directories for building Graphical NetHack with the Visual
375 -----------------------------------------/ /---------------
377 util dat doc include src sys win build binary
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.
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.
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
404 Note: It's possible to build a graphical version using the Makefile,
405 as explained above. However, the IDE build has full game
408 Start the Visual Studio 2013 Express IDE:
409 Start | All Programs | Microsoft Visual Studio 2013 Express
411 Visual C++ 2013 Express
413 In the Visual C++ 2013 Express IDE menus, choose:
414 File | Open Project/Solution
417 4. Set up for the build.
419 In the Visual C dialog box, navigate to the top of
420 your NetHack source directory.
422 In there, highlight "nethack.sln" for Visual C++ 2013 Express Edition
425 Once the workspace or solution has been opened, you should see
426 the following list in the Visual C selection left pane:
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."
443 In Visual C 2013 Express IDE menus right-click on
444 "Solution NetHack (14 Projects)" and select "Configuration Manager."
446 Set the "Active Solution Configuration" to either
450 and click the "Close" button.
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
464 On the Visual C++ Express IDE menus once again, choose:
465 Debug | Build Solution
466 or press <F7> to accomplish the same thing.
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.
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.
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
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
494 II. Executing the game
496 1. Running from the command prompt:
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.
506 2. Running from a Windows shortcut.
508 If you will be running it by launching it from a shortcut, just use
509 the following information when setting up the shortcut.
511 Description : NetHack 3.6.0 Console version
512 Command Line : C:\NETHACK\BINARY\NETHACK.EXE
514 Description : NetHack 3.6.0 Graphical Interface
515 Command Line : C:\NETHACK\BINARY\NETHACKW.EXE
517 (changing the directory to the appropriate one of course)
519 III. Play NetHack. If it works, you're done!
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
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