The Dark Mod - Compilation Guide

Intended article audience: engine coders

This guide should provide you with enough information to compile The Dark Mod's game code from source. It applies to version 2.09 or later version of TDM. If you want to compile older version, see the history of this wiki page. Brief compilation instructions are also included in COMPILING.txt file in the source code package.

Get the sources

The sources are available through "snapshots", i.e. whenever the Dark Mod team is releasing a new update (e.g. TDM 2.09) the corresponding sources are released as well.

• You can download a source code archive from the Downloads page: http://www.thedarkmod.com/downloads/

The executables built from these sources are compatible with the latest official release of TDM.

Also you can get the very latest source code directly from SVN:

• Public read-only access: https://svn.thedarkmod.com/publicsvn/darkmod_src/trunk/
• Team members only: https://svn.thedarkmod.com/svn/darkmod_src/trunk

Be warned though that these sources might be incompatible with your local darkmod installation. To minimize the problem, developer builds of the game are available in tdm_installer. Each developer build is named like devXXXXX-YYYY, where YYYY is the SVN revision number which this version was built from. If you checkout this exact revision from the source code SVN and build executable from it, it will surely be compatible with the corresponding dev. build of TDM.

Directory structure

Put the source code directory next to your game directory, such that the directory structure looks like this:

C:\Games\Doom3\darkmod       <-- your darkmod installation
C:\Games\Doom3\darkmod_src   <-- your source folder (containing the solution)

This directory structure is recommended for both Windows and Linux.

Windows

Since TDM 2.07 you'll need Visual Studio 2017 to compile the project. The free Community Edition works fine, it can be downloaded approximately here. Additionally, you have to:

• Make sure "Visual C++ MFC for x86 and x64" is being installed by MSVC installer, along with "Desktop development with C++" workflow (see screenshot below)
• If compiling 2.07, make sure "Windows XP support for C++" is installed too (not needed for 2.08).

You'll find a TheDarkMod.sln solution file (in MSVC 2017 format) in the source code folder, which you can double-click to open in Visual Studio. The solution is designed to put the compiled binaries into the ../darkmod folder nearby, that's why we recommend using the directory layout shown above. (You can change the output paths in the property sheets, in case you know how to do that).

Once the solution is opened, select the Configuration in the topmost toolbar (either "release" or "debug", depending on what you want to do) and Platform (either Win32 or x64). Then hit "Build Solution" (Ctrl-Shift-B or F7). The compilation usually takes a minute or two, watch the output window at the bottom of Visual Studio. After completion you'll find the compiled binary in your darkmod/ folder. It would be either TheDarkMod.exe or TheDarkModx64.exe, depending on the configuration used.

Debugging the Engine/Game

To debug your custom built code, you need to attach Visual Studio's debugger to the TheDarkMod.exe process. There are two ways to accomplish that:

The quick one:

1. Go to Visual Studio and open the TheDarkMod solution
2. Make sure the "DarkModTools" project is marked bold (as "Startup project")
3. Compile and hit run (F5), Studio will start your TheDarkMod.exe and attach automatically

The manual way:

1. Start your custom TheDarkMod.exe through Windows Explorer or shortcuts
2. Once the game is up and running, Alt-Tab back to Visual Studio
3. Go to menu "Debug" > "Attach to Process..." and select the TheDarkMod.exe process from the list in that dialog popping up.
4. The debugger will now attach to TDM and you can now place breakpoints or intercept game crashes.

Troubleshooting

My breakpoints don't work (they are hollow circles instead of full ones)

Make sure you're attached to the correct TheDarkMod.exe binary. If you're attaching to an older version (e.g. from an outdated compilation process) or one you haven't built in Studio yourself, VC++ won't be able to load the symbols from the .pdb files. Make sure that the configuration type (release or debug build) is matching as well.

I cannot inspect all the variables / The instruction pointer is skipping code

You are probably running a release build, which comes with some optimisations. When debugging a release build, you'll notice that your instruction pointer (the yellow arrow) is sometimes skipping statements, which have most likely been optimised out of the binary during compilation/linking. You'll also have troubles when trying to inspect temporary variables or inlined functions. Use a debug build if this prevents you from figuring out things during debugging.

Debugging works well, but the game plays too slowly

You are running debug build, which is much slower than release. There are several ways to make life easier. First, you can get to the place where problem happens in release build and save your game there, then run debug build and load the game to do debugging. Second, you can try the "Debug with inlines" configuration, which is faster than full debug build, but is still very convenient to debug. If this is not fast enough for you, you can also debug the release build directly, but be aware that breakpoints and watches do not always work due to optimizations. Note that even release build is slower with debugger than without it because of debug heap. You can disable it by setting environment variable _NO_DEBUG_HEAP=1. If you do it properly, then your release build should run with full speed.

Linux

You need GCC 5 or newer to build TDM on Linux. Anything older than GCC 4.7 surely won't work. CMake >= 3.12 is required starting from TDM 2.08.

You first need to create a build directory. Easiest option is to create a subdirectory in the source code root directory ("darkmod_src"):

 mkdir build && cd build

From your build directory, call CMake:

 cmake -DCMAKE_BUILD_TYPE="Release" ..

The '..' indicate the path to the source directory. If you chose a different location for your build directory instead of the suggested subdirectory, you have to adjust this parameter accordingly. Finally, build TDM by calling

 make -j

where the '-j' parameter instructs make to build the project in parallel for faster compile times.

For newer Ubuntu and Linux Mint versions, it may be better to use:

 make -j$(nproc)

to ensure that the number of processes is limited to available cores.

If you wish to compile a debug executable, pass '-DCMAKE_BUILD_TYPE="Debug"' to the CMake call.

Ubuntu 16.04: native

The simplest approach is to do a native build, i.e. produce 64-bit binaries on 64-bit OS, or 32-bit binaries on 32-bit OS. Starting from a clean Ubuntu installation, here is the list of packages you need to install:

 sudo apt-get install subversion               //svnversion: not found
 sudo apt-get install mesa-common-dev          //no such file: "Gl/gl.h", <=2.07
 sudo apt-get install libxxf86vm-dev           //no such file: "X11/extensions/xf86vmode.h"
 sudo apt-get install libopenal-dev            //no such file: "AL/al.h"
 sudo apt-get install libxext-dev              //no such file: "X11/extensions/Xext.h"
 sudo snap install cmake                       //we need a recent version of CMake, so install from snap instead of apt

Now run CMake as instructed above.

Ubuntu 16.04: 32-bit version on 64-bit OS

If you have 64-bit Linux, you can also build and run 32-bit TDM. Note that this approach is slightly more complicated.

You have to install the following packages in addition to the ones listed above:

 sudo apt-get install g++-multilib             //no such file: 'sys/cdefs.h'
 sudo apt-get install libx11-dev:i386          //cannot find "-lX11"
 sudo apt-get install libxxf86vm-dev:i386      //cannot find "-lXxf86vm"
 sudo apt-get install libopenal-dev:i386       //cannot find "-lopenal"
 sudo apt-get install libxext-dev:i386         //cannot find "-lXext"

Then you need to call CMake with a toolchain file to target 32-bit:

 cmake -DCMAKE_BUILD_TYPE="Release" -DCMAKE_TOOLCHAIN_FILE="../sys/cmake/gcc_32bit.cmake" ..

The 64-bit and 32-bit versions can be built independently on a single 64-bit Linux, but you need to use different build directories for each version.

Other distros

Even if you have a Linux distro different from Ubuntu, the instructions above will most likely help you. If you still have problems with your build, please report to the forums.

E.g. for Kali Linux

 sudo apt-get update
 sudo apt-get install build-essential manpages-dev 
 sudo apt-get install cmake
 sudo apt install libx11-dev      
 sudo apt-get install libxxf86vm-dev  
 sudo apt-get install libxext-dev

I have a bugfix for the team

In case you figured out a problem in the TDM game code and you maybe even have a fix available, please drop by at our forums to tell the coding staff. Your fix might be incorporated in the main development branch.

See also Reporting Problem article.

Working in SVN

If you work directly with SVN, make sure that svnversion command works properly in OS console:

• Windows: install TortoiseSVN with "command line client tools" included.
• Linux: install "subversion" package.

To check that it works, build TDM yourself, run it, and then open TDM console. You should see the correct SVN revision number in the lower-right corner.