Building Moondust Project from sources
This is a guide that will provide an overview for building Moondust Project (also known as PGE Project) for your specific operating system.
Preparing to build
- Download the required sources (clone a development repository and all its submodules)
- Download the desired config pack
Firstly, you will need to download all required sources:
Clone the repository with the following commands:
# On Linux or macOS, create a directory for your repos if you do not already have one mkdir ~/myrepos cd ~/myrepos/ # On Windows, you need to open a folder where you want to store your repositories (you should have ASCII-only characters in a full path!) and open the Git Bash on it # clone the repo into your new directory git clone --recursive -j4 https://github.com/WohlSoft/Moondust-Project.git cd PGE-Project # clone submodules (they are required to build PGE Project) git submodule init git submodule update
Note: You should to have the Git installed. On macOS it's usually already installed.
For Windows Git Bash can be used. You should install a Git For Windows to get started.
Tip: If you have a slow network connection, you can speed-up the cloning process by using of the "--depth=1" flag. To use a SSH-based url you must be logged into GitHub.
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 (You can install the necessary set of Qt libraries by your package manager. Otherwise, the latest version can be downloaded from here: https://www.qt.io/download-qt-installer (You will need the "Open Source" version), valid for x86_64 systems only, on ARM or PowerPC-based platforms you should use the package manager to obtain the necessary set of Qt libraries, see the guide below)
- gcc >= 5.0
- g++ >= 5.0
- Installed OpenGL libraries and headers (mesa-drv, x11-xcb-dev, etc.)
- CMake >= 3.5 (If you have older CMake in your distro packages repository, you can alternatively download a fresh version of CMake here: https://cmake.org/download/)
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 gcc-c++ 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 glibc-static libstdc++-static
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 glibc-static libstdc++-static
To get Qt installed you have two options. The first is to Qt5 packages from your distribution's repositories via your package manager, and the second is downloading binaries from the official site of Qt.
Most easier way to install necessary Qt libraries is using package manager of your Linux distribution.
Ubuntu 16+ / Mint 18+
sudo apt-get install qt5-default qt5-qmake qttools5-dev qttools5-dev-tools libqt5gui5 \ libqt5core5a libqt5widgets5 libqt5concurrent5 libqt5qml5 qtdeclarative5-dev libqt5network5 \ qt5-image-formats-plugins qt5-gtk-platformtheme qt5dxcb-plugin qtwayland5 libqt5waylandclient5
Redhat / CentOS
sudo yum install qt5-devel
WARNING: This paragraph is valid for x86_64 machines only, and will not work on ARM/PowerPC/x86 machines.
Alternatively to package managers, you can download Qt5 from the official site on the following page: https://www.qt.io/download
Note: If you don't know what to download, choose "Open Source", it has all necessary for PGE Project.
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 qt-unified-linux-x64-online.run
- Run installer:
And follow install instructions.
Tip: Installer will ask you to login or register: it's not necessary and can be just skipped. Hit the Skip button to continue installation.
Once you're finished, don't forget to check if Qt is installed to "/home/$USER/Qt"
If you get a return messsage such as the following, congrats! Everything is successful up to this point ;-)
QMake version 3.1 Using Qt version 5.12.4 in /home/wohlstand/Qt/5.12.4/gcc_64/lib
Preparing to build
- Extract the downloaded config pack to /home/$USER/.PGE_Project/configs
Make sure you have the following folder tree.
- Now open the terminal and change the current directory to the in the PGE-Project repo directory that contains the project sources.
- run the ./generate_paths.sh command to configure the build and check which Qt installation was detected. If no Qt installation was detected, the text editor (gedit, mcedit, or nano) will be opened with the _paths.sh file and you will need to manually set paths to Qt bin and lib directories,
#-----------------Path to Qt bin directory----------------- QT_PATH="/home/user/Qt/5.12.0/gcc_64/bin/"; #-----------------Path to Qt lib directory----------------- QT_LIB_PATH="/home/user/Qt/5.12.0/gcc_64/lib/";
Building the code
To start building, use the build.sh script:
chmod u+x build.sh ./build.sh
Once everything has finished building, you should now be able to see the built executubles in the ./build-pge-cmake-release/bin folder.
Now if you'd like to start the PGE editor, run the pge_editor file
Additional arguments for build.sh
- no-pause - skips pausing when the script finishes
It's possible to pack your build in order to use it on other systems without rebuilding. To do this, run the "./build.sh deploy" command from the repository root:
Once the deploy process has finished you'll get something such as "bin-cmake-release/pge_project-linux-64.tar.bz2". Ta-da! You now have a file that allows you to share or use your compiled build on other systems.
- Your build will correctly work on only 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.
Generate Lua-API documentation
Lua-API documentation is written in the source code directly. It can be converted into friendly and brows-able set of HTMLs that can be used.
- LDoc (You need to clone it into the repository into parent directory of PGE Project repository. I.e.
git clone https://github.com/stevedonovan/LDoc ../LDoc)
- Penlight (Can be also installed through luarocks:
sudo luarocks install penlight)
After you have installed all dependencies and built the project, run next command to run documentation build:
On successful work you will found the compiled documentation in Engine/doc/doc folder.
Building for Windows
- MinGW >= 5.3 or MinGW-w64 (can be used one that coming together with the Qt framework by installer)
- Qt >= 5.4 (You can download it here, you will need the Open Source): http://www.qt.io/download-open-source/#section-5). You also can read the Installing Qt on Windows manual.
- Get Qt for Windows 32/64 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 and templates are used by PGE which are not available and not buildable in MSVC!
- You don't need for a paid Qt version. You need to download the Open Source!
- 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)
- CMake >= 3.5 (You can download it here: https://cmake.org/download/)
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:
- For 64-bit build
- 5.12 -> MinGW 7.2.0 64 bit or higher
- Tools -> MinGW-w64 7.2.0
- For 32-bit build
- 5.12 -> MinGW 7.2.0 32 bit or higher
- Tools -> MinGW-w64 7.2.0
Other components are optional and doesn't required
Tip: 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. Since Qt 5.12.0, 64-bit Qt builds for MinGW are shipped officially.
Important note: Since 5.8, Qt does no longer support the Windows XP. Therefore, Editor, Maintainer, MusicPlayer, and Calibrator will fail with "CancelIoEx not found in the kernel32.dll" error if they built with Qt >= 5.8. To keep the support for Windows XP, please install the Qt 5.6.x or earlier.
Preparing to build
- Clone the source code repository to a folder where you can find it easily (Path shouldn't contain non-ASCII characters!)
- Extract the downloaded config pack into %UserProfile%\.PGE_Project\configs (if .PGE_Project directory is not exists - create it, and create the "configs" folder inside!)
You must have this 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)
- 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 build-pge-cmake-release/bin subfolder - it's the compiled PGE application. You can run and use it!
P.S. If you want to deploy the pre-compiled stuff, you will need to run the next command to automatically copy all necessary DLLs into PGE's binary folder. You will need to have installed 7zip to be able to run this.
When everything is built, you can run the pge_editor.exe from a build-pge-cmake-release/bin directory (or from bin-cmake-release/PGE_Project when you have used `deploy` command) to run editor application or run the pge_engine.exe to launch game engine.
Building for Windows via MSYS2
Alternatively, you can build PGE with using of MSYS2 environment.
- Install MSYS2 (https://www.msys2.org/)
- From the start menu, open "MSYS2 MinGW 64-bit" or "MSYS2 MinGW 32-bit" depending if you want a 64-bit or 32-bit build
- To install dependencies for 64-bit, run:
pacman -S git p7zip mingw-w64-x86_64-toolchain mingw-w64-x86_64-cmake mingw-w64-x86_64-qt5
or for 32-bit run:
pacman -S git p7zip mingw-w64-i686-toolchain mingw-w64-i686-cmake mingw-w64-i686-qt5
- To get the source code and build, run the following commands:
git clone --depth 1 --recursive https://github.com/WohlSoft/Moondust-Project.git PGE-Project cd PGE-Project ./generate_paths.sh ./build.sh deploy
- You now you should have a build of PGE!
Building for Mac OS X
- XCode and command line dev-tools must be installed (https://developer.apple.com/xcode/downloads/)
- Qt >= 5.4
- SDL2 >= 2.0 (will be built with build_deps.sh script)
- SDL2_mixer >= 2.0 (will be built with build_deps.sh script)
- CMake >= 3.5 (You can download it here: https://cmake.org/download/ or install it with command brew install cmake)
Installing of development tools
To install XCode you need to download it from your App Store.
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/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX10.11.sdk \ /Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX10.10.sdk
In case of "High Sierra" replace versions with 10.12 and 10.13 (XCode 9)
ln -s /Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX10.13.sdk \ /Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX10.12.sdk
"High Sierra" with XCode 8
ln -s /Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX10.12.sdk \ /Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX10.13.sdk
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:
- run the generate_paths.sh file and when nano will open, add Qt path into environment and save file with CMD+O
for example ~/Qt/clang_32/bin)
To build project use the special build.sh script:
When everything will be built, you will see the built app bundles in the ./build-pge-cmake-release/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 "build.sh" script with the "deploy" argument:
When deploy script will finish it's job, you will get the "bin-cmake-release/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.
Building PGE Engine for Android
For now is PGE Engine only can be built for Android platform.
- Most recent Android Studio for development
- Android SDK 28+
- Android NDK
Preparing to build
The project you need to open and build is located in `Engine/android-project`. Until you will be able to open the project you need to initialize it: open the terminal (or Git Bash if you running on the Windows) and change current directory into `<repo>/Engine/android-project`. Then, execute the `build_init.sh`. After the build has been initialized, feel free to open it in Android Studio where you are able to run the build.
From Android Studio you can run Build->Make to just compile the project, or Build->Generate signed APK to get the ready-for-use APK. Please check both Java Key Stores.
Deploying of built stuff
APK you have built, can be simply installed into the device through ADB or by manual placing into the device and installing via any file manager.
To make it work right you will need:
- make the `/sdcard/PGE Project` folder and then `/sdcard/PGE Project/configs` and `/sdcard/PGE Project/worlds` inside
- put any config pack into `/sdcard/PGE Project/configs` folder
- put any episode or levels set into `/sdcard/PGE Project/worlds` folder
- On Android 6+ you will need to switch on the file system access, otherwise engine will not be able to see config packs and episodes
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.
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 `./build.sh clean` or `build.bat clean` (dependent on operating system) scripts in the root of the repository
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.
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.
ninja: error: '...', needed by '...', missing and no known rule to make it
Note: This trouble has been resolved in recent commits of a "master", so, you will no longer meet this issue again.
When you trying to run CMake build directly by using Ninja, keep an eye on the fact it can't correctly deal with "external projects" of CMake for the case dependent libraries are didn't built yet. However, you have a solution: at first, you need to build dependent libraries as the separated target:
cmake --build . --target libs
On a moment when all libraries will be built, you'll be able to compile the project:
cmake --build . --target all
Which platform version supported? (Windows, macOS, Linux, Android)
Any non-Qt components supports minimal platforms as possible as they are can (Windows XP and macOS 10.7). Qt with newer versions graduately drops support of old platforms: Platforms supported by Qt. To support certain older platform, you need to get the specified Qt version that is able to work on a wanted platform.
- For example, to support Windows XP, you need to use the Qt 5.6 which is LTS. Qt 5.7 is able to work on Windows XP, however, since Qt 5.8 all Qt apps will fail with missing CancelIO call inside Kernel32.dll on Windows XP.
- For the case of Linux, you can support old platform with latest Qt in the case you will compile all required dependencies from sources with using of modern compiler (GCC 6+ or CLang 4+, C++11 required, C++14 is recomended).
- For the case of macOS, you will need to use specific Qt version to support older macOS platforms. You still can use latest XCode to produce working binaries. You should be sure to specify minimal macOS version to get the complete deployment working on older platform.
- Minimal Android version support is dependent on a version of SDK. With newer version of SDKs, minimal Android version is increasing. If you want to deploy to old platform, you should use an older SDK.