Building Moondust Project from sources

This is a guide that will provide an overview of building the Moondust Project (formerly 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:

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

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

Dependences
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/)

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

For modern releases

For older releases

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

on Redhat / CentOS

on openSUSE

on Arch-based distros

Qt 5
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.

Package managers
The most easier way to install necessary Qt libraries is using the package manager of your Linux distribution.

Ubuntu 16+ / Mint 18+

Redhat / CentOS

Arch-based distros

Official binaries
Alternatively, to package managers, you can download Qt5 from the official site on the following page: https://www.qt.io/download

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 the package to your PC
 * Set executable:

And follow install instructions.
 * Run the installer:

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

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

Preparing to build

 * Extract the downloaded config pack to /home/$USER/.PGE_Project/configs

Make sure you have the following folder 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
 * Now open the terminal and change the current directory to in the Moondust-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,

Example:

Building the code
To start building, use the build.sh script:

Once everything has finished building, you should now be able to see the built executables in the ./build-pge-cmake-release/bin folder.

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

Additional arguments for build.sh

 * no-pause - skips pausing when the script finishes

Deploying builds
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.

Notes:
 * Your build will correctly work on only systems that are compatible with your own Linux distro. For example, a Moondust 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 Moondust 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 a friendly and browsable set of HTML that can be used.

Dependencies

 * LDoc (You need to clone it into the repository into the parent directory of the Moondust Project repository. I.e. )
 * Penlight (Can be also installed through luarocks: )

Build
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.

Dependences

 * MinGW >= 5.3 or MinGW-w64 (can be used one that comes together with the Qt framework by the 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! Moondust requires MinGW because MinGW has the support of functions and templates used by Moondust which are not available and not buildable in MSVC!
 * You don't need a paid Qt version. You need to download the Open Source!
 * 7zip [You can download it here: http://7-zip.org/ or SourceForge (needed for deploy script which must be used with dynamic Qt build which is available to download)]
 * Git (You can download it here: https://git-scm.com/) (Optionally, without it Moondust Editor/Engine are will have not a build-ID mark in the about dialogue)
 * 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. Qt installation Note: you must enable the components: Other components are optional and aren't required to be installed.
 * MinGW into C:\MinGW (if you got it separated)
 * Qt into C:\Qt
 * For a 64-bit build
 * 5.12 -> MinGW 7.2.0 64 bit or higher
 * Tools -> MinGW-w64 7.2.0
 * For a 32-bit build
 * 5.12 -> MinGW 7.2.0 32 bit or higher
 * Tools -> MinGW-w64 7.2.0

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%\.Moondust_Project\configs (if .Moondust_Project directory is not exist - create it, and create the "configs" folder inside!)

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

Build code
If everything is successfully built, you will see the built Moondust executables in the build-pge-cmake-release/bin subfolder - it's the compiled Moondust application. You can run and use it!
 * In the project folder, hold the 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 want to deploy the pre-compiled stuff, you will need to run the next command to automatically copy all necessary DLLs into Moondust'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/Moondust_Project when you have used `deploy` command) to run the editor application or run the pge_engine.exe to launch the game engine.

Building for Windows via MSYS2
Alternatively, you can build Moondust with using of MSYS2 environment. or for 32-bit run:
 * 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:


 * To get the source code and build, run the following commands:


 * You now you should have a build of Moondust!

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)
 * CMake >= 3.5 (You can download it here: https://cmake.org/download/ or install it with command brew install cmake)

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 "coreutils", "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 recommend you to choose 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 error with missing headers which is a small bug which forces you 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:

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

"High Sierra" with XCode 8

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

Static version of Qt
If you don't want to have trouble with frameworks and dependent dynamic libraries, we are recommending to build a static version of Qt yourself. Here is a detailed manual on how to build a 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 (The 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 the environment and save the file with CMD+O

Building code
To build a project using the special build.sh script:

./build.sh

When everything will be built, you will see the built app bundles in the ./build-pge-cmake-release/bin folder.

To start the usage of the editor, run the Moondust Editor.app file

Deploying of built stuff
If you wish to make a DMG image to use your build on other computers without rebuilding, you can run the "build.sh" script with the "deploy" argument:

When the deploy script will finish its job, you will get the "bin-cmake-release/pge-project-dev-macosx.dmg" file which you can share with friends or use on another computer yourself.

Building Moondust Engine for Android
For now, Moondust Engine only can be built for the Android platform.

Dependences

 * Most recent Android Studio (NOT available in China!) 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 are able to open the project you need to initialize it: open the terminal (or Git Bash if you running on Windows) and change the current directory into ` /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 can run it.

Building code
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 manually placing it into the device and installing it 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, the 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, it seems you forgot to download submodules.

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

Merge conflicts
The reasons for merge conflicts are: If you have any troubles with merge conflicts in case you didn't make any changes and you can't resolve it, just re-clone the repository
 * You have committed some changes to some lines which also changed the pulling state
 * You have a folder which has been turned into a submodule, but you still have it as part of the Moondust repository. Delete it and try to pull it again. If you still have an error, try to re-clone the 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 `./build.sh clean` or `build.bat clean` (dependent on the operating system) scripts in the root of the repository

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

Any "undefined reference" error while linking
This error means that some of the dependencies are built incorrectly and lack some of the functions, external variables or classes. 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
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 been built yet. However, you have a solution: at first, you need to build dependent libraries as the separate target: Or

At a moment when all libraries will be built, you'll be able to compile the project:

Or

Which platform version is supported? (Windows, macOS, Linux, Android)
Any non-Qt components support as minimal platforms as possible they can (Windows XP and macOS 10.7). Qt with newer versions gradually drops support of old platforms: Platforms supported by Qt. To support certain older platforms, 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 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 the old platform with the latest Qt in this case you will compile all required dependencies from sources using the modern compiler (GCC 6+ or CLang 4+, C++11 required, C++14 is recommended).
 * For the case of macOS, you will need to use a specific Qt version to support older macOS platforms. You still can use the latest XCode to produce working binaries. You should be sure to specify a minimal macOS version to get the complete deployment working on the older platforms.
 * Minimal Android version support is dependent on a version of SDK. With the newer version of SDKs, the minimal Android version is increasing. If you want to deploy to an old platform, you should use an older SDK.