Copyright (c) NetHack Development Team 1990-2012 NetHack may be freely redistributed. See license for details. ============================================================== Instructions for compiling and installing NetHack 3.5 on a Windows system (Windows XP and Windows 2003 or later only) ============================================================== Last revision: $NHDT-Date$ Last revision: $Date: 2012/01/15 17:43:54 $ Credit for the porting of NetHack to the Win32 Console Subsystem goes to the NT Porting Team started by Michael Allison. Credit for the Win32 Graphical version of NetHack (aka "NetHack for Windows" or NetHackW) goes to Alex Kompel who initially developed and contributed the port. The PC Windows porting team consisting of Michael Allison, David Cohrs, Alex Kompel, Dion Nicolaas, Yitzhak Sapir, and Janet Walz maintained the tty and graphical win32 versions of NetHack 3.5.0. You can build either the TTY version of NetHack or the Windows Graphical version. In either case you can use one of the following build environments: o A copy of Microsoft Visual Studio 2010 Express The current NetHack code has not been tested with earlier versions of the compiler. 64-bit Note: To build a 64-bit target with the Express edition, you will also need to download and install the Windows Software Development Kit version 7.1 Visual Studio 2010 Express does not include a 64 bit C compiler by default. (http://msdn.microsoft.com/en-us/windowsserver/bb980924.aspx) OR o [UNTESTED FOR 3.5] A copy of Borland C 5.5.1 command line tools. Borland has made a version of its command line tools available for download after registration at: http://www.borland.com/bcppbuilder/freecompiler/ OR o [UNTESTED FOR 3.5] A copy of MinGW 2.0 or later. MinGW is a collection of header files and import libraries with which native Windows32 programs can be built; the MinGW 2.0 distribution contains the GNU Compiler Collection. You can download MinGW at http://www.mingw.org/ Earlier versions of MinGW will not allow you to build the Windows Graphical version. In addition to the makefiles that allow you to build NetHack from the command line, there is also a set of project files and a workspace file that allow you to build the Windows Graphical version from Microsoft Visual C's IDE (Integrated Development Environment.) /-----------------------------------\ | FIRST STEP - MOVING THINGS AROUND | \-----------------------------------/ The first step in building either version of NetHack is to execute sys\winnt\nhsetup.bat to move some files to their required locations. From the command prompt: cd sys\winnt nhsetup From a Windows explorer window: double-click on nhsetup.bat A "binary" directory will be created off the top of the NetHack source tree to house the completed build. A build subdirectory will also be created off the top of the NetHack source tree, and many files appropriate for a graphical build will be moved there. If you wish to build from the command line, proceed to "BUILDING FROM THE COMMAND LINE." If you wish to build using Visual C's IDE, proceed now to "BUILDING USING VISUAL C'S IDE." /--------------------------------\ | BUILDING FROM THE COMMAND LINE | \--------------------------------/ You can built two different versions of NetHack for Win32 from the command line: A tty port utilizing the Win32 Console I/O subsystem, Console NetHack; A Win32 native port built on the Windows API, Graphical NetHack or NetHackW. The executable for Console NetHack will be named NetHack.exe. The executable for Graphical NetHack will be named NetHackW.exe. You can opt to build both; they will be able to use the same datafiles, save files and bones files. I. Dispelling the Myths: Compiling NetHack for Win32 is not as easy as it sounds, nor as hard as it looks, however it will behoove you to read this entire section through before beginning the task. We have provided a Makefile for each of the following compilers: o Microsoft Visual Studio 2010 Express Visual C++ Compiler o Borland C 5.5.1 o MinGW 2.0 (with GCC 3.2) The Microsoft Visual Studio 2010 Express Makefile was created for use with MS NMAKE which is provided with the Microsoft compiler. The supplied Makefile may work with earlier versions of the Microsoft compiler, but that has not been tested. The Borland C Makefile was created for use with Borland MAKE which is provided with the Borland compiler. The GCC Makefile was created for use with GNU Make version 3.79.1, which comes with the MinGW package. You may find it useful to obtain copies of lex (flex) and yacc (bison, or byacc). While not strictly necessary to compile nethack, they are required should you desire to make any changes to the level and dungeon compilers. II. To compile your copy of NetHack on a Windows NT/2000/XP machine: Setting Up 1. It almost goes without saying that you should make sure that your tools are set up and running correctly. That includes ensuring that all the necessary environment variables for the compiler environment are set correctly. For Visual Studio 2010 Express, the installation should have placed a command prompt option on the Start menus that is properly configured for building: From Start | All Programs | Microsoft Visual Studio 2010 Express Select Visual Studio Command Prompt 2010 64-bit Note: The additional installation of Microsoft Windows SDK V7.1 will have placed a command prompt option on the Start menus that is properly configured for building as well, but supports the Windows SDK tools. That is what should be used if you wish to target an x64 build for example. From Start | All Programs | Microsoft Windows SDK v7.1 Select Windows SDK 7.1 Command Prompt Then, for an x86 (32-bit) target run the following at the command prompt: SETENV /x86 If you prefer to target an x64 (64-bit) build run the following at the command prompt: SETENV /x64 For the GCC Makefile, add \bin to your path, where is your MinGW root directory.). For the Borland Makefile, you can simply invoke the Make utility from the Makefile's directory (For the standard Borland compiler installation you can just use the explicit path "c:\borland\bcc55\bin\make /f Makefile.bcc". NetHack 3.5.0 has not yet been tested with the Borland compiler. 2. Make sure all the NetHack files are in the appropriate directory structure. You should have a main directory with subdirectories dat, doc, include, src, sys\share, sys\winnt, util, and binary (The "binary" directory was created by nhsetup.bat earlier if you followed the steps appropriately). For Console NetHack you need win\tty in addition to these; for Graphical NetHack you need win\win32 in addition to these. Other subdirectories may also be included in your distribution, but they are not necessary for building the TTY version for the Win32 console subsystem. You can delete them to save space. Required Directories for a Win32 Console NetHack: top | ----------------------------------------------------/ /----- | | | | | | | | util dat doc include src sys win binary | | ------ ----- | | | share winnt tty Required Directories for a Win32 Graphical NetHack: top | ----------------------------------------------------/ /----- | | | | | | | | util dat doc include src sys win binary | | ------ ----- | | | share winnt win32 Check the file "Files" in your top level directory for an exact listing of what file is in which directory. In order for the Makefiles to work, all the source files must be in the proper locations. If you downloaded or ftp'd the sources from a UNIX system, the lines will probably end in UNIX-style newlines, instead of the carriage return and line feed pairs used by Windows. Some programs have trouble with them, so you may need to convert them. The compiler should not have any problems with them however. 3. Now go to the include subdirectory to check a couple of the header files there. Things *should* work as they are, but since you have probably set up your system in some sort of custom configuration it doesn't hurt to check out the following: First check config.h according to the comments to match your system and desired set of features. Mostly you need to check section 4 and 5. You may include all or as few of the special game features as you wish (they are located last in the file). 4. Edit your Makefile. For building Console NetHack, ensure that GRAPHICAL is set to "N", or commented out. For building Graphical NetHack, set GRAPHICAL to "Y". Optional step: If you elected not to use the high-quality BSD random number routines by commenting out RANDOM in ntconf.h, comment out (or set equal to nothing) the RANDOM macro in your Makefile. If you are recompiling after patching your sources, or if you got your files from somewhere other than the official distribution, "touch makedefs.c" to ensure that certain files (onames.h and pm.h) are remade, lest potentially troublesome timestamps fool your make (or nmake) utility. Compiling 5. Now that everything is set up... For Visual Studio 2010 Express, as mentioned above, the installation should have placed a command prompt option on the Start menus that is properly configured for building: From Start | All Programs | Microsoft Visual Studio 2010 Express Select Visual Studio Command Prompt 2010 Change your current directory to the NetHack src directory. Issue this command: nmake install 64-bit Note: As previously mentioned, you should start your command prompt from the Windows SDK v7.1 menu which is properly configured for building using the Windows SDK tools. From Start | All Programs | Microsoft Windows SDK v7.1 Select Windows SDK 7.1 Command Prompt Change your current directory to the NetHack src directory. Then, for an x86 (32-bit) target run the following at the command prompt: SETENV /x86 nmake install If you prefer to target an x64 (64-bit) build run the following at the command prompt: SETENV /x64 nmake install For Borland compiler: Change your current directory to the NetHack src directory. Issue this command: make /f Makefile.bcc install For GCC: Change your current directory to the NetHack src directory. Issue this command: mingw32-make -f Makefile.gcc install If you get any errors along the way then something has not been set up correctly. The time it takes to compile depends on your particular machine of course, but you should be able to go for lunch and return to find everything finished. The less memory, and slower your machine, the longer the lunch you may take. :-) In any case, it is likely that the command prompt window where you are doing the compiling will be occupied for a while. If all goes well, you will get an NetHack executable. Notes: 1. To install an update of NetHack after changing something, change your current directory to src and issue the appropriate command for your compiler: For Microsoft compiler: nmake For Borland compiler: make /f Makefile.bcc For GCC: mingw32-make -f Makefile.gcc If you add, delete, or reorder monsters or objects, or you change the format of saved level files, delete any save and bones files. (Trying to use such files sometimes produces amusing confusions on the game's part, but usually crashes.) If you made changes to any of the level compiler software, you may have to delete dgn_flex.c, dgn_yacc.c, lev_flex.c, and lev_yacc.c from the util directory to ensure that they are remade. 2. Depending on the build and compiler and tools used above, the executable produced by the TTY build is either: - a 32-bit (x86), flat-address space, non-overlayed .exe file, which should run on any true Win32 environment. or - a 64-bit (x64) .exe file, which should run on any 64-bit Windows O/S. To run NetHack, proceed to RUNNING NETHACK. /-------------------------------------------------\ | BUILDING USING VISUAL STUDIO 2010 EXPRESS IDE | \-------------------------------------------------/ Only the native port built on the Windows API, or Graphical NetHack, can be built using the Visual Studo 2010 Express IDE. I. Dispelling the Myths: Compiling NetHack using the Visual C IDE is straightforward, as long as you have your compiler and tools correctly installed. It is again assumed that you already changed your directory to sys\winnt and executed: nhsetup as described at the top of this document. If you didn't, you must go back and do so before proceeding. II. To compile your copy of NetHack for Windows on a Windows machine using the Visual Studio 2010 Express IDE: Setting Up 1. It almost goes without saying that you should make sure that your tools are set up and running correctly. (For the Microsoft Visual Studio 2010 ExpressIDE it should correctly fire up when you choose it: Start | All Programs | Microsoft Visual Studio 2010 Express and select Visual C++ 2010 Express 2. Make sure all the NetHack files are in the appropriate directory structure. You should have a main directory with subdirectories dat, doc, include, src, sys\share, sys\winnt, util, win\win32, and at this point you should also have a build directory and a binary directory (both created by nhsetup.bat executed from sys\winnt earlier.) Other subdirectories may also be included in your distribution, but they are not necessary for building the graphical version of NetHack (you can delete them to save space if you wish.) Required Directories for building Graphical NetHack with the Visual C IDE: top | -----------------------------------------/ /--------------- | | | | | | | | | util dat doc include src sys win build binary | | ------ ----- | | | share winnt win32 Those last two (build and binary) are created during the building process. They are not disributed as part of the NetHack source distribution. nhsetup.bat creates the build directory and moves a few files into it, including the Visual C project files. The "binary" directory will house everything you need to play the game after building is complete. Check the file "Files" in your top level directory for an exact listing of what file is in which directory. In order for the build process to work, all the source files must be in the proper locations. Remember that nhsetup.bat moves/copies many files around to their intended locations for building NetHack. If you downloaded or ftp'd the sources from a UNIX system, the lines will probably end in UNIX-style newlines, instead of the carriage return and line feed pairs used by Windows. Visual C project files and workspace files (dsp and dsw files) in particular need to have their lines end in carriage-return-line-feed or they won't work properly. 3. Ready your tool. Note: It's possible to build a graphical version using the Makefile, as explained above. However, the IDE build has full game functionality. Start the Visual Studio 2010 Express IDE: Start | All Programs | Microsoft Visual Studio 2010 Express and select Visual C++ 2010 Express In the Visual C++ 2010 Express IDE menus, choose: File | Open Project/Solution 4. Set up for the build. In the Visual C dialog box, navigate to the top of your NetHack source directory. In there, highlight "nethack.sln" for Visual C++ 2010 Express Edition and click on Open. Once the workspace or solution has been opened, you should see the following list in the Visual C selection left pane: + dgncomp + dgnstuff + dlb_main + levcomp + levstuff + makedefs + nethackw + recover + tile2bmp + tilemap + uudecode On the Visual C++ 2010 Express IDE menus, NetHackW should be the startup project in bold, but if it isn't make it so by right-clicking and choosing "set as Startup Project." In Visual C 2010 Express IDE menus right-click on "Solution NetHack (12 Projects)" and select "Configuration Manager." Set the "Active Solution Configuration" to either Debug or Release and click the "Close" button. The Release build of NetHackW which does not contain all the debugging information and is smaller, and runs slightly quicker. The Debug build of NetHackW will spend time writing debug information to the disk as the game is played. Unless you are debugging or enhancing NetHack for Windows, you probably will want to choose the Release build. Building 5. Start your build. On the Visual C++ Express IDE menus once again, choose: Debug | Build Solution or press to accomplish the same thing. That starts the build. It is likely that the IDE message window where you are doing the compiling will be occupied for a while. 6. If all has gone well to this point, you should now have a NetHack executable called NetHackW.exe in the "binary" directory, along with all the support files that it needs. /-----------------\ | RUNNING NETHACK | \-----------------/ I. Checking the installation: Make sure all of the support files -- Guidebook.txt, license, Defaults.nh, NetHack.exe or NetHackW.exe, nhdat, and recover.exe -- were copied to the game directory. If not, move them there yourself. Edit Defaults.nh to reflect your particular setup and personal preferences, by following the comments. As with all releases since 3.2.1, HACKDIR defaults to the same directory as that where the NetHack.exe or NetHackW.exe executable resides. You only need to set HACKDIR in defaults.nh if, for some reason, you wish to override that (be careful). II. Executing the game 1. Running from the command prompt: If you add the directory containing the NetHack executable to your PATH, you can just type "nethack" or "nethack -umike" or "nethackw" or "nethackw -umike" to start it up. Alternatively, you can explicitly invoke it with a command such as "c:\nethack\binary\nethack.exe" or "c:\nethack\binary\nethackw.exe" (specifying whatever drive and directory your NetHack executable resides in) each time. 2. Running from a Windows shortcut. If you will be running it by launching it from a shortcut, just use the following information when setting up the shortcut. Description : NetHack 3.5.0 Console version Command Line : C:\NETHACK\BINARY\NETHACK.EXE Description : NetHack 3.5.0 Graphical Interface Command Line : C:\NETHACK\BINARY\NETHACKW.EXE (changing the directory to the appropriate one of course) III. Play NetHack. If it works, you're done! PROBLEMS If you discover a bug and wish to report it, or if you have comments or suggestions we recommend using our "Contact Us" web page at: http://www.nethack.org/common/contact.html If you don't have access to the web, or you want to send us a patch to the NetHack source code feel free to drop us a line c/o: DevTeam (at) nethack.org Happy NetHacking!