The Dark Mod - Compilation Guide: Difference between revisions

From The DarkMod Wiki
Jump to navigationJump to search
← Older edit
No edit summary
No edit summary
 
(43 intermediate revisions by 10 users not shown)
Line 1: Line 1:
This guide should provide you with enough information to compile The Dark Mod's game code from source.
'''Intended article audience:''' engine coders


The sources are available through "snapshots", i.e. whenever the Dark Mod team is releasing a new update (e.g. TDM 1.01) the corresponding sources are released as well.
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 <tt>COMPILING.txt</tt> file in the source code package.


== Download the sources ==
You can download the latest source package from our website: http://www.thedarkmod.com/download_source.php


== Windows ==
== Get the sources ==
{{needs-update|text=This information about compiling needs to be revised since TDM 1.08 has been released}}
For Windows you'll need Visual Studio to compile the project, you can get the free Express editions from the Microsoft website. It should work with every version starting from VC++ 2008 upwards. (Note: you don't need a Platform SDK for VC++ 2008).


Download the sources and unpack them somewhere. You'll find a <tt>d3game.sln</tt> solution file (which is in VC++ 2008 format), which you can double-click to open in Visual Studio.  
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.


Once opened, select the Configuration Type in the topmost toolbar (either "release" or "debug", depending on what you want to do) and hit "Build Solution" ({{Ctrl}}-{{Shift}}-{{key|B}}). The compilation usually takes a few minutes, watch the output window at the bottom of Visual Studio. Once completed, you'll find the compiled <tt>gamex86.dll</tt> in a subfolder named "releasedll" (for release builds" or "debugdll" (for debug builds).


In order to "install" the gamex86.dll, you need to copy it somewhere where Doom3.exe can find it. There are two ways to do that: either you place the dll right next to your DOOM3.exe which will override any other mechanism (the game will always load the DLL right next to DOOM3.exe ''first''), or you put them in a PK4 (along with a binary.conf file) and place it in your mod folder. There is some info on www.iddevnet.com/doom3 about how to do that.
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 


=== Debugging the Game ===
Be warned though that these sources '''might be incompatible with your local darkmod installation'''.
To debug your custom built game code, you need to attach Visual Studio's debugger to the Doom3.exe process. There are two ways to accomplish that:
To minimize the problem, developer builds of the game are available in tdm_installer.
Each developer build is named like <tt>devXXXXX-YYYY</tt>, 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.


The quick one:
== Directory structure ==
# Go to Visual Studio and open the d3game solution
# Start the game (either through tdmlauncher.exe or through DOOM3.exe plus command lines)
# Once the game is up and running, Alt-Tab back to Visual Studio
# Go to menu "Debug" > "Attach to Process..." and select the DOOM3.exe process from the list in that dialog popping up.
# The debugger will now attach to Doom3 (along with all loaded DLLs) and you can now place breakpoints or intercept game crashes.


The longer one (if you debug your game more than once or twice):
Put the source code directory next to your game directory, such that the directory structure looks like this:
# Go to Visual Studio and open the d3game solution
# Right-click the Solution in the "Solution Explorer" and select "Add" > "Existing Project..."
# Browse to DOOM3.exe and select that, you'll see the DOOM3.exe project added to your solution explorer view.
# Right-Click the DOOM3.exe and choose "Select as startup project".
# Now you can start the debugger just by hitting F5 and Visual Studio will automatically attach to the Doom3 process.
# [Optional]: You can specify command line parameters to Doom3.exe by opening the Doom3.exe project properties and adding the desired parameters (e.g. com_allowConsole or fs_game_base/fs_game) to the "Command Arguments" item. This is necessary if you want to debug a specific TDM mission (although in this case, employing the "quick" method above is easier).


Note: you can still attach your debugger to any running DOOM3.exe process with the second method.
C:\Games\darkmod      <-- your darkmod installation
C:\Games\darkmod_src  <-- your source folder (containing the solution)


In Visual Studio Express 2010 (and later), you will first need to switch to Expert Settings via "Tools > Settings" to enable the "Debug" > "Attach to Process" option.
This directory structure is recommended for both Windows and Linux.


=== Troubleshooting ===
For windows users (this may also apply to linux users) - Install tortoise SVN and then right click on the \darkmod_src folder and select checkout. Then in the url field put 'https://svn.thedarkmod.com/publicsvn/darkmod_src/trunk/' then click ok (see screenshot below)
;My breakpoints don't work (they are hollow circles instead of full ones)
:Check if you copied the correct gamex86.dll to the folder where DOOM3.exe is located. The code you're viewing and the DLL loaded by DOOM3.exe must match ''exactly'', otherwise Visual Studio won't load your symbols. Make sure that the configuration type (release or debug build) is matching as well. Also make sure that the code is properly compiled, e.g. hit "Build Solution" again - the output window should tell you that everything is up to date.


;I cannot inspect all the variables / The instruction pointer is skipping code
[[File:Darkmod src.jpg|thumb]]
: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.
{{clear}}


== Linux ==
== Windows ==


For Linux you'll need gcc and scons, plus a few packages depending on your distribution. There is a README.linux file contained in the source package you downloaded, check it out for some details.
Since TDM 2.11 you'll need Visual Studio 2022 to compile the project (VS2017 was used before that).
The free Community Edition works fine, it can be downloaded [https://visualstudio.microsoft.com/vs/ 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).


=== Debian Sqeeze 64 bit ===
[[File:Unknown.png|thumb]]{{clear}}


You need the following packages:
You'll find a <tt>TheDarkMod.sln</tt> solution file 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).


apt-get install ia32-libs scons g++ g++-multilib m4 zip
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}}-{{key|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 <tt>TheDarkMod.exe</tt> or <tt>TheDarkModx64.exe</tt>, depending on the configuration used.
apt-get install libglew1.5-dev libpng12-dev libjpeg62-dev
apt-get install libc6-dev-i386 libxxf86vm-dev libopenal-dev libasound2-dev libxext-dev


You must also edit '''sys/scons/SConscript.game''' and add the following lines near where ''local_env.Append'' is alread 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:


local_env.Append(LIBS = [
The quick one:
        File('/lib32/libpng12.so.0'),
# Go to Visual Studio and open the TheDarkMod solution
])
# Make sure the "DarkModTools" project is marked bold (as "Startup project")
# Compile and hit run (F5), Studio will start your TheDarkMod.exe and attach automatically


Also change in the same file (a few lines above):
The manual way:
# Start your custom TheDarkMod.exe through Windows Explorer or shortcuts
# Once the game is up and running, Alt-Tab back to Visual Studio
# Go to menu "Debug" > "Attach to Process..." and select the TheDarkMod.exe process from the list in that dialog popping up.
# The debugger will now attach to TDM and you can now place breakpoints or intercept game crashes.


local_env.Append( LINKFLAGS = [ '-lrt', '-lpng' ] )
=== 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.


to:
;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.


local_env.Append( LINKFLAGS = [ '-lrt', '-lpng12' ] )
;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 [https://ofekshilon.com/2014/09/20/accelerating-debug-runs-part-1-_no_debug_heap-2/ _NO_DEBUG_HEAP=1]. If you do it properly, then your release build should run with full speed.


It might also be necessary to make the following symlink:
== Linux ==


ln -s /lib32/libpng12.so.0 /lib32/libpng.so
You need GCC 5 or newer to build TDM on Linux.
Anything older than GCC 4.7 surely won't work.
CMake >= 3.14 is required starting from TDM 2.08.


=== Ubuntu 10.10 64 Bit ===
You first need to create a build directory. Easiest option is to create a subdirectory in the source code
You'll need the same packages as for the 32 bit Ubuntu variants, plus a few additional 32 bit compatibility packages (ia32-libs and libc6-dev-i386):
root directory ("darkmod_src"):
sudo apt-get install g++ scons libglew1.5-dev libpng12-dev libjpeg62-dev ia32-libs libc6-dev-i386
  mkdir build && cd build
Then just run the scons command to start compiling:
From your build directory, call CMake:
scons BUILD="release" BUILD_GAMEPAK="1"
  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.


=== Ubuntu 10.04 32 Bit ===
If you need to force a specific GCC version because your Linux distro does not support GCC 5 but you've installed a newer GCC you may add flags to the cmake invoke:
After setting up a clean 10.04, these are the packages needed to get the source to compile. Copy & paste the following line:
  cmake -DCMAKE_BUILD_TYPE="Release" .. -DGAME_DIR=/home/user/darkmod -DCMAKE_C_COMPILER=gcc-11 -DCMAKE_CXX_COMPILER=g++-11
sudo apt-get install g++ scons libglew1.5-dev libpng12-dev libjpeg62-dev
( Replace gcc-11 g++-11 with whichever GCC version you intend to use. )
Then run this command to start compiling:
<br><br>Finally, build TDM by calling
./buildLinux.sh
  make -j
If the build fails, complaining that it can't find something, it needs more libraries. Execute the following line:
where the '-j' parameter instructs make to build the project in parallel for faster compile times.
sudo apt-get install m4 libxxf86vm-dev libopenal-dev libasound2-dev g++-multilib gcc-multilib zlib1g-dev libxext-dev
That should install all packages needed.


=== Ubuntu 9.10 x64 ===
For newer Ubuntu and Linux Mint versions, it may be better to use:
{{needs-update|text=This information about compiling in x64 builds needs to be reviewed}}
  make -j$(nproc)
I had to install the following packages in Ubuntu 9.10 x64 to compile The Dark Mod's source:
to ensure that the number of processes is limited to available cores.
scons 1.2.0
g++ 4.4.1
ia32-libs
libc6-dev-i386
libglew1.5-dev
libboost1.38-dev
While the boost headers from the Ubuntu repository work fine, all the libboost-*-dev binaries (which are 64 bit) won't work for the game code (which is 32 bit). Hence I had to track down and download a few packages on my own and extract the corresponding .a file from the .deb. I then placed the static libs in the /linux/boost/lib folder and adjusted the sconscript.game.


Note: the following won't be needed in TDM source versions 1.01 and higher as the boost and libstdc++ libs will already be included in newer source packages. In these newer packages you just need to open sys/scons/SConscript.game and uncomment three lines at the bottom of the script (I left a comment there about Ubuntu 9.10).


If you're trying to compile the 1.00 package, you'll need to download the binaries, I got mine from here: http://sb.itc.u-tokyo.ac.jp/DEBIAN/pool/main/b/boost1.38/?C=M;O=A
If you wish to compile a debug executable, pass '-DCMAKE_BUILD_TYPE="Debug"' to the CMake call.
libboost-filesystem1.38-dev_1.38.0-7_i386.deb
libboost-system1.38-dev_1.38.0-7_i386.deb
The actual version behind the 1.38.0 can vary, just be sure to get a boost 1.38 dev package from somewhere. Open it with the Archive Manager, open the contained <tt>data.tar.gz</tt> and extract the ./usr/lib/libboost_filesystem-mt.a (or libboost_system-mt.a) file. Remove the -mt part from the name and put these files into your darkmod_src/linux/boost/lib, so that you end up with the following files in there:
./linux/boost/lib/libboost_filesystem.a
./linux/boost/lib/libboost_system.a
Then fetch the libstdc++6_4.4.1-4ubuntu8_i386.deb file from any server you can find (I got mine from http://de.archive.ubuntu.com/ubuntu/pool/main/g/gcc-4.4/, the actual version "ubuntu8" might be different for you), right-click the file and open it with the Archive Manager, extract the libstdc++.so.6.0.13 file and rename it to libstdc++.so. Put that file in a newly created linux/libstdc/ folder.
./linux/boost/lib/libstdc++.so
As next step, adjust the sconscript.game file  (which is located in sys/scons/SConscript.game and scroll down towards the end of the script. There is a section defining the LIBS to be linked into the game module.
# Use static Boost and DevIL
local_env.Append(LIBS = [
    File('#/linux/devil/lib/libIL.a'),
    File('#/linux/boost/lib/libboost_filesystem.a'),  # ADD THIS ONE
    File('#/linux/boost/lib/libboost_system.a'),      # ADD THIS ONE
    File('#/linux/libstdc/libstdc++.so')              # ADD THIS ONE
])
Be sure to add the three lines marked with ADD THIS ONE. You should now be able to compile the code, and there will a tdm_game02.pk4 file created in the root folder of your source directory. Copy that file to your ~/.doom3/darkmod installation and launch the game.


== Mac OS X ==
=== Ubuntu 16.04: native ===
For OS X you'll need gcc and scons, as with Linux. gcc should be included in your xcode installation, scons can be downloaded from the [http://www.scons.org/ scons project website]. The third-party libraries like boost, devil and libcurl are already included in the TDM source package, so it should compile out of the box. If you ever need to build one of them from scratch, see the subsections below.


The sconscripts are prepared for both Intel and PPC target architectures, the MACOSX_TARGET_ARCH argument will control which architecture you're compiling for.
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:


=== Compiling for Intel architecture ===
  sudo apt-get install subversion              //svnversion: not found
To start compiling, enter the following command in the folder you extracted the TDM sources to:
  sudo apt-get install mesa-common-dev          //no such file: "Gl/gl.h", <=2.07
scons BUILD="release" BUILD_GAMEPAK="1" MACOSX_TARGET_ARCH="i386"
  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


=== Compiling for PPC architecture ===
Now run CMake as instructed above.
To start compiling, enter the following command in the folder you extracted the TDM sources to:
scons BUILD="release" BUILD_GAMEPAK="1" MACOSX_TARGET_ARCH="ppc"


=== Compiling a universal binary ===
=== Ubuntu 16.04: 32-bit version on 64-bit OS ===
I've been using the following script to generate a universal binary. This script assumes that there are two separate TDM source folders, one in <tt>darkmod_src.i386</tt> and one in <tt>darkmod_src.ppc</tt>.
Note: they are actual copies of the same TDM source package, I just used that as convenience such that I don't have to recompile the whole source tree after minor changes.


cd /Users/greebo
If you have 64-bit Linux, you can also build and run 32-bit TDM.
cd darkmod_src.i386
Note that this approach is slightly more complicated.
scons BUILD="release" BUILD_GAMEPAK="1" MACOSX_TARGET_ARCH="i386"
cd ../darkmod_src.ppc
scons BUILD="release" BUILD_GAMEPAK="1" MACOSX_TARGET_ARCH="ppc"
cd ../darkmod_src.i386
lipo -arch i386 gamei386-base.dylib -arch ppc ../darkmod_src.ppc/gameppc-base.dylib -create -output game.dylib
zip -d tdm_game03.pk4 game.dylib
zip tdm_game03.pk4 game.dylib


After this the <tt>darkmod_src.i386/tdm_game03.pk4</tt> should contain the universal binary of the TDM game lib. The PK4 is about 6 to 7 MB.
You have to install the following packages in addition to the ones listed above:


=== Installing scons ===
  sudo apt-get install g++-multilib            //no such file: 'sys/cdefs.h'
Get the scons tarball from their website, unpack it to a folder and run the following commands (note that the exact scons version might differ):
  sudo apt-get install libx11-dev:i386          //cannot find "-lX11"
cd scons-2.0.1
  sudo apt-get install libxxf86vm-dev:i386      //cannot find "-lXxf86vm"
python setup.py install
  sudo apt-get install libopenal-dev:i386      //cannot find "-lopenal"
  sudo apt-get install libxext-dev:i386        //cannot find "-lXext"


=== Building libcurl in Mac OS X ===
Then you need to call CMake with a toolchain file to target 32-bit:
Download the libcurl 7.21 source package, and extract it on your system. To produce a so-called "fat" binary you need to compile for both i386 and ppc targets.


Build the i386 target by entering:
  cmake -DCMAKE_BUILD_TYPE="Release" -DCMAKE_TOOLCHAIN_FILE="../sys/cmake/gcc_32bit.cmake" ..


env CFLAGS="-m32 -arch i386" LDFLAGS="-m32 -arch i386" ./configure --disable-ldap --build=i686-unknown-linux-gnu --without-libidn --without-zlib --without-ssl
The 64-bit and 32-bit versions can be built independently on a single 64-bit Linux, but you need to use different
make
build directories for each version.
sudo make install


After make install the static library can be found in <tt>/usr/local/lib/libcurl.a</tt>, copy that file to your curl folder and rename it to <tt>./libcurl.i386.a</tt>
=== Other distros ===


Build the powerpc target by entering:
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.


env CFLAGS="-m32 -arch ppc" LDFLAGS="-m32 -arch ppc" ./configure --disable-ldap --build=powerpc-unknown-linux-gnu --without-libidn --without-zlib --without-ssl
E.g. for Kali Linux
make
sudo make install


After make install the static library can be found in <tt>/usr/local/lib/libcurl.a</tt>, copy that file to your curl folder and rename it to <tt>./libcurl.ppc.a</tt>
  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


Finally call lipo to combine these two into a fat binary by entering this in your curl folder.
== I have a bugfix for the team ==


lipo -arch i386 libcurl.i386.a -arch ppc libcurl.ppc.a -create -output libcurl.a
The filesize of the newly created <tt>libcurl.a</tt> should be around the sum of the single ppc and i386 libs, you can double-check that. Copy the <tt>libcurl.a</tt> into your <tt>darkmod_src/macosx/libcurl/</tt> and you're done with this step.
=== Building Boost static libs in Mac OS X ===
Download the boost 1.45 sources and extract them to your hard drive. Create a jam user config file to use the g++ 4.0 compiler instead of the default gcc 4.2 in Leopard: create a new file in your boost root folder and name it <tt>user-config-darwin.jam</tt>:
using darwin : 8.11 : /usr/bin/g++-4.0 :
    <architecture>"combined"
    <address-model>"32"
    <macosx-version>"10.4"
    <macosx-version-min>"10.4"
    <link>"static"
    <threading>"multi" ;
Download a bjam binary for OS X to your machine, then build boost threads, filesystem and system:
/path/to/bjam --user-config=../../../user-config-darwin.jam architecture=combined link=static threading=multi address-model=32 release [stage]
The "stage" option only works in filesystem and system (not in thread, as of boost 1.45). You'll find the filesystem and system libs in the <tt>./stage</tt> folder of your boost root, the <tt>libboost_thread.a</tt> will be located in the <tt>bin.v2</tt> folder after compilation.
Copy all libboost*.a files to <tt>darkmod_src/macosx/boost/lib/</tt>.
== 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.
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.


== Additional Info about the TDM Code ==
See also [[Reporting Problem]] article.
The Dark Mod codebase is quite large in the meantime and we have reorganised and refactored/replaced a number of things. There are a few things which haven't changed too much (like the animation code), but most gameplay code has been altered to fit TDM's needs.
 
Additionally, the TDM code relies on a few static libraries which are not required in the vanilla D3 code, see below.
 
=== Boost Libraries ===
TDM's code is using [http://www.boost.org boost] libraries. Most boost libraries we're using are header-only (i.e. they work without special linking), with the exception of filesystem, system, threads, program_options etc. The latter ones require a static library to be built for your OS and linked into the game code. For Windows the TDM source package you downloaded already contains the correct binaries for VC++ 2005 (7-zipped), VC++ 2008 and VC++ 2010 in both release and debug flavours. They can be found in the win32\lib folder.
 
=== ZipLoader ===
For the FM installation code, we made use of the minizip/zlib sources. For Windows and Linux the package already comes with the correct static .lib and .a files, so this should work out of the box. In case you need to compile these libraries from scratch (e.g. for a newer compiler or a different OS) there is a .vcproj file available in win32\ziploader (Windows) or a sconscript in <tt>sys/scons/Sconscript.ziploader</tt>. Use these to compile a new static library and make sure the library is referenced by the d3game project.
 
=== DevIL ===
Our lightgem code makes use of some image processing routines, which are contained in the open source DevIL package. The correct static library is already contained in the source package you downloaded, hence it should work right out of the box. In case you need to compile that library from scratch (applies to Windows only, Linux users will just need to download the correct package from their repositories), there are the DevIL sources in win32/devil, including a vcproj file, which you can use as basis.
 
== TDMLauncher ==
The Dark Mod comes with a custom launching app named tdmlauncher which makes mission installation/uninstallation easier for players. The source code for the tdmlauncher is contained in the source package linked above, head to the folder dmlauncher/ where you'll find a Visual Studio solution file as well as a sconscript.tdmlauncher. TDMLauncher is making use of boost::filesystem, that's why there is a separate lib/ folder in there as well (for Linux only). See above for info about the boost libraries.
 
== How to compile the boost static libraries in Windows ==
See also the main article: [[Compile the static Boost Libraries in Windows]]


Any VC++ compiler version '''other than VC++ 2008 or VC++ 2010''' will require a recompile of the boost static libraries which The Dark Mod links against. At the time of writing, TDM is using the following boost libraries:
== Working in SVN ==
* boost.filesystem
* boost.system
* boost.thread
* boost.date_time
* boost.program_options (for the updater/packager)


Now take the *.lib files and copy them into your '''win32/lib''' folder in your source directory and the linking should succeed.
If you work directly with [https://svn.thedarkmod.com/svn/darkmod_src/trunk SVN], make sure that [http://svnbook.red-bean.com/en/1.7/svn.ref.svnversion.re.html 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.


Note for VC++ 2005 users: the boost libraries needed to link the game library are shipped in the darkmod source package in compressed format in ''win32/libs/libboost_binaries_vc++2005.7z''. Unpack that archive if you need them.


[[Category:Tutorial]]
[[Category:Tutorial]]
[[Category:Coding]]
[[Category:Coding]]

Latest revision as of 01:53, 11 June 2024

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.

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:

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\darkmod       <-- your darkmod installation
C:\Games\darkmod_src   <-- your source folder (containing the solution)

This directory structure is recommended for both Windows and Linux.

For windows users (this may also apply to linux users) - Install tortoise SVN and then right click on the \darkmod_src folder and select checkout. Then in the url field put 'https://svn.thedarkmod.com/publicsvn/darkmod_src/trunk/' then click ok (see screenshot below)

Windows

Since TDM 2.11 you'll need Visual Studio 2022 to compile the project (VS2017 was used before that). 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).

You'll find a TheDarkMod.sln solution file 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.14 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.

If you need to force a specific GCC version because your Linux distro does not support GCC 5 but you've installed a newer GCC you may add flags to the cmake invoke: 

 cmake -DCMAKE_BUILD_TYPE="Release" .. -DGAME_DIR=/home/user/darkmod -DCMAKE_C_COMPILER=gcc-11 -DCMAKE_CXX_COMPILER=g++-11

( Replace gcc-11 g++-11 with whichever GCC version you intend to use. )

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.

Retrieved from "https://wiki.thedarkmod.com/index.php?title=The_Dark_Mod_-_Compilation_Guide&oldid=33353"