Building Moondust Project from sources

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:

Try to clone the repository with the following commands:

(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)

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

https://github.com/WohlSoft/PGE-Project

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



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


 * PGE File Library - must be in "_common/PGE_File_Formats" folder.
 * libFreeImageLite - must be in "_Libs/FreeImage" folder.

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

http://wohlsoft.ru/docs/_laboratory/config_packs

Dependences
Need to install
 * Qt >= 5.4 (The latest version can be downloaded from here: http://www.qt.io/download-open-source/ (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 build_deps.sh 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)

GCC and system libraries
Install gcc and dependent libraries on Debian/Ubuntu/Mint

For modern releases

For older releases

Optional: you can install a ccache tool in order to speed up the building process

on Redhat / CentOS

on openSUSE

Qt 5
To get Qt installation you have two ways: you can install Qt5 packages from your repositories but also you can download it here:

http://www.qt.io/download-open-source/

If you download necessary package from official site, you should open Terminal and set "executable" permission to get able start installation.

and follow install instructions.
 * download package to your PC
 * Set executable:
 * Run installer:

after installation don't forget to check installed Qt (If your Qt was installed into "/opt/Qt/"):

If you will get message like this: Everything are okay ;-)

for convenience, you can make symlink to qmake in the /usr/bin and use qmake easier:

Preparing for build

 * Extract the source code to a folder where you can find it easily (for example, /home/vasya/projects/pge/)
 * Extract the downloaded config pack into /path/to/your/source/Content/configs

You must have this tree:

 -configs//data --music --sound --graphics common characters --mario --peach --luigi --toad --link level --background --background2 --block --npc --effect worldmap --level --player --tiles --scene --tile for example /opt/Qt/5.7/gcc_64/bin/qmake, /opt/Qt/5.7/gcc_64/bin/lrelease)
 * open the terminal and change current directory to the unpacked folder with project sources
 * run the generate_paths.sh file and when gedit will open, type the paths to qmake and to lrelease (in the bin directory of your Qt,
 * run the build_deps.sh to build included dependent libraries.

Building code
To build project use the special build.sh script:

When everything will be built, you will see a built executables in the ./bin folder.

To start usage of the editor, run the pge_editor file

Additional arguments of build.sh

 * no-pause - skips pause on script finishing
 * use-ccache - can speed-up building process, but you need to install ccache tool. Works with GCC compiler.

Deploying of built stuff
If you wish to pack your build to use it on another computers without rebuilding, you can run the "deploy_linux.sh" script from a "_Misc/dev_scripts/deploy" folder:

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

Notes:
 * Your build will work on compatible linux distros only: I.e. PGE built on Debian/Mint/*Ubuntu will NOT work on Fedora/CentOS/Redhat/OpenSUSE or back!
 * To have right deployment, you should build PGE with Static version of Qt.

Dependences

 * MinGW >= 5.3 (You can get MinGW installer here: http://sourceforge.net/projects/mingw/files/latest/download?source=files) (MinGW already includes with Qt MinGW installer)
 * Qt >= 5.4 (You can download it here: http://www.qt.io/download-open-source/#section-5) (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: http://7-zip.org/) (needed for deploy script which must be used with dynamic Qt build which available to download)
 * Git (You can download it here: https://git-scm.com/) (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. Qt installation Note: you must enable those components: Other components are optional and doesn't required
 * MinGW into C:\MinGW (if you got it separated)
 * Qt into C:\Qt
 * 5.8.0 -> MinGW 5.3.0 32 bit or similar
 * Tools -> MinGW 5.3.0 or similar

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//data --music --sound --graphics common characters --mario --peach --luigi --toad --link level --background --background2 --block --npc --effect worldmap --level --player --tiles --scene --tile

for example C:\Qt\5.7\mingw53_32\bin and C:\Qt\Tools\mingw530_32\bin)
 * run the generate_paths.bat file and when notepad will open, type the paths to Qt and to MinGW
 * run the build_deps.bat to build included dependent libraries.

Build code
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!
 * 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:

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.

Dependences

 * XCode and command line dev-tools must be installed (https://developer.apple.com/xcode/downloads/)
 * Qt >= 5.4
 * (You can download it here: http://www.qt.io/download-open-source/) (Get latest Qt for Open Source version)
 * Qt can be installed from homebrew with command brew install qt5
 * SDL2 >= 2.0 (will be built with build_deps.sh script)
 * SDL2_mixer >= 2.0 (will be built with build_deps.sh script)

XCode
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 "coreutols", "binutils" and "gnu-sed"

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

Qt
You have two ways to install Qt:
 * via homebrew in with terminal command:
 * 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.*)
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:

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//data --music --sound --graphics common characters --mario --peach --luigi --toad --link level --background --background2 --block --npc --effect worldmap --level --player --tiles --scene --tile

for example ~/Qt/clang_32/bin)
 * run the generate_paths.sh file and when nano will open, add Qt path into environment and save file with CMD+O
 * run the build_deps.sh to build included dependent libraries.

Building code
To build project use the special build.sh script:

./build.sh

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

To start usage of the editor, run the pge_editor.app 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 "deploy_osx.sh" script from a "_Misc/dev_scripts/deploy" folder:

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.

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: 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
 * 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

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 ./clean_make.sh 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.

Links

 * Original building manual on PGE Forums