Compiling

From NetHackWiki
Jump to: navigation, search

This page contains help on compiling NetHack 3.6, either the officially released version (3.6.0) or the version from the development sources (as of 2016 October). Compiling is necessary if you want to try out the dev team's latest changes when they haven't released a compiled version yet, or if you want to apply a patch, e.g. from the bilious database or make changes of your own.

Information about compiling NetHack 3.4.3 can still be found in an old version of this article, q.v..

Obtaining the Officially Released Sources

The official released NetHack source can be found here: http://nethack.org/v360/download-src.html

Once you have obtained the tarball, you will need to extract it, either using standard tools (tar -xvf nethack-360-src.tgz) or some other archive extractor that can handle the tar and gzip formats.

Note that if you use a graphical archive extractor like 7zip, you may have to extract twice: once to decompress the gzip and obtain the plain tar file, and a second time to extract the actual contents.

Obtaining the Development Sources

The development source repository is available at http://git.code.sf.net/p/nethack/NetHack

If you have git installed, you can retrieve a copy of the repository using either of the following commands:

git clone https://github.com/NetHack/NetHack

alternately:

git clone http://git.code.sf.net/p/nethack/NetHack

(It doesn't matter which repository you use; they're both mirrors of the public portion of the dev team's repository.)

This will create a subdirectory (a.k.a., a "folder") called 'NetHack', in the current directory, and the new subdirectory, 'NetHack', will be a git repository, containing a working copy of the latest public development source for what will eventually become NetHack 3.6.1.

Preparing to Compile

Gathering Build Tools

In order to build NetHack, you will neet at minimum the following tools:

  • a C compiler (typically 'gcc' or 'clang')
  • 'make' (typically Gnu 'make', and note in particular that Microsoft's 'nmake' won't work)
  • 'flex' and 'bison', or some other suitable lex/yacc implementation
  • common libraries (including development headers); these should be includeded if you have a complete working build environment (e.g., if you have installed build-essential on Debian-derived systems, you should have them). I don't know a complete list of all the libraries that are required, but I believe the list includes standard POSIX regular expression libraries, termcap/terminfo, and of course the standard C library. Beyond that, I'm not sure.
  • any libraries (including development headers) needed for the specific ports you wish to build; if this is the first time you are building NetHack, it is recommended that you start by building the Unix TTY port first, as it is the easiest and has no additional requirements of its own beyond the ones that all the ports require.

Note that you will need copies of all these on the platform for which you are building NetHack. Cross-compiling NetHack, if even possible, is much more complicated and far beyond the scope of this article.

Selecting a Hints File

The new build system introduced in NetHack 3.6.0 is based on "hints files", which inform the rest of the build system about various things which might differ from one system to another, and which you might wish to customize when building, even if you are making no changes to the actual game. Things like which directory to install the game's binaries into, which directory to use for storing the game data, which flags to pass to the compiler, and even basic facts like what the compiler on your system is called, are all specified in the hints file. A hints file is simply a plain text file, formatted like a shell script, that contains hints for the NetHack build system, in the form of setting variables.

You can find a collection of existing hints files in the sys/unix/hints/ directory. You may find that one of them is closer to what you want than others. For example, the 'linux' hints file is designed for a single-user install in ~/nh/install; whereas, the 'unix' hints file is designed for a traditional system-wide install in /usr. Look through the existing hints files and see if you can find one that is a close fit for your needs.

Modifying a Hints File

If you need to combine or modify a hints file, here are some useful things to know:

  • Lines starting with # are comments. You can thus prepend # to an existing line to comment it out, rendering it ineffective but leaving it there for reference.
  • There are four main directories that need to be specified: 'HACKDIR', 'SHELLDIR', 'INSTDIR', and 'VARDIR'. These are often based on a 'PREFIX' directory, which is not itself used directly for anything, but the others are typically located inside of it.
  • The CHOWN and CHGRP variables should contain the commands used to change ownership and group-ownership of files, respectively. Setting it to a command that doesn't do anything (such as 'yes' or 'true', as the stock 'linux' hints file does) will result in permissions not being changed, which is typically not what you want except possibly for a single-user install. If you are modifying the 'linux' hints file to build on a Linux system, you will probably want to change these lines.
  • The WINSRC, WINOBJ, and WINLIB lines control which window port you will build. If this is your first time compiling NetHack, it is recommended to start with the TTY port, which is easiest to build successfully.

Running the Build Setup Script

Once you have selected and possibly modified a hints file, you are ready to run the setup script. On most platforms, this is done with the following command: sys/unix/setup.sh sys/unix/hints/whichever_hints_file_you_are_using

On non-Unix platforms, the setup process may be slightly different. See the documentation for your platform. (TODO: someone should write up the Windows build setup here, as that's the only really widely used platform that isn't some kind of Unix.)

The setup script should copy the needed build-system files (e.g., makefiles) into place and modify them as needed.

Compiling

At this point, you may be able to just run the 'make' command and get a working build.

Installing

If the build goes well, you can (as root/superuser if necessary, or with sudo) use the 'make install' command to install your newly compiled NetHack.

Creating the System Config File

When you try to run your new build, it will complain that there is no syscf file and refuse to do anything until you create that file. The syscf file is allowed to be empty; it just has to exist.

Depending on which hints file you used, some permissions may need to be changed before the game can be run as a regular user.