docs/building.md
DevilutionX provides a source package with the release (devilutionx-src.tar.xz) that contains
all the dependencies that must be vendored, the version information, and devilutionx.mpq.
This is the version most appropriate for packaging DevilutionX for Linux distributions.
For other use cases, use the git repository.
Note that pkg-config is an optional dependency for finding libsodium, although we have a fallback if necessary.
sudo apt-get install cmake g++ libsdl2-dev libsodium-dev libpng-dev libbz2-dev libgtest-dev libgmock-dev libbenchmark-dev libsdl2-image-dev libfmt-dev
sudo apt-get install gettext poedit
sudo apt-get install smpq
sudo dnf install cmake gcc-c++ glibc-devel libstdc++-static SDL2-devel SDL2_image-devel libsodium-devel libpng-devel bzip2-devel gmock-devel gtest-devel google-benchmark-devel libasan libubsan fmt-devel
cmake -S. -Bbuild -DCMAKE_BUILD_TYPE=Release
cmake --build build -j $(getconf _NPROCESSORS_ONLN)
First, set up the dependencies for cross-compilation:
Packaging/nix/debian-cross-aarch64-prep.sh
Then, build DevilutionX using the cross-compilation CMake toolchain file:
cmake -S. -Bbuild-aarch64-rel \
-DCMAKE_TOOLCHAIN_FILE=../CMake/platforms/aarch64-linux-gnu.toolchain.cmake \
-DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=/usr -DCPACK=ON \
-DDEVILUTIONX_SYSTEM_LIBFMT=OFF
cmake --build build-aarch64-rel -j $(getconf _NPROCESSORS_ONLN) --target package
Make sure you have Homebrew installed, then run:
brew bundle install
cmake -S. -Bbuild -DCMAKE_BUILD_TYPE=Release
cmake --build build -j $(sysctl -n hw.physicalcpu)
Make sure you have Homebrew installed, then run:
brew install cmake
cmake -S. -Bbuild -DCMAKE_TOOLCHAIN_FILE=../CMake/Platforms/ios.toolchain.cmake -DENABLE_BITCODE=0 -DPLATFORM=OS64
cmake --build build -j $(sysctl -n hw.physicalcpu) --config Release
cd build
rm -rf Payload
mkdir -p Payload
mv devilutionx.app Payload
zip -r devilutionx.ipa Payload
For testing with the Simulator instead run the following:
cmake -S. -Bbuild -G Xcode -DCMAKE_TOOLCHAIN_FILE=../CMake/Platforms/ios.toolchain.cmake -DPLATFORM=SIMULATOR64
Then open the generated Xcode project and run things from there.
</details> <details><summary>FreeBSD</summary>pkg install cmake sdl2 libsodium libpng bzip2 googletest
cmake -S. -Bbuild -DCMAKE_BUILD_TYPE=Release
cmake --build build -j $(sysctl -n hw.ncpu)
pkgin install cmake SDL2 libsodium libpng bzip2 googletest
cmake -S. -Bbuild -DCMAKE_BUILD_TYPE=Release
cmake --build build -j $(sysctl -n hw.ncpu)
pkg_add cmake sdl2 libsodium png bzip2 gmake gtest
cmake -S. -Bbuild -DCMAKE_MAKE_PROGRAM=gmake -DCMAKE_BUILD_TYPE=Release
cmake --build build -j $(sysctl -n hw.ncpuonline)
Note: We currently recommend using Ubuntu 24.04 for the MinGW build. The following instructions will install the recommended version of Ubuntu on WSL.
If you are building on Windows and do not have WSL already setup this will install WSL and Ubuntu (Requires Windows 10 2004 or higher or Windows 11)
In an Administrator Command Prompt or Powershell
wsl --install -d Ubuntu-24.04
Reboot
Wait for Command Prompt to pop up and say installing when complete enter your new Linux password
You can launch WSL anytime by typing wsl or ubuntu in a Command Prompt or Powershell or in the Start Menu launch the Ubuntu App
In a WSL terminal run these commands to get the source code for DevilutionX
sudo apt-get install git
git clone https://github.com/diasurgical/devilutionx
cd devilutionx
# Install MinGW build tools
sudo apt-get update
sudo apt-get install cmake git libz-mingw-w64-dev mingw-w64 mingw-w64-tools smpq wget
The 32-bit build depends on the 32-bit MinGW Development Libraries for SDL2 and libsodium as well as headers for zlib. These dependencies will need to be placed in the appropriate subfolders under /usr/i686-w64-mingw32.
When linking zlib, libpng will always prefer dynamically linking with libz.dll.a if it can be found. We recommend renaming or deleting libz.dll.a to force libpng to use static linkage. This will prevent errors about missing dlls when you attempt to run the game.
These can be done automatically by running Packaging/windows/mingw-prep.sh.
Note: If your i686-w64-mingw32 directory is not in /usr (e.g. when on
Debian), the mingw-prep scripts and the CMake command won't work. You need
adjust the mingw-prep scripts and pass -DCROSS_PREFIX=/path to CMake to set
the path to the parent of the i686-w64-mingw32 directory.
# Download the 32-bit development libraries for SDL2 and libsodium
# as well as the headers for zlib and place them in subfolders under
# /usr/i686-w64-mingw32
Packaging/windows/mingw-prep.sh
By compiling the package target, the build will produce the devilutionx.zip archive which should contain all the dlls necessary to run the game. If you encounter any errors suggesting a dll is missing, try extracting the dlls from the zip archive.
# Configure the project to disable unit tests,
# statically link bzip2 and libsodium,
# and enable Discord integration
cmake -S. -Bbuild -DCMAKE_TOOLCHAIN_FILE=../CMake/platforms/mingwcc.toolchain.cmake \
-DCMAKE_BUILD_TYPE=Release -DBUILD_TESTING=OFF -DDEVILUTIONX_SYSTEM_BZIP2=OFF \
-DDEVILUTIONX_STATIC_LIBSODIUM=ON -DDISCORD_INTEGRATION=ON
# Build the "package" target which produces devilutionx.zip
# containing all the necessary dlls to run the game
cmake --build build -j $(getconf _NPROCESSORS_ONLN) --target package
The 64-bit build depends on the 64-bit MinGW Development Libraries of SDL2 and libsodium as well as headers for zlib. These dependencies will need to be placed in the appropriate subfolders under /usr/x86_64-w64-mingw32.
When linking zlib, libpng will always prefer dynamically linking with libz.dll.a if it can be found. We recommend renaming or deleting libz.dll.a to force libpng to use static linkage. This will prevent errors about missing dlls when you attempt to run the game.
These can be done automatically by running Packaging/windows/mingw-prep64.sh.
Note: If your x86_64-w64-mingw32 directory is not in /usr (e.g. when
on Debian), the mingw-prep scripts and the CMake command won't work. You need
adjust the mingw-prep scripts and pass -DCROSS_PREFIX=/path to CMake to set
the path to the parent of the x86_64-w64-mingw32 directory.
# Download the 64-bit development libraries for SDL2 and libsodium
# as well as the headers for zlib and place them in subfolders under
# /usr/x86_64-w64-mingw32
Packaging/windows/mingw-prep64.sh
# Configure the project to disable unit tests,
# statically link bzip2 and libsodium,
# and enable Discord integration
cmake -S. -Bbuild -DCMAKE_TOOLCHAIN_FILE=../CMake/platforms/mingwcc64.toolchain.cmake \
-DCMAKE_BUILD_TYPE=Release -DBUILD_TESTING=OFF -DDEVILUTIONX_SYSTEM_BZIP2=OFF \
-DDEVILUTIONX_STATIC_LIBSODIUM=ON -DDISCORD_INTEGRATION=ON
# Build the "package" target which produces devilutionx.zip
# containing all the necessary dlls to run the game
cmake --build build -j $(getconf _NPROCESSORS_ONLN) --target package
Make sure to install the workload Desktop development with C++ and the individual components C++ CMake tools for Windows and Windows SDK for Visual Studio.
Note: Windows SDK component should match your Windows build version.
Install Git for Windows
Run the following commands in Command Prompt or Powershell
git clone https://github.com/microsoft/vcpkg
cd vcpkg
bootstrap-vcpkg.bat
vcpkg integrate install
If you need additional instructions for vcpkg you can find the documentation here.
In order to build devilutionx.mpq, install smpq from https://launchpad.net/smpq/trunk/1.7/+download/SMPQ-1.7-x86_64.exe. The location of this tool will need to be added to the system's PATH environment variable.
File -> Open -> CMake, select CMakeLists.txt from the project root.x64-Release configuration (or x86 for 32 bit builds, -Debug for debug builds).Build devilution.exe from the Build menu.WSL-GCC-x64-Debug configuration.Build devilution from the Build menu.Where is the source code: field.Where to build the binaries: field. If you want to place them inside source directory it's preferable to do so inside directory called build to avoid the binaries being added to the source tree.Win32 in Optional Platform for Generator, otherwise it will default to x64 build.vcpkg select Specify toolchain file for cross-compiling and select the file scripts/buildsystems/vcpkg.cmake from vcpkg directory otherwise just go with Use default native compilers.Generate and open produced .sln file using Visual Studio.Install Android Studio After first launch configuration, go to "Configure -> SDK Manager -> SDK Tools". Select "NDK (Side by side)" and "CMake" checkboxes and click "OK".
Click "Open Existing Project" and choose "android-project" folder in DevilutionX root folder.
Wait until Gradle sync is completed.
In Android Studio, go to "Build -> Make Project" or use the shortcut Ctrl+F9
You can find the compiled APK in /android-project/app/build/outputs/apk/
https://devkitpro.org/wiki/Getting_Started
Install (dkp-)pacman: https://devkitpro.org/wiki/devkitPro_pacman
Install required packages with (dkp-)pacman:
sudo (dkp-)pacman -S --needed - < Packaging/switch/packages.txt
sudo apt install smpq or yum install smpq), on windows you can
download the latest version from Launchpad.net, and unix based OSes can build
from source using tools/build_and_install_smpq.shcmake -S. -Bbuild -DCMAKE_TOOLCHAIN_FILE=/opt/devkitpro/cmake/Switch.cmake -DCMAKE_BUILD_TYPE=Release -DBUILD_ASSETS_MPQ=ON
cmake --build build -j $(getconf _NPROCESSORS_ONLN)
The nro-file will be generated in the build folder. Test with an emulator (RyuJinx) or real hardware.
</details> <details><summary>Nintendo 3DS</summary>https://devkitpro.org/wiki/Getting_Started
Install (dkp-)pacman: https://devkitpro.org/wiki/devkitPro_pacman
Install required packages with (dkp-)pacman:
sudo (dkp-)pacman -S \
devkitARM general-tools 3dstools libctru \
citro3d 3ds-sdl 3ds-libpng 3ds-bzip2 \
3ds-cmake 3ds-pkg-config picasso 3dslink
/opt/devkitpro/tools/bin/If you are compiling using MSYS2, you will need to run export MSYS2_ARG_CONV_EXCL=-D before compiling.
Otherwise, MSYS will sanitize file paths in compiler flags which will likely lead to errors in the build.
cmake -S. -Bbuild -DCMAKE_TOOLCHAIN_FILE=/opt/devkitpro/cmake/3DS.cmake -DCMAKE_BUILD_TYPE=Release
cmake --build build -j $(getconf _NPROCESSORS_ONLN)
The output files will be generated in the build folder.
</details> <details><summary>PlayStation Vita</summary>cmake -S. -Bbuild -DCMAKE_TOOLCHAIN_FILE=${VITASDK}/share/vita.toolchain.cmake -DCMAKE_BUILD_TYPE=Release
cmake --build build
pkgman install cmake_x86 devel:libsdl2_x86 devel:libsodium_x86 devel:libpng_x86 devel:bzip2_x86
pkgman install cmake libsdl2_devel libsodium_devel libpng16_devel bzip2_devel gtest_devel gettext getconf
setarch x86 # Switch to secondary compiler toolchain (GCC8+)
cmake -S. -Bbuild -DCMAKE_BUILD_TYPE=Release
cmake --build build -j $(getconf _NPROCESSORS_ONLN)
No setarch required, as there is no secondary toolchain on x86_64, and the primary is GCC8+
cmake -S. -Bbuild -DCMAKE_BUILD_TYPE=Release
cmake --build build -j $(getconf _NPROCESSORS_ONLN)
DevilutionX uses buildroot-based toolchains to build packages for OpenDingux and RetroFW.
For OpenDingux / RetroFW builds, mksquashfs needs to be installed on your machine.
To build, run the following command:
TOOLCHAIN=<path/to/toolchain> Packaging/OpenDingux/build.sh <platform>
Replace <platform> with one of: lepus, retrofw, rg99, rg350, or gkd350h.
For example:
TOOLCHAIN=/opt/gcw0-toolchain Packaging/OpenDingux/build.sh rg350
You can download the prebuilt toolchains for x86_64 hosts here:
Remember to run ./relocate-sdk.sh in the toolchain directory after unpacking it.
Alternatively, if you do not set TOOLCHAIN, the script will
download and compile a partial buildroot toolchain for you
(stored at $HOME/buildroot-$PLATFORM-devilutionx).
This requires 8 GiB+ disk space and takes a while.
End-user manuals are available here and in the package help section.
</details> <details><summary>Clockwork PI GameShell</summary>You can either call
Packaging/cpi-gamesh/build.sh
to install dependencies and build the code.
Or you create a new directory under /home/cpi/apps/Menu and copy the file there. After restarting the UI, you can download and compile the game directly from the device itself. See the readme for more details.
docker build -f Packaging/amiga/Dockerfile -t devilutionx-amiga .
docker run -u "$(id -u "$USER"):$(id -g "$USER")" --rm -v "${PWD}:/work" devilutionx-amiga
The command above builds DevilutionX in release mode. For other build options, you can run the container interactively:
docker run -u "$(id -u "$USER"):$(id -g "$USER")" -ti --rm -v "${PWD}:/work" devilutionx-amiga bash
See the CMD in Packaging/amiga/Dockerfile for reference.
To actually start DevilutionX, increase the stack size to 50KiB in Amiga. You can do this by selecting the DevilutionX icon, then hold right mouse button and select Icons -> Information in the top menu.
</details> <details><summary>Emscripten</summary>Emscripten port is a work in progress. It builds but does not do more than that currently.
To build, install the Emscripten SDK, then run:
emcmake cmake -S. -Bbuild-em -DCMAKE_BUILD_TYPE=Release
cmake --build build-em -j $(getconf _NPROCESSORS_ONLN)
To then run it:
cd build-em
emrun index.html
Note: Visual Studio Community Edition can be used.
Add the following to the PATH:
Run:
Packaging/xbox-one/build.bat
Building for Miyoo Mini must be run from inside the Toolchain Docker image.
Executing Packaging/miyoo_mini/build.sh will create the folder build-miyoo-mini/SDROOT which has the correct structure to be used with
OnionOS Port Collection.
For macOS Tiger, DevilutionX can be compiled using the compiler and libraries from MacPorts.
For PowerPC, you can use precompiled dependencies from here:
http://macports-tiger-ppc.glebm.com/
After installing MacPorts, run:
# Some packages may require you to manually deactivate certain ports during installation.
# Remember to reactivate them after installing.
sudo port install curl curl-ca-bundle gcc14 cmake \
libsdl12 libsdl_image libsodium bzip2 zlib lua54
# Set GCC 14 as the default GCC:
sudo port select --set gcc mp-gcc14
Then, build DevilutionX:
CC=gcc cmake -S. -Bbuild-rel -DCMAKE_BUILD_TYPE=Release -DBUILD_TESTING=OFF -DCPACK=ON -DMACOSX_STANDALONE_APP_BUNDLE=ON
cmake --build build-rel -j "$(sysctl -n hw.ncpu)"
# `sudo` is required to produce a bundle with all the shared libraries.
sudo cmake --build build-rel --target package -j "$(sysctl -n hw.ncpu)"
To run tools from the tools/ directory (only needed for development), you also need Python:
sudo port install python312
sudo port select --set python python312
sudo port select --set python3 python312
You can build for DOS from Linux using DJGPP.
First, install / compile the dependencies (only needs to be done once):
Packaging/windows/dos-prep.sh
Then, build DevilutionX:
cmake -S. -Bbuild-dos -DCMAKE_TOOLCHAIN_FILE=CMake/platforms/djcpp.toolchain.cmake -DTARGET_PLATFORM="dos" \
-DCMAKE_BUILD_TYPE=Release -DBUILD_TESTING=OFF
cmake --build build-dos -j $(getconf _NPROCESSORS_ONLN)
-DCMAKE_BUILD_TYPE=Release changed build type to release and optimize for distribution.-DNONET=ON disable network support, this also removes the need for the ASIO and Sodium.-DUSE_SDL1=ON build for SDL v1 instead of v2, not all features are supported under SDL v1, notably upscaling.-DCMAKE_TOOLCHAIN_FILE=../CMake/platforms/linux_i386.toolchain..cmake generate 32bit builds on 64bit platforms (remember to use the linux32 command if on Linux).-DDEBUG=OFF disable debug mode of the Diablo engine.-DASAN=OFF disable address sanitizer.-DUBSAN=OFF disable undefined behavior sanitizer.