1# Installing D1X-Rebirth and D2X-Rebirth
2## Building
3
4D1X-Rebirth and D2X-Rebirth (generically DXX-Rebirth) are built by an SConstruct script.  DXX-Rebirth runs on Windows (XP and later), Linux (x86 and amd64), recent Mac OS X, and Raspberry Pi.  Other targets may also work, but are not tracked by the core team.  If you maintain a working target not listed here, please file an issue to have it included in this list.
5
6The DXX-Rebirth maintainers have no control over the sites linked below.  The maintainers are not responsible for the safety or correct operation of the prerequisites listed below.  Unless specified otherwise, the maintainers of DXX-Rebirth have not verified that the links are current, safe, or produce a working environment.
7
8### Prerequisites
9
10* [Python 3.x](https://www.python.org/) to run [scons](https://www.scons.org/), the processor for SConstruct scripts.
11[Python 3.6](https://www.python.org/downloads/release/python-3610/) is recommended.
12* C++ compiler with support for selected C++11 features.  One of:
13    * [gcc](https://gcc.gnu.org/) 7.5
14    * [clang](https://clang.llvm.org/) 9.0 or later
15    * Microsoft Visual Studio is **not** supported at this time.
16	  Support for Microsoft Visual Studio will be added when it
17	  implements sufficient C++17 features for the code to build with
18	  few or no modifications.
19* [SDL 1.2](https://www.libsdl.org/).
20SDL 2 is also supported, and will become the default soon.
21* [PhysicsFS](https://icculus.org/physfs/).
22PhysFS 3.x or later is required.
23
24Optional, but recommended:
25
26* [SDL\_image 1.2](https://www.libsdl.org/projects/SDL_image/).
27* [SDL\_mixer 1.2](https://www.libsdl.org/projects/SDL_mixer/).
28* [libpng](http://www.libpng.org/).
29* C++ compiler with support for selected C++14 features.  One of:
30    * [gcc](https://gcc.gnu.org/) 9.2.0 or later
31    * [clang](https://clang.llvm.org/) 9.0 or later
32
33Unless otherwise noted, using the newest release available is recommended.  For example, prefer gcc-9.3 to gcc-7.5, even though both should work.
34
35DXX-Rebirth can be built on one system to run on a different system, such as using Linux to build for Windows (a "cross-compiled build").  The sections below specify where to get prerequisites for a build meant to run on the system where it is built (a "native build").
36
37For each prerequisite, its development headers (files ending in **.h**) and its libraries (ending in **.so** for Linux, **.dylib** for Mac OS X, and **.dll** for Windows) must be found by the compiler.  You can do this by placing these files in an existing directory which the compiler will search, or by placing these files in a directory which you instruct the compiler to search.
38
39In general, avoid installing prerequisites to paths which contain embedded spaces.  Although Rebirth quotes paths to handle this, some prerequisites may use `pkg-config` files that do not handle embedded spaces well.
40
41#### Placing files in a directory which you instruct the compiler to search (preferred)
42
43If you choose to install the headers and/or libraries in a new path, you must instruct the build system to search that path.  To do this for development headers, add to the scons command line **"CPPFLAGS=-isystem** _/absolute/path/to/header/directory_**"**.  To do this for libraries, add to the scons command line **"LINKFLAGS=-L** _/absolute/path/to/library/directory_**"**.
44
45#### Adding files to an existing directory which the compiler will search
46
47To find these paths for gcc:
48* Get the compiler's header search path by running **gcc -Wp,-v -S -x c++ /dev/null** and looking at the lines under the label **#include <...> search starts here:**.  Any of these lines will work.  The paths _without_ a compiler version number in them are preferable.  Windows users may need to write **gcc -Wp,-v -S -x c++ nul** instead, due to Windows using a different name for the null device.
49* Get the compiler's library search path by running **gcc -print-search-dirs** and looking at the line labeled **libraries:**.  This line is a list of directories that will be searched.  Any of the directories will work.  Again, prefer directories that are do not have a compile version number in them.
50
51#### Windows
52Where possible, Windows users should try to obtain a compiled package, rather than locally compiling from source.  To build from source, read on.
53
54If you are not sure whether your system is Windows x86 or Windows x64, use the packages for Windows x86.  Systems running Windows x64 support running Windows x86 programs, but Windows x86 systems do not run Windows x64 programs.
55
56* [Python x86 installer](https://www.python.org/ftp/python/3.6.7/python-3.6.7.exe) |
57[Python x64 installer](https://www.python.org/ftp/python/3.6.7/python-3.6.7-amd64.exe)
58* [SCons](http://prdownloads.sourceforge.net/scons/scons-3.1.1.zip)
59* C++ compiler
60    * mingw-gcc: [Getting Started](http://www.mingw.org/wiki/Getting_Started) |
61	[Direct download](https://sourceforge.net/projects/mingw/files/latest/download)
62* [SDL 1.2 x86 zip](https://www.libsdl.org/release/SDL-1.2.15-win32.zip) |
63[SDL 1.2 x64 zip](https://www.libsdl.org/release/SDL-1.2.15-win32-x64.zip)
64* No published PhysFS package for Windows is known.
65You must [build it](https://hg.icculus.org/icculus/physfs/raw-file/bf155bd2127b/INSTALL.txt)
66from [source](https://icculus.org/physfs/downloads/physfs-3.0.2.tar.bz2).
67You may be able avoid building from source by copying PhysFS DLLs from a
68previous Rebirth release and installing current PhysFS headers.
69However, building from source is recommended to ensure a consistent
70environment.
71
72#### MSYS2/mingw-w64 (Windows alternate method)
73* `pacman -S git ${MINGW_PACKAGE_PREFIX}-{gcc,pkgconf,scons,SDL,SDL_image,SDL_mixer,libpng,physfs}`
74
75#### Linux
76Install the listed prerequisites through your system package manager.
77* Arch PKGBUILD files are in `contrib/arch/`
78* An RPM spec file is in `contrib/rpm/`
79* Gentoo ebuild files are in `contrib/gentoo/`
80
81##### Arch
82* **pacman -S
83 base-devel
84 scons
85 sdl
86 sdl\_image
87 sdl\_mixer
88 physfs**
89
90##### Fedora
91* **yum install
92 gcc-c++
93 scons
94 SDL-devel
95 SDL\_image-devel
96 SDL\_mixer-devel
97 physfs-devel**
98
99##### Gentoo
100* **emerge --ask --verbose --noreplace
101 dev-util/scons
102 media-libs/libsdl
103 media-libs/sdl-image
104 media-libs/sdl-mixer
105 dev-games/physfs**
106
107##### Ubuntu
108* **apt-get install
109 build-essential
110 scons
111 libsdl1.2-dev
112 libsdl-image1.2-dev
113 libsdl-mixer1.2-dev
114 libphysfs-dev**
115
116#### Mac OS X
117Where possible, Mac users should try to obtain a compiled package, rather than locally compiling from source.  To build from source, read on.
118
119Install the listed prerequisites through your preferred package manager.
120
121PhysicsFS must be installed as a separate dynamic library.  It is not supported as an OS X Framework.  The required files will be installed into the correct locations by the PhysicsFS installer; refer to the relevant instructions.
122
123The Mac OS X Command Line Tools are required.  Install them by running
124
125    xcode-select --install
126
127from the Terminal.  This may need to be done after each major OS upgrade as well.
128
129DXX-Rebirth can be built from the Terminal (via SCons) without Xcode; to build using Xcode requires Xcode to be installed.
130
131##### [Homebrew](https://github.com/Homebrew/homebrew/)
132* **brew install
133 scons
134 sdl
135 sdl\_image
136 sdl\_mixer
137 physfs
138 libpng
139 pkg-config
140 dylibbundler**
141
142### Building
143Once prerequisites are installed, run **scons** *options* to build.  By default, both D1X-Rebirth and D2X-Rebirth are built.  To build only D1X-Rebirth, run **scons d1x=1**.  To build only D2X-Rebirth, run **scons d2x=1**.
144
145If unspecified, **SConstruct** uses $CXX for the compiler, $CPPFLAGS for preprocessor options, $CXXFLAGS for C++ compiler options, and $LDFLAGS for linker options.  You may override any or all of these choices by setting options of the corresponding name: **scons CXX=/opt/my/c++ 'CXXFLAGS=-O0 -ggdb'**.  **SConstruct** supports numerous options for adjusting build details.  Run **scons -h** to see them.  Option names are case sensitive.  Commonly used options include:
146
147* **CXX=**_path_ - path to C++ compiler
148* **CPPFLAGS='**_flags_**'** - flags for C preprocessor
149* **CXXFLAGS='**_flags_**'** - flags for C++ compiler
150* **LDFLAGS='**_flags_**'** - flags for linker
151* **lto=1** - enable Link Time Optimization
152* **sdlmixer=1** - enable support for SDL\_mixer
153* **builddir=**_path_ - set directory for build outputs; defaults to "."
154* **builddir\_prefix=**_path_ - Developer option; set builddir to builddir\_prefix plus a path derived from build options.
155Use this to build multiple targets without picking specific paths for each one.
156The generated path is stable across multiple runs with the same options.
157Packaging scripts should use **builddir** with manually chosen directories.
158* **verbosebuild=1** - show commands executed instead of short descriptions of the commands
159* **prefix=**_path_ - (Linux only); equivalent to **--prefix** in Autoconf
160* **sharepath=**_path_ - (Linux only); sets system directory to search for game data
161
162The build system supports building multiple targets in parallel.  This is primarily useful for developers, but can also be used by packagers to create secondary builds with different features enabled.  To use it, run **scons** *game*=*profile[,profile...]*.  **SConstruct** will search each profile for the known options.  The first match wins.  For example:
163
164        scons dxx=gcc8,e, d2x=gcc7,sdl2, \
165            gcc7_CXX=/path/to/gcc-7 \
166            gcc8_CXX=/path/to/gcc-8 \
167            e_editor=1 sdl2_sdl2=1
168
169This tells **SConstruct** to build both games (**dxx**) with the profiles **gcc8**, **e**, *empty* and also to build D2X-Rebirth (**d2x**) with the profiles **gcc7**, **sdl2**, *empty*.  Profiles **gcc7** and **gcc8** define private values for **CXX**, so the default value of **CXX** is ignored.  Profile **e** enables the **editor** option, which builds features used by players who want to create their own levels.  Profile **sdl2** sets the **sdl2** option to true, which produces a build that uses libSDL2 instead of libSDL.  Profile *empty* is the default namespace, so CPPFLAGS, CXXFLAGS, etc. are found when it is searched.  Since these values were not assigned, they are drawn from the corresponding environment variables.
170
171The build system supports specifying a group of closely related targets.  This is mostly redundant on shells with brace expansion support, but can be easier to type.  For example:
172
173        scons builddir_prefix=build/ \
174			dxx=gcc8+gcc9,prof1,prof2,prof3,
175
176This is equivalent to the shell brace expansion:
177
178        scons builddir_prefix=build/ \
179			dxx={gcc8,gcc9},prof1,prof2,prof3,
180
181or
182
183        scons builddir_prefix=build/ \
184			dxx=gcc8,prof1,prof2,prof3, \
185			dxx=gcc9,prof1,prof2,prof3,
186
187Profile addition can be stacked: **scons dxx=a+b,c+d,e+f** is equivalent to **scons dxx=a,c,e dxx=a,d,e dxx=b,c,e dxx=b,d,e dxx=a,c,f dxx=a,d,f dxx=b,c,f dxx=b,d,f**.
188
189#### Configuration
190**SConstruct** runs tests to check for common problems and available functionality.  **SConstruct** will automatically enable available compiler features.  **SConstruct** will not automatically enable optional features which require an external library.  If the feature is enabled, either by default or by the provided options, and the library is present, it will be used.  If the feature is enabled, and the library is absent, the build fails.  If the feature is disabled, either by default or by the provided options, the library check is skipped and the feature is not used.
191
192If required functionality is missing, **SConstruct** will stop the build and print a diagnostic message.  A stop at this stage indicates an environment problem.  If any target fails to configure, no target will be built.
193
194Before reporting an issue, clear any applicable caches (**ccache -C**; **rm .sconsign.dblite**) and reproduce the failure.  The DXX-Rebirth maintainers may be able to help you resolve environment problems if you cannot solve them on your own.  If you need help, please post the full output of running **scons** and the contents of **sconf.log** from your build directory.
195
196#### Compiling
197After **SConstruct** finishes the configure tests, **scons** will compile and link the program.  Failures at this stage may indicate a bug that should be reported.  Broken environments are usually caught by **SConstruct** checks before the build began.  If the compilation succeeds, the output files will be found in game-specific directories.  If the profile specified editor features, then **-editor** is appended to the filename.
198
199The output path can be overridden with the **SConstruct** option **program\_name**.  If **program\_name** is set, it overrides the game directory prefix and the optional **-editor** modification.  It does not override the output suffix (**.exe** for Windows, *empty* for Linux).
200
201Windows output with **program\_name** unset:
202
203* *build-directory*/d1x-rebirth/d1x-rebirth*[-editor]*.exe
204* *build-directory*/d2x-rebirth/d2x-rebirth*[-editor]*.exe
205
206Windows output with **d1x=1 program\_name**=**d1x-local**:
207
208* *build-directory*/d1x-local.exe
209
210Linux output with **program\_name** unset:
211
212* *build-directory*/d1x-rebirth/d1x-rebirth*[-editor]*
213* *build-directory*/d2x-rebirth/d2x-rebirth*[-editor]*
214
215##### Compiling with MSYS2
216MSYS2 offers its users three terminal environments: msys2, for building with POSIX compatibility (linking to runtime `/usr/bin/msys-2.0.dll`); and mingw32 and mingw64, for building portable native Windows apps (linking to `C:\WINDOWS\System32\msvcrt.dll`), on i686 and x86_64 respectively.
217* Install [MSYS2](https://www.msys2.org), following the directions on the main page.
218* In either a mingw32 or mingw64 (not msys2) terminal:
219
220      pacman -Syuu  # update MSYS2, as needed
221      pacman -S --needed git ${MINGW_PACKAGE_PREFIX}-{gcc,pkgconf,scons,SDL,SDL_image,SDL_mixer,libpng,physfs}
222        #  ^ substitute SDL2 for SDL if desired
223      git clone https://github.com/dxx-rebirth/dxx-rebirth.git
224      cd dxx-rebirth
225      scons
226        # Or (for example) to build d1x only, with SDL 2, with lower process priority, on all cores:
227      time nice scons -j$(nproc) sdl2=1 d1x=1
228
229* A locally built executable will run anywhere if it's invoked from inside the appropriate mingw32 or mingw64 terminal. To run it instead directly in Windows, either:
230    1. The linked mingw-w64 libraries will need to be added to PATH (See [contrib/msys2](contrib/msys2) for working example batch files); or
231    2. Dependency DLLs from MSYS2 will need to be copied to the same directory as the executable.
232
233#### Installing
234For Windows and Linux, DXX-Rebirth installs only the main game binary.  The binary can be run from anywhere and can be installed by copying the game binary.  The game does not inspect the name of its binary.  You may rename the output after compilation without affecting the game.
235
236As a convenience, if **register\_install\_target=True**, **SConstruct** registers a pseudo-target named **install** which copies the compiled files to *DESTDIR*__/__*BINDIR*.  By default, **register\_install\_target=True**, *DESTDIR* is *empty*, and *BINDIR* is *PREFIX*__/bin__, which expands to **/usr/local/bin**.
237
238DXX-Rebirth [requires game data](https://www.dxx-rebirth.com/game-content/) to play.  The build system has no support for interacting with game data.  You can get [Descent 1 PC shareware data](https://www.dxx-rebirth.com/download/dxx/content/descent-pc-shareware.zip) and [Descent 2 PC demo data](https://www.dxx-rebirth.com/download/dxx/content/descent2-pc-demo.zip) from the DXX-Rebirth website.  Full game data is supported (and recommended), but is not freely available.  You can [buy full Descent 1 game data](https://www.gog.com/game/descent) and/or [buy full Descent 2 game data](https://www.gog.com/game/descent_2) from GOG.com.  Historically, both Descent 1 and Descent 2 were sold as a single unit.  After a nearly two-year hiatus from sale, the games returned to GOG.com in November 2017 as separate units.  DXX-Rebirth contains engines for both games.  Each engine works for its respective game without the data from the other, so players who wish to purchase only one game may do so.
239