Building PGE From sources

From PGE Wiki
Revision as of 08:56, 19 September 2017 by Love bodhi (talk | contribs)
Jump to navigation Jump to search

This is a guide that will provide an overview for building PGE for your specific operating system.

Preparing to build

  • Download the required sources (clone dev repo)
  • Download a desired config pack

Firstly, you will need to download all required sources:

Clone the repository with the following commands:

#create a directory for your repos if you do not already have one
mkdir ~/myrepos
cd ~/myrepos/

#clone the repo into your new directory
git clone --recursive -j4
cd PGE-Project

(You must have git installed. On OS X it is usually already installed. For Windows Git Bash may be used which is included with the git installation)

Tip: If you have a slow network connection, you can speed-up the cloning process by using the "--depth=1" flag. To use a SSH-based url you must be logged into GitHub.

If you failed to clone the repo you can alternatively download all of the sources as a single ZIP:

(use the "Download Zip" link to download the sources from GitHub)

How to Download ZIP from GitHub

Next, download the submodule dependencies and place them into their folders. (Without these submodules, PGE is not buildable!):

Now download any configuration package (that contains media such as graphics, music and sounds) that is known to work with the latest laboratory version of PGE:

Building for Linux


Need to install

  • Qt >= 5.4 (The latest version can be downloaded from here: (You will need the "Open Source" version)
  • gcc >= 5.0
  • g++ >= 5.0
  • Installed OpenGL libraries and headers (mesa-drv, x11-xcb-dev, etc.)

Already included with PGE sources (these will be built by the script)

  • SDL2 2.3 (used latest version from official Mercurial repository)
  • SDL Mixer X (a.k.a. SDL2_mixer_ext) - fork of SDL2 mixer made by Wohlstand
    • libogg
    • libvorvis
    • libFLAC
    • libMAD
    • libmodplug (sources are merged with SDL Mixer X)
    • libADLMIDI (recoded into library from ADLMIDI console player)
    • libGME
  • FreeImageLite (modded FreeImage which supports PNG, BMP, GIF and ICO formats only. Purpose of mod - reduce library size with disabled of useless for PGE format libraries)
  • libluabind (deboostified version)
    • luajit (based on Lua 5.2)

Note: italic dependencies are partially modified (fixed warnings or some bugs)

Installing development tools

GCC and system libraries

Install gcc and dependent libraries on Debian/Ubuntu/Mint

For modern releases

sudo apt-get install gcc g++ git wget make automake
sudo apt-get install build-essential
sudo apt-get install libasound2-dev libdbus-1-dev libegl1-mesa-dev libgl1-mesa-dev libgles2-mesa-dev libglu1-mesa-dev libmirclient-dev libpulse-dev libsndio-dev libudev-dev libwayland-dev libx11-dev libxcursor-dev libxext-dev libxi-dev libxinerama-dev libxkbcommon-dev libxrandr-dev libxss-dev libxt-dev libxv-dev libxxf86vm-dev

For older releases

sudo apt-get install gcc g++ git wget make
sudo apt-get install build-essential
sudo apt-get install "^libxcb.*" libx11-dev libx11-xcb-dev libxcursor-dev libxrender-dev \
libxrandr-dev libxext-dev libxi-dev libxss-dev libxt-dev libxv-dev \
libxxf86vm-dev libxinerama-dev libxkbcommon-dev libfontconfig1-dev \
libasound2-dev libpulse-dev libdbus-1-dev libts-dev udev mtdev-tools webp \
libudev-dev libglm-dev libwayland-dev libegl1-mesa-dev mesa-common-dev \
libgl1-mesa-dev libglu1-mesa-dev libgles2-mesa libgles2-mesa-dev

Optional: Installing the ccache package is possible to speed up the building process

sudo apt-get install ccache

on Redhat / CentOS

sudo yum install gcc g++ git wget make automake nano
sudo yum install alsa-lib-devel libX11-devel libXScrnSaver-devel libXcursor-devel libXext-devel libXi-devel libXinerama-devel libXrandr-devel libXrender-devel libxkbcommon-devel mesa-libEGL-devel mesa-libGL-devel mesa-libGLES-devel mesa-libGLU-devel systemd-devel

on openSUSE

sudo zypper install gcc gcc-c++ git wget make automake nano
sudo zypper install alsa-lib-devel libX11-devel libXScrnSaver-devel libXcursor-devel libXext-devel libXi-devel libXinerama-devel libXrandr-devel libXrender-devel libxkbcommon-devel mesa-libEGL-devel mesa-libGL-devel systemd-devel

Qt 5

To get Qt installed you have two options.

The first is to Qt5 packages from your distribution's repositories or you can download it from the following page:

Note: You need to make an account there in order to download. More download options will be visible if you open the "View all downloads" page.

If you download the necessary packages from the official Qt project's site you should set "executable" permission in a terminal to get a runnable install for Qt's installation.

  • download package to your PC
  • Set executable:
chmod u+x
  • Run installer:

and follow install instructions.

Once you're finished, don't forget to check if Qt is installed to "/opt/Qt/"

/home/$USER/Qt/5.7/gcc_64/bin/qmake -v

If you get a return messsage such as the following, congrats! Everything is successful up to this point ;-)

QMake version 3.0
Using Qt version 5.7.0 in /home/someone/Qt/5.7/gcc_64/lib

If you care about convenience, it's recommended to make a symlink to qmake in the /usr/bin This will make it easier to use qmake.

sudo ln -s /home/$USER/Qt/5.7/gcc_64/lib /usr/bin/qmake
Warning: If you've already installed other versions of Qt, it's preferable to create a symlink with a name such as "qmake-qt5"

Preparing to build

  • Extract the source code to a folder where you know you'll find it easily (such as /home/vasya/projects/pge/)
  • Extract the downloaded config pack to /path/to/your/source/Content/configs

Make sure you have the following folder tree.

configs/-ConfigPackDir-/data folder tree

  • Now open the terminal and change the current directory to the previously unpacked folder that contains the project sources.
  • run the file and when gedit opens, type in the paths to qmake and to lrelease (these paths should normally be towards the bin directory of your Qt,

Example: /opt/Qt/5.7/gcc_64/bin/qmake, /opt/Qt/5.7/gcc_64/bin/lrelease)

  • run the to build the included dependent libraries.

Building the code

To start building, use the script:

chmod u+x

Once everything has finished building, you should now be able to see the built executubles in the ./bin folder.

Now if you'd like to start the PGE editor, run the pge_editor file

Additional arguments for

  • no-pause - skips pausing when the script finishes
  • use-ccache - this can speed up the building process but you'll need to first install the ccache tool. Works with the GCC compiler.

Deploying builds

It's possible to pack your build in order to use it on other systems without rebuilding. To do this, run the "" script from a "_Misc/dev_scripts/deploy" folder:

cd _Misc/dev_scripts/deploy
cd ../../..

Once the deploy script has finished you'll get something such as "bin/_packed/pge-project-dev-linux-mint.tar.gz". Ta-da! You now have a file that allows you to share or use your compiled build on other systems.


  • Your build will only work on systems that are compatible with your own linux distro. For example a PGE build that has been built on a Debian/Mint/*Ubuntu system will NOT work on a Fedora/CentOS/Redhat/OpenSUSE system (or vica versa)!
  • To have the correct deployment, it's recommended to build PGE with the Static version of Qt.

Building for Windows


  • MinGW >= 5.3 (You can get MinGW installer here: (MinGW already includes with Qt MinGW installer)
  • Qt >= 5.4 (You can download it here: (Get Qt for Windows 32 bit (minGW) or use Online Installer to take same version. Don't download VisualStudio versions if you don't plan to use it for yourself! PGE requires MinGW, because MinGW has support of a functions used by PGE which are not available in MSVC!)
  • 7zip (You can download it here: (needed for deploy script which must be used with dynamic Qt build which available to download)
  • Git (You can download it here: (Optionally, without it PGE Editor/Engine are will have not build-ID mark in about dialog)
  • SDL2 >= 2.0 (Already included in the _Libs/_builds/win32)
  • SDL2_mixer >= 2.0 (Already included in the _Libs/_builds/win32)

Installation of the development tools

Install all the tools in a folder, for example, C:\DevTools.

  • MinGW into C:\MinGW (if you got it separated)
  • Qt into C:\Qt

Qt installation Note: you must enable those components:

  • 5.8.0 -> MinGW 5.3.0 32 bit or similar
  • Tools -> MinGW 5.3.0 or similar

Other components are optional and doesn't required


If you want to build 64-bit version, you must have 64-bit Qt for MinGW which is not available officially, however, you can build it youtself.

You can read manual How to build Qt on MinGW-w64 by yourself.

Important note: Qt since 5.8 no more supports Windows XP. Therefore Editor, Maintainer and Calibrator are built with Qt >= 5.8 will fail with "CancelIoEx not found in the kernel32.dll" error. If you want to support Windows XP, please install the Qt of 5.7 version or older.

After the install, you can add MinGW and Qt directories into PATH environment:

(if tools was installed into C:\DevTools, you must append those folders into PATH global variable)


to use your installed MinGW separately or


to use the internal pre-installed MinGW in the Qt folder

PATH string to append:


Preparing to build

  • Extract the source code to a folder where you can find it easily (Path shouldn't contain non-ASCII characters!)
  • Extract the downloaded config pack into /path/to/your/source/Content/configs or into /path/to/your/source/bin-w32/configs (if bin-w32 and configs sub-directory are not exists - create them!)

You must have this tree:

configs/-ConfigPackDir-/data folder tree

  • run the generate_paths.bat file and when notepad will open, type the paths to Qt and to MinGW

for example C:\Qt\5.7\mingw53_32\bin and C:\Qt\Tools\mingw530_32\bin)

  • run the build_deps.bat to build included dependent libraries.

Build code

  • In the project folder, hold Shift key on your keyboard and press the right mouse button, and in the context menu select "Open command window" (available for Windows 7 and newer).
  • In the opened command Window, enter these commands for the build:

If everything is successfully built, you will see the built PGE executables in the bin-w32 subfolder - it's the compiled PGE application. You can run and use it!

P.S. If you was built the dynamic version, you need to run the "_Misc\dev_scripts\deploy\deploy_windows_dynamic.bat" script to automatically copy necessary DLLs into PGE's binary folder. You need to have installed 7zip to have able run this script.

When everything is built, you can run the pge_editor.exe from a bin-w32 directory to run editor application or run the pge_engine.exe to launch game engine.

Building for Mac OS X


Installing of development tools


To install XCode you need to download it from your App Store.

Dependent tools

To have correct working build scripts, you also need to install "coreutils", "binutils" and "gnu-sed"

brew install coreutils
brew install binutils
brew install gnu-sed

Note: If you are using MacPorts, do those commands instead:

port install bunutils
port install coreutils
port install gsed


You have two ways to install Qt:

  • via homebrew in with terminal command: brew install qt5
  • via Online installer (We recommends you to choice the ~/Qt path which will be easy to access from Finder)

Important Note for El Capitan (OS X 10.11.*) and for HighSierra (OS X 10.13.*)

If you received a build errors with missing of the headers which a small bug which forces to find SDK for OS X 10.10 while you have pre-installed SDK only for 10.11. This trouble can be easily fixed with a small workaround: you will need to make a symlink to 10.11 in the SDK's folder:

ln -s /Applications/ \

In case of "High Sierra" replace versions with 10.12 and 10.13 (XCode 9)

ln -s /Applications/ \

"High Sierra" with XCode 8

ln -s /Applications/ \

Since you will run this in the terminal, build process must work correctly

Static version of Qt

If you don't want to have a troubles with frameworks and dependent dynamic libraries, we are recommending to build static version of Qt yourself. Here is detail manual how to build static version of Qt 5 for Mac OS X: Building static Qt 5

Preparing to build

  • Extract the source code to a folder where you can find it easily (Path shouldn't contain non-ASCII characters!)
  • Extract the downloaded config pack into /path/to/your/source/Content/configs

You must have this tree:

configs/-ConfigPackDir-/data folder tree

  • run the file and when nano will open, add Qt path into environment and save file with CMD+O

for example ~/Qt/clang_32/bin)

  • run the to build included dependent libraries.

Building code

To build project use the special script:


When everything will be built, you will see the built app bundles in the ./bin folder.

To start usage of the editor, run the file

Deploying of built stuff

If you wish to make a DMG image to use your build on another computers without rebuilding, you can run the "" script from a "_Misc/dev_scripts/deploy" folder:

cd _Misc/dev_scripts/deploy
cd ../../..

When deploy script will finish it's job, you will get the "bin/_packed/pge-project-dev-macosx.dmg" file which you can share to friends or use on another computers yourself.

Note: To have right deployment, you should build PGE with Static version of Qt.


file_formats.h (or any other) not found

If this file is not found, seems you forgot to download submodules.

... is not a member of ...

Usually this error appears when you have an outdated submodules. If error happens outside any submodule related classes, that means a bug, caused by a missing macros or support of another operating system. Please report about this to us.

Merge conflicts

Reasons of merge conflicts are:

  • You have committed some change of some line which also changed in the pulling state
  • You have a folder which has been turned into submodule, but you still have it as part of PGE repository. Delete it and try to pull again. If you still have error, try to re-clone repository
  • Was a force push with incompatible history modification. After this you must re-clone the repository

If you have any troubles with merge conflicts in case you didn't made any changes and you can't resolve it, just re-clone repository

Fatal error: can't create .... on running build script

If you getting this error, means you have damaged make files. To fix that you must run the ./ or clean_make.bat (dependent on operating system) scripts in the root of the repository

Access denied error while linking

This error usually happens on Windows operating system. It means you trying to rebuild application which is still in run. If you already closed it, please check out the task manager and kill it if it has turned into zombie and still be in the memory.

Any "undefined reference" error while linking

This error means that some of dependencies is built incorrectly and lacks some of function, external variable or class. Another reason is a missing system library in the link list which is dependent on your operating system.