Skip to content

Latest commit

 

History

History
573 lines (431 loc) · 18.2 KB

BUILDING.md

File metadata and controls

573 lines (431 loc) · 18.2 KB

DETONATOR 2D

Build Instructions 👨🏼‍💻

Screenshot Screenshot Screenshot Screenshot

Getting Started 👈

Tip

The build process assumes some familiarity with building C++ based projects using toolchains and tools such as GCC, MSVS, Emscripten💩 and CMake.

Tip

You'll need to have Qt5 in order to build the Editor.

Build Steps:

  1. First build the engine and editor for your target platform.
  2. If you want to deploy / package your game for web then build the engine for HTML5/WASM
  3. If you want to work on the engine itself it's advisory to also run the (unit) tests.

Step 1) Building the Editor & Engine for Desktop Windows 🪟

Important

These build instructions are for MSVS 2019 Community Edition 64bit build.

How to install dependencies
How to build the project in RELEASE
  • Open Developer Command Prompt for VS 2019
  $ git clone https://github.com/ensisoft/detonator
  $ cd detonator
  $ git submodule update --init --recursive
  $ mkdir build
  $ cd build
  $ conan install .. --output-folder=conan --build missing
  $ cmake -G "Visual Studio 16 2019" .. -DCMAKE_BUILD_TYPE=Release  -DCMAKE_TOOLCHAIN_FILE=conan/conan_toolchain.cmake
  $ cmake --build   . --config Release
  $ cmake --install . --config Release
How to build the project in DEBUG [OPTIONAL]

Note that on MSVS the library interfaces change between debug/release build configs. (e.g. iterator debug levels). This means that in order to link to 3rd party libraries the debug versions of those libraries must be used.

  • Open Developer Command Prompt for VS 2019
  $ git clone https://github.com/ensisoft/detonator
  $ cd detonator
  $ git submodule update --init --recursive
  $ mkdir build_d
  $ cd build_d
  $ conan install .. --output-folder=conan --build missing -s build_type=Debug
  $ cmake -G "Visual Studio 16 2019" .. -DCMAKE_BUILD_TYPE=Debug -DCMAKE_TOOLCHAIN_FILE=conan/conan_toolchain.cmake
  $ cmake --build   . --config Debug
  $ cmake --install . --config Debug
How to build Qt5 designer plugin [OPTIONAL] 
  $ cd editor\gui\qt
  $ mkdir build
  $ cmake -G "Visual Studio 16 2019" -DCMAKE-BUILD_TYPE=Release
  $ cmake --build . --config Release
  $ cmake --install . --config Release

Step 1) Building the Editor & Engine for Desktop Linux 🐧

How to install dependencies

See your distro manuals for how to install the packages.

Install these packages:

  • GCC (or Clang) compiler suite
  • CMake build tool
  • Conan💩💩 package manager (VERSION 2)
    • On Archlinux you can use 'yay' to install conan + its dependencies from AUR*
    • See below for installing yay + conan💩💩
  • Git version control system
  • Qt5 application framework
How to build the project in RELEASE 
  $ git clone https://github.com/ensisoft/detonator
  $ cd detonator
  $ git submodule update --init --recursive
  $ mkdir build
  $ cd build
  $ conan install .. --output-folder=conan --build missing
  $ cmake -G "Unix Makefiles" .. -DCMAKE_BUILD_TYPE=Release -DCMAKE_TOOLCHAIN_FILE=conan/conan_toolchain.cmake
  $ make -j16 install
  $ ctest -j16
How to build the project in DEBUG [OPTIONAL] 
  $ git clone https://github.com/ensisoft/detonator
  $ cd detonator
  $ git submodule update --init --recursive
  $ mkdir build_d
  $ cd build_d
  $ conan install .. --output-folder=conan --build missing -s build_type=Debug
  $ cmake -G "Unix Makefiles" .. -DCMAKE_BUILD_TYPE=Debug -DCMAKE_TOOLCHAIN_FILE=conan/conan_toolchain.cmake
  $ make -j16 install
  $ ctest -j16
How to build the project in PROFILE [OPTIONAL]
  • Build the project for profiling using Valgrind / KCachegrind
  $ git clone https://github.com/ensisoft/detonator
  $ cd detonator
  $ git submodule update --init --recursive
  $ mkdir build_profile
  $ cd build_profile
  $ conan install .. --output-folder=conan --build missing -s build_type=RelWithDebInfo
  $ cmake -G "Unix Makefiles" .. -DCMAKE_BUILD_TYPE=RelWithDebInfo -DCMAKE_TOOLCHAIN_FILE=conan/conan_toolchain.cmake
  $ make -j16 install
  • Then in order to profile and analyze the output use the combination of valgrind and kcachegrind. For example:
  $ cd detonator/audio/test/
  $ valgrind --tool=cachegrind ./audio_test --graph
  $ kcaghegrind cachegrind.out.XXXXX
How to build with Ninja, Clang and Mold linker [OPTIONAL]
  • These are alternative instructions for build using Ninja, Clang and Mold linker.
  $ export CC=/usr/bin/clang
  $ export CXX=/usr/bin/clang++
  $ conan profile new detonator-clang --detect

  $ git clone https://github.com/ensisoft/detonator
  $ cd detonator
  $ git submodule update --init --recursive
  $ mkdir build
  $ cd build
  $ conan install .. --build missing --profile detonator-clang
  $ cmake -G "Ninja" .. -DCMAKE_BUILD_TYPE=Release -DUSE_MOLD_LINKER=ON
  $ ninja -j16 install
How to build Qt5 designer plugin [OPTIONAL] 
  $ cd detonator/editor/gui/qt
  $ mkdir build
  $ cmake -G "Unix Makefiles" .. -DCMAKE_BUILD_TYPE=Release
  $ make -j16
  $ sudo make install
Build troubleshooting 💩

When you create a Conan profile with

$ conan profile new default --detect

If Conan complains about "ERROR: invalid setting" (for example when GCC major version changes) you can try edit ~/.conan/settings.yaml. Search for the GCC versions and edit there.

Step 2) Building the Engine for HTML5/WASM 💩

Note

HTML5/WASM build is only required if you want to build and package your game for the web.
If you just want to try the editor or build native games you don't need this.


Some notes about building to HTML5/WASM.
  • Building to HTML5/WASM is currently supported only for the engine but not the editor.
  • Current Emscripten💩 version is 3.1.50. Using other version will likely break things.
  • Building to HTML5/WASM will produce the required JS and WASM files to run games in the browser,
    but you still need to build the editor in order to develop the game and package it.
  • When you package your game with the editor, the HTML5/WASM game files are copied by the editor
    during the packaging process in order to produce the final deployable game package.
How to build on Linux 🐧
  • Install Emscripten💩
  $ cd detonator
  $ git clone https://github.com/emscripten-core/emsdk.git
  $ cd emsdk
  $ git pull
  $ ./emsdk install 3.1.50
  $ ./emsdk activate 3.1.50
  $ source ./emsdk_env.sh
  • Check your Emscripten💩 installation
  $ which emcc
  $ /home/user/emsdk/upstream/emscripten/emcc
  $ emcc --version
  $ emcc (Emscripten gcc/clang-like replacement + linker emulating GNU ld) 3.1.50 (047b82506d6b471873300a5e4d1e690420b582d0)
  • Build the DETONATOR 2D engine into a WASM blob. Make sure that you have the Emscripten💩 tools in your path, i.e. you have sourced emsdk_env.sh in your current shell.
  $ git clone https://github.com/ensisoft/detonator
  $ cd detonator
  $ git submodule update --init --recursive
  $ cd emscripten
  $ mkdir build
  $ cd build
  $ emcmake cmake .. -DCMAKE_BUILD_TYPE=Release
  $ make -j16 install
How to build on Windows 🪟 
  $ cd detonator
  $ git clone https://github.com/emscripten-core/emsdk.git
  $ cd emsdk
  $ git pull
  $ emsdk.bat install 3.1.50
  $ emsdk.bat activate 3.1.50
  $ emsdk_env.bat
  • Check your Emscripten💩 and Ninja🥷 installation
  $ where emcc
  $ C:\coding\detonator\emsdk\upstream\emscripten\emcc
  $ C:\coding\detonator\emsdk\upstream\emscripten\emcc.bat
  $ emcc --version
  $ emcc (Emscripten gcc/clang-like replacement + linker emulating GNU ld) 3.1.50 (047b82506d6b471873300a5e4d1e690420b582d0)
  $ where ninja
  $ C:\coding\detonator\emsdk\ninja.exe
  $ ninja --version
  $ 1.10.2
  • Build the DETONATOR 2D engine into a WASM blob. Make sure you have emcc and Ninja in your path i.e. you have ran emsdk_env.bat in your current shell.
  $ git clone https://github.com/ensisoft/detonator
  $ cd detonator
  $ git submodule update --init --recursive
  $ cd emscripten
  $ mkdir build
  $ cd build
  $ emcmake cmake .. -DCMAKE_BUILD_TYPE=Release
  $ ninja -j16
  $ ninja -j16 install
Build troubleshooting 💩

Windows: Emscripten💩 3.0.0 build fails with

error: undefined symbol: _get_daylight (referenced by tzset_impl__deps: ['_get_daylight','_get_timezone','_get_tzname'], referenced by tzset__deps: ['tzset_impl'], referenced by localtime_r__deps: ['tzset'], referenced by __localtime_r__deps: ['localtime_r'], referenced by top-level compiled C/C++ code)
error: undefined symbol: _get_timezone (referenced by tzset_impl__deps: ['_get_daylight','_get_timezone','_get_tzname'], referenced by tzset__deps: ['tzset_impl'], referenced by localtime_r__deps: ['tzset'], referenced by __localtime_r__deps: ['localtime_r'], referenced by top-level compiled C/C++ code)
warning: __get_timezone may need to be added to EXPORTED_FUNCTIONS if it arrives from a system library
error: undefined symbol: _get_tzname (referenced by tzset_impl__deps: ['_get_daylight','_get_timezone','_get_tzname'], referenced by tzset__deps: ['tzset_impl'], referenced by localtime_r__deps: ['tzset'], referenced by __localtime_r__deps: ['localtime_r'], referenced by top-level compiled C/C++ code)
warning: __get_tzname may need to be added to EXPORTED_FUNCTIONS if it arrives from a system library
...

Build fails with

wasm-ld: error: --shared-memory is disallowed by ldo.c.o because it was not compiled with 'atomics' or 'bulk-memory' features.
  • emscripten-core/emsdk#790
  • This is trying to communicate that something was built without thread support when thread support should be enabled.
    In other words trying to mix + match translation units / libs built with different build configuration.
  • Make sure to double check the build flags including third_party/CMakeLists.txt

If your build was successful there should now be GameEngine.js, GameEngine.wasm and GameEngine.worker.js files in the editor's dist folder.

Step 2.1) Deploying the Game for the Web 💩

When you package your game for the web the editor will copy all the required files to your chosen output directory.

  • GameEngine.js
  • GameEngine.wasm
  • GameEngine.worker.js
  • FILESYSTEM
  • FILESYSTEM.js
  • game.html

These 6 files are then all the files that you need to deploy/copy over to your web server.

Tip

You can rename game.html to whatever you want, for example my-amazing-game.html. Just don't change the names of any other files

1. Configure Your Web Server

[!IMPORTANT]
You must enable the correct web policies💩 in order to enable SharedArrayBuffer💩 in order to enable threads !! 💩💩
Without SharedArrayBuffer web worker threads can't run and the engine cannot work. 💩💩
https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/SharedArrayBuffer

[!IMPORTANT]
You must set the HTTP Cross-Origin-Opener-Policy to same-origin
You must set the HTTP Cross-Origin-Embedder-Policy to require-corp
You can achieve this with a .htaccess file.

Header set Access-Control-Allow-Origin  "https://your-domain.com"
Header set Cross-Origin-Embedder-Policy "require-corp"
Header set Cross-Origin-Resource-Policy "same-site"
Header set Cross-Origin-Opener-Policy   "same-origin"
Header set Access-Control-Allow-Headers "range"
2. Deploy Your Game to Your Web Server

Copy the following files to your webserver using sftpor similar mechanism.
You'll find these in your package output folder after the successful completion of your game packaging in the editor.

  $ sftp my-user@my-server.com
  $ cd www\my-game\
  $ put GameEngine.js
  $ put GameEngine.wasm
  $ put GameEngine.worker.js
  $ put FILESYSTEM
  $ put FILESYSTEM.js
  $ put game.html

Step 3) Running (Unit) Tests 🫣

Instructions to run unit tests

There's a bunch of unit tests that are built as part of the normal build process. Basically anything that begins with a "unit_test_" is a unit test.
For writing tests there's a very simple testing utility that is available in base. base/test_minimal.h

In addition to having the unit tests both the audio and graphics subsystems also have "rendering" tests, i.e. playing audio or rendering stuff on the screen. The rendering tests rely on a set of gold images a.k.a. known good images. Currently, the images are provided as part of this repository but there's the problem that because of differences in OpenGL implementations it's possible that the rendering output is not exactly the same between various vendors/implementations (such as NVIDIA, AMD, Intel etc. Fixing this is a todo for later). The audio tests, however, don't have any automated way of verifying the test output.

  • The expectation is that all unit test cases should pass on Linux
  • The graphics rendering tests might have false negatives on different OpenGL vendors/driver versions/OS.
  • Any graphics rendering test that differs from the expected gold image will generate delta and result images.
    • The result image will be the actual result image.
    • The delta image will help visualize the pixels that were not the same between the result and the gold image.
  • Using multiple CMake "jobs" to run tests can confuse the rendering tests.
    • A safer alternative is to NOT use the -jN parameter but only use a single job.

See this list for known Issues

On the Desktop Linux 🐧

How to run all tests

Run all tests including unit tests, graphics and audio tests:

  $ cd detonator/build
  $ ctest -j16
How to run audio tests

Run mp3, ogg, flag and 24bit .wav tests. (Use --help for more information):

  $ cd detonator/audio/test
  $ ./audio_test --mp3 --ogg --flac --24bit
  $ ...
  $ ./audio_test --help
How to run graphics tests

Run all tests with MSAA4. (Use --help for more information):

  $ cd detonator/graphics/test/dist
  $ ./graphics_test --test --msaa4
  $ ...
  $ ./graphics_test --help

On the Desktop Windows 🪟

How to run all tests

  • Before the tests can run you need to make sure that you have the Qt libraries available for loading.

  • For testing in release:

    • Copy QtCore.dll, QtGui.dll, QtNetwork.dll, QtSvg.dll, QtWidgets.dll and QtXml.dll to detonator\build\Release folder.
    • Copy Qt plugins\platforms folder to detonator\build\Release folder.
    • Copy Qt plugins\imageformats folder to detonator\build\Release folder.

  • For testing in debug:

    • Copy QtCored.dll, QtGuid.dll, QtNetworkd.dll, QtSvgd.dll, QtWidgetsd.dll and QtXmld.dll to detonator\build_d\Debug folder.
    • Copy Qt plugins\platforms folder to detonator\build_d\Debug\ folder.
    • Copy Qt plugins\imageformats folder to detonator\build_d\Debug\ folder.

Run all tests including unit tests, graphics and audio tests:

  $ cd detonator\build
  $ ctest -C Release
  ...
  $ cd detonator\build_d
  $ ctest -C Debug

On the Web (WASM+HTML5) 💩

Currently, only some unit tests are available on the web. More tests will be enabled as needed.

How to run unit tests

The detonator/emscripten/bin folder should contain the following build artifacts:

  • http-server.py
  • unit-test.html
  • UnitTest.js
  • UnitTest.wasm
  • UnitTestThread.js
  • UnitTestThread.wasm
  • UnitTestThread.worker.js
  1. Launch a web server for serving the test HTML pages.
  $ cd detonator/emscripten/bin
  $ python http-server.py
  $ Serving at port 8000
  1. Open your web browser and navigate to http://localhost:8000/unit-test.html
  2. Open your web browser and navigate to http://localhost:8000/unit-test-thread.html

The test execution may take some time. The performance tests will execute without running the JS main thread, thus the page will seem "stuck" to the browser. But if you let it run it should complete and print Success! to indicate completion.

Random Notes on Building and Build Setup

How to install Conan💩💩 with Yay on ArchLinux

  1. Download the yay package from AUR
    https://aur.archlinux.org/packages/yay
    BOTH YAY AND CONAN💩💩 WILL LIKELY HAVE MISSING DEPENDENCIES

  2. Install missing Yay dependencies

$ sudo pacman -S debugedit
  1. Build Yay
$ cd yay
$ makepkg
$ sudo pacman -U yay-12.3.5-1-x86_64.pkg.tar.zst
$ yay --version
$ yay v12.3.5 - libalpm v14.0.0
$
  1. Use Yay to install Conan💩💩
$ yay -S conan
$ yay -S python-patch-ng
$ ...
$ conan --version
$ Conan version 2.6.0
$