Building on Windows - TheXTech/TheXTech GitHub Wiki

Content

Intro
Build the game
Running and debugging a build

Intro

The game should work with MinGW-w64 (both 32 and 64-bit), Clang, or with MSVC at least 2015 on your choice. A compiler must support the C++11 standard. With the MSVC 2019 and CMake, you also can produce the ARM64 build.

If you going to use Qt Creator for a development process, please read this manual to install the Qt toolchain on Windows properly.

After you will install compiler toolchains, CMake, Git, and (optionally) a Ninja-Build (You need to put an EXE file into any folder available in PATH environment, for example, the same place where your compiler executables are placed), you can run the build!

Preparing to build

Before to start the build, you should obtain the source code for TheXTech. You can use the stable version as well as the latest in-development to test out any new experimental features and receive any further bugfixes earlier.

Stable version

If you want to build the stable version, you can simply download the source code archive from the official site or from GitHub releases:

Download the source code archive from the TheXTech's official page.
Or download the source code archive from one of GitHub releases pages.

And then, unpack the archive and open the terminal at the just-now unpacked directory that contains the source code for TheXTech.

Important note: Please never use the "Source code" links at Github releases: they are broken. Instead, download the thextech-full-src-v*.*.*.tar.gz or thextech-full-src-v*.*.*.tar.bz2 or thextech-full-src-v*.*.*.zip archive.

This project uses submodules and GitHub is unable to create source code packages that includes submodules too.

Development version

If you want to build the latest in-development version, then, instead of downloading the archive, you can clone the repository itself by running this in a terminal (please open the terminal at the directory where you want to put the clonned repository, so, you will know where it is):

git clone https://github.com/TheXTech/TheXTech.git

Then, Make sure all submodules have been pulled, otherwise, it won't build:

cd TheXTech
git submodule init
git submodule update

Keep a note that these commands usually print nothing.

Build the game

You can build the game using one of the next methods:

Building using MSYS environment (The easiest way)
Building with MinGW from the command line (Using standalone MinGW or MinGW-w64 toolchains)
Building with MinGW from Qt Creator
Building in Visual Studio 2017/2019 by direct open of the CMake project
Building in Visual Studio 2015/2017/2019 and CMake (Suggested for MSVC)
Building for ARM64 with the Visual Studio 2019 and CMake

Building using MSYS environment

This is the simplest way to build the project on Windows.

Preparing the building environment

Run the MSYS2 installer as per https://www.msys2.org#installation steps 1 to 4.
Run "MSYS2 MinGW 64-bit" from the start menu, to open an MSYS2 command line. (To be clear, you really want to run the "MinGW 64-bit" version, not any of the other MSYS2 options).

Run the following command to install the required programs (git, gcc, cmake, ninja) in MSYS2:

pacman --noconfirm --needed -S git mingw-w64-x86_64-toolchain mingw-w64-x86_64-cmake mingw-w64-x86_64-ninja

Open the project directory

Run the following command to change the current directory to the TheXTech's source code directory:
```
cd /c/path/to/TheXTech/
```
Pro tip: You can just type the cd (with a space at end), and then, drag and drop the TheXTech source code directory to the terminal window, and then, the full path will be pasted, and then you can hit the Enter to change the directory.

Running the build

At the TheXTech directory, create the build directory and build the project itself by running the following commands one by one:
```
mkdir build
cd build
cmake -G Ninja -DCMAKE_BUILD_TYPE=Debug ..
ninja
```
(For a release build, which may run faster, replace "Debug" with "MinSizeRel")
If all worked correctly, you will now have a build of the program in the subdirectory output/bin. You can open the directory in Windows Explorer with the following command to take a look:
```
explorer $(cygpath -w $(realpath output/bin))
```
At this point, you need a game root directory to actually be running it. This is a matter of downloading the game assets and making a "worlds" folder. See "Running and debugging a build" for more details.

Building with MinGW from the command line

Use this method only condition when you really don't want to use the MSYS environment at all. Highly recommended to use the MSYS environment to prepare the working build environment.

Before starting the work, you should install the MinGW-w64 toolchain into your system and make sure the "bin" directory is listed in the PATH environment. Also, you will need to install the CMake and (optionally) Ninja build (To install it, simply unpack the downloaded executable into MinGW's bin directory). Once your build environment is ready, open the command line at the repository's directory and follow the next step.
Make the building directory:
```
md build
cd build
```
Run a CMake configuring from a command line: If you going to use the MinGW toolchain, be sure the "bin" folder of the necessary toolchain is available in the PATH environment!
```
rem when you want to use the regular GNU Make
cmake -G "MinGW Makefiles" -DCMAKE_BUILD_TYPE=Debug ..
```
```
ren OR when you want to use Ninja which does better parallel processes management
cmake -G Ninja -DCMAKE_BUILD_TYPE=Debug ..
```
A note: if you going to deploy a release build, the "MinSizeRel" configuration is suggested.

Run the build itself:

rem Run regular GNU Make build with 4 parallel tasks
rem (suggested on 4-core CPU, if you have more cores, use a different number than 4)
mingw32-make -j 4

If you generated build.ninja files (using cmake -G Ninja ..., such as in the release example) in the last step:

rem Or run a Ninja build
ninja

After the build will be complete, you can run the game at output\bin\thextech.exe. Before that, you need to prepare a game root directory in your user directory. At this point, you need a game root directory to actually be running it. This is a matter of downloading the game assets and making a "worlds" folder. See "Running and debugging a build" for more details.

Building with MinGW from Qt Creator

Important: To properly install the Qt Creator and related tools, please read this manual to install the Qt toolchain on Windows properly.

If you use the Qt Creator IDE, you can simply open the CMakeLists.txt as a project, it will be automatically configured with the toolchains you will choose for that. Make only sure that build directories were short, otherwise, the build would fail with a "too long path" error in a process of unpacking a source code of SDL2 dependency.

After the build will be complete, you can run the game using the IDE's "Run" button. Before that, you need to prepare a game root directory in your user directory (See "Running and debugging a build" for more details).

Building in Visual Studio 2017/2019 by direct open of the CMake project

Visual Studio since 2017 supports a direct building of CMake projects, you can open the directory of TheXTech's episode root as a project!

Once you will open it, make a small tune of CMakeSettings.json: change buildRoot and installRoot with some shorter paths (for example C:\Repos\xtech-32 or C:\Repos\xtech-64, or E:\my\xt-32) to avoid the "path too long" error while unpacking sources of SDL2 dependency.
Then, start a build.
After the build will be complete, you can run the game using the IDE's "Run" button. Before that, you need to prepare a game root directory in your user directory (See "Running and debugging a build" for more details).

Building in Visual Studio 2015/2017/2019 and CMake

You can use CMake to generate projects for Visual Studio IDE.

At first, you need to open the console of development tools for Visual Studio and change the directory to the root of the repository.

How to generate the build:

At the first, make the building directory:

md build
cd build

Now, you need to generate the project:

for Visual Studio 2015:

cmake -G "Visual Studio 14 2015" -A Win64 ..

for Visual Studio 2017:

cmake -G "Visual Studio 15 2017" -A Win64 ..

for Visual Studio 2019:

cmake -G "Visual Studio 16 2019" -A Win64 ..

Note: where -A Win64 is a type of target platform for the build. You can specify the -A Win32 to generate the 32-bit build of the game, or -A ARM64 to build the game for mobile ARM-based devices (some tablets run Windows 10 with the ARM processor. Visual Studio 2019 and ARM SDK libraries required).

And then:

run a build from the console:
```
cmake --build . --config Debug --parallel 4
```
A note: Where --config Debug is a type of the build. Debug means the assembly with debug symbols and has disabled optimizations. If you going to deploy a release build, the "MinSizeRel" configuration is suggested. It will enable the rest of the optimizations and will strip all debug symbols from target binaries. Where --parallel 4 means run 4 parallel build processes that speeds-up the whole build. You can specify the different number of parallel builds by looking at the number of cores on your CPU.
Or open the .sln file you can find in the build directory after the project generating in the Visual Studio IDE directly.

Next: Running and debugging a build

Building for ARM64 with the Visual Studio 2019 and CMake

To produce the assembly for ARM64 architecture, you need to run the next from your MSVC 2019 command line (Your MSVC toolchain should contain the ARM libraries set being installed):

md build
cd build
cmake -G "Visual Studio 16 2019" -A ARM64 ..

And then, run a build itself:

cmake --build . --config Debug --parallel 3

Next: Running and debugging a build

Running and debugging a build

The built game will not work until you will prepare the game root. Please prepare the game root until you will be able to run a game. The game root by default is located in your home directory and you can have multiple builds with different configurations and modes, all will use the same game root directory at your home directory.

Make a folder in your home directory:
```
md %UserProfile%\.PGE_Project
md %UserProfile%\.PGE_Project\thextech
```
Note: Where %UserProfile% is an environment variable that contains a path to your user directory, for example, C:\Users\Wohlstand.

Tip: Instead of manual directory making, try to run the game executable: it will span an error of missing UI assets, and will automatically create the tree of directories!
Download one of two archives with compatible assets:
- SMBX 1.3 assets
- Adventures of Demo assets
Unpack the content of an archive into your %UserProfile%\.PGE_Project\thextech directory
Make in the %UserProfile%\.PGE_Project\thextech directory the "worlds" folder and put any compatible episodes you have (all episodes made for an original SMBX 1.3 and earlier will work here). Optionally you can make the "battle" folder and put a bunch of level fils which will be used for battle arena purposes.
Once your game root directory is ready, feel free to run the output\bin\thextech.exe binary (or the "Run"/"Debug" button at your IDE) to start a game.