Building the Engine
Build Tools
First thing you will want to do is get the right tools for building and working with the Mezzanine Engine. We have pages for each supported platforms tool set, pick the appropriate set for your uses: Linux development tools, Mac OS X Tool or Windows dev tools.
If you are planning on developing software too it may be a good idea to install a copy of Code::Blocks, QT Creator or another IDE (Integrated Development Environment). You can use any IDE you like, but if you want to ask us IDE questions we will only have answers for the ones we have used. On Mac OS x you will probably want to use xcode
Get the Source Code
From a command prompt you can run a few commands to get a copy of the source on your workstation. If you are using windows you could use the git bash prompt, and on Mac OS or Linux the normal terminal or bash prompts should work. If you are using some graphical tool the steps are the same, but you will have to figure out how to make the software you use perform them.
These commands if copied verbatim on windows will navigate to your C: Drive and create a folder called “Mezzanine” with the source code in it. The actual commands you will type are in italics/highlighted. You can change “c:” to a directory of your choice, such as your desktop or documents folder. You will have to change it if you are not using windows. One thing to note is that one of the linker’s used, windres.exe, does not like spaces in the paths that are passed to it. If you place the Mezzanine repo in a path that has a space in one of the folder names your compile will fail. Avoid paths with spaces in directory names. I.E., a folder named “Documents/Mezzanine” will be ok, but “My Documents/Mezzanine” will fail during compilation.
dev@DEV-PC ~
$ cd c:
dev@DEV-PC /c
$ git clone git://github.com/BlackToppStudios/Mezzanine.git
Cloning into Mezzanine...
remote: Counting objects: 117277, done.
remote: Compressing objects: 100% (51597/51597), done.
remote: Total 117277 (delta 65098), reused 114360 (delta 62444)
Receiving objects: 100% (117277/117277), 572.91 MiB | 1.60 MiB/s, done.
Resolving deltas: 100% (65098/65098), done.
Here is an example of similar commands on Linux:
sqeaky@Tachyon:~$ mkdir projects
sqeaky@Tachyon:~$ cd projects/
sqeaky@Tachyon:~/projects$ git clone git://github.com/BlackToppStudios/Mezzanine.git
Cloning into 'Mezzanine'...
remote: Counting objects: 117277, done.
remote: Compressing objects: 100% (51597/51597), done.
remote: Total 117277 (delta 65102), reused 114356 (delta 62444)
Receiving objects: 100% (117277/117277), 572.90 MiB | 1.94 MiB/s, done.
Resolving deltas: 100% (65102/65102), done.
Git URLs
There are a few places and ways you can download the source code. The ones that provide “read only” access refer only to the ability to upload to changes. With any of these methods you can make as many changes as you like to the copy on your machine:
- git://github.com/BlackToppStudios/Mezzanine.git – For read only access
- git@github.com:BlackToppStudios/Mezzanine.git – For read/write access we have given you access on github
- git://gitorious.org/physgame/physgame.git – Read only access to the backup
- git@gitorious.org:physgame/physgame.git – Read/write access to the backup
- http://git.gitorious.org/physgame/physgame.git – Read Only
The “git://”, “https://” and “http://” URLs will work with no extra configuration. To a URL that starts with “git@, an SSH URL, you will need to sign up with Gitorious or https://github.com/, setup an RSA-Keypair, and upload your public key to their site. See the Gitorious FAQ or Git setup page for more info, and be certain that the RSA fingerprint matches if it asks you. Additionally to upload changes a BTS administrator will have to give you permissions on Github to contribute.
Once you have cloned the Mezzanine repository (or physgame repository if from the older gitorious backup) the URL setting is stored in “.git/config” and it can be changed with any text editor. The “.git” folder is hidden by default.
You can also download a zip archive of the source from https://github.com/BlackToppStudios/Mezzanine/. You may have to adjust certain steps if this is the case.
Dependencies
After you get the source code there may be some steps you need to take to get any software the Mezzanine engine depends on installed and configured. Please take a look at any appropriate steps for your platform: Linux libraries, Mac OS X libraries or Windows libraries.
Building the Shipped Dependencies
In the past this was a significantly complex procedure, more recently almost all of ourp dependencies have been integrated tightly. Ogre, SDL, Bullet3d and a few others are all built during the CMake build process.
The Mezzanine source ships with a copy of SDL and Ogre3d (and a few other) libraries source code that are used internally by it. You won’t need to use these unless you are making advanced changes to the Mezzanine, but they will need to be compiled.
Using CMake
Cmake will create a set of project files that will tell the compiler how to compile the source you just downloaded. The steps listed here assume that you have the source files in “c:\Mezzanine\” and want to have your compiled binaries in “c:\Mezzbuild\”. There are a couple of way to do this. You can use the graphical Cmake program or the command line tool.
The Options
In the graphical version these appear as series of checkbox, in the command line version you can use “-D” to set these:
- Mezz_Debug – Enables Debuging symbols in the Mezzanine library and enable extra logging mesage. Defaults to false.
- Mezz_Lua51 – Enable/Disable the whole Lua system. Defaults to true/enabled.
- Mezz_Network – Enable Networking support. Defaults to true.
- Mezz_BuildRenderSystemDirectX9 – This controls support for DirectX 9 a common RenderSystem on all microsoft operating systems. This is experimental.
- Mezz_BuildRenderSystemDirectX11 – Controls support DirectX 11 a more advanced RenderSystem only available on newer microsoft operating systems. This is experimental.
- Mezz_BuildRenderSystemOpenGL – This is default Render system on Windows, Linux and Mac OS X
- Mezz_BuildRenderSystemOpenGLES – Experimental, this is the render that will be used on some mobiles platforms
- Mezz_BuildRenderSystemOpenGLES2 – Experimental, this is the render that will be used on some mobiles platforms
Here are some of the advanced features:
- Mezz_Profile – Enable compiler level profiling support. Defaults to false.
- Mezz_ForceBuildType – Forces The CMake build type to match the Mezz_Debug flag, useful if you to not have debug symbols but want the extra logging Mezz_Debug enables.
- Mezz_ThrowOnSingletonFetch – Controls whether getting a singleton when it is invalid throws or returns null.
- Mezz_UseOgreVersion – This must be set to match the Ogre3d version if you want to use one not integrated you will need to adjust this.
CMake option Caveats
Currently the Mezz_Profile cmake flag does not work on windows, and will give errors while trying to compile it. Avoid enabling it.
Mezz_XML Has been deprecated and removed. The XML system is central to many other features, and maintaining this option takes too much time for the value it adds.
Graphical Tool
First thing to do is open Cmake. The default installation in windows should have put a Cmake icon on you desktop, and another in your start menu. In Ubuntu (and most other modern Linux distributions) when you install “cmake-gui” an entry will be made in the KDE or Gnome menu. Use that icon or menu entry to start it.
The first box at the top of the screen is called “Where is the source code:”. Select the folder using the “Browse Source” button, or manully type in “c:/Mezzanine”. The next box asks “Where to build binaries:” enter “c:/Mezzbuild”. After that click the configure button in the lower left corner. This will prompt you for what kind of project files to make. If you just want to build the engine and not work with it’s source directly select “Unix Makefiles” or “MinGW Makefiles”, if you do directly want to work with the source code select “Codeblocks – Unix Makefiles” or “Codeblocks – MinGW Makefiles”. When you click finish on this screen Cmake will have figured out most of the information it needs to make the files.
The last information required before creating project files is any options you want to select. Read below about “The Options” then click “Configure” again after you have made your choice. Then click “Generate” to actually make the project files.
Command Line Tool
There are a few different options when using CMake from the command line. Ideally this should be run from the directory the compiled binaries are desired in, this is called the build directory. Cmake should be passed the directory with the Mezzanine repository. On Linux, but otherwise similar to our previous example, you could:
cmake ../Mezzanine/
When run from windows it might look the same if run from a Git bash prompt, or it could like the following if run from a DOS prompt:
cmake ..\Mezzanine\
Generators
There are many kinds of files CMake can output. The way you select these are by passing cmake a generator. Most commonly we will recommend Makefiles or Codeblocks project files. There are several other kinds of files available for creation, but they are beyond the scope of this document. The most common generators we use are:
On Linux:
- CodeBlocks – Unix Makefiles
- Unix Makefiles
On Windows:
- Codeblocks – MinGW Makefiles
- MinGW Makefiles
These can be entered with the “-G” switch (also called an argument) for example:
cmake ../Mezzanine/ -G"CodeBlocks - Unix Makefiles"
Entering options
All of the options listed above can be entered with the “-D” switch. After the name of the name of the option you need to include either “:boolean=true” or “:boolean=false”, for example:
cmake ../Mezzanine/ -G"CodeBlocks - Unix Makefiles" -DMezz_Debug:boolean=true
Game Developers will probably want the default options, which leave Profiling support and Debugging support off, but enables XML parsing support. If you know for a fact you do not want XML parsing use:
cmake ../Mezzanine/ -G"CodeBlocks - Unix Makefiles" -DMezz_XML:boolean=False
If you read the output of cmake carefully, it will tell you what is enabled or disabled in plain English. With messages being similar to “MezzanineAndCatch – Enabling XML subsystem, object serialization to XML, and Mezz_XML” or “MezzanineAndCatch – Disabling XML subsystem, object serialization to XML, and Mezz_XML”.
If you are an Developer you will probably want to enable profiling and debugging support in the engine using something similar to:
cmake ../Mezzanine/ -G"CodeBlocks - Unix Makefiles" -DMezz_Debug:boolean=true -DMezz_Profile:boolean=true
Compiling the Engine
Once you have your project files or makefiles you can compile the engine. There are two way to do this. People interested in the engine code can use the Code::Blocks IDE to compile the engine (Engine Developers and some Game Developers). People who aren’t interested in engine code can use make (some Game Developers, People installing the engine and Package Maintainers)
This can take anywhere from 10 seconds to 45 minutes depending on the speed of your computer. Various netbooks have taken between 30 and 45 minutes for a fresh compile all build targets, and 20 seconds to 90 seconds for a partial compile of one build target that uses the Mezzanine. Our i7 machine took around two minutes for a full build and less than a second for a partial build.
Code::Blocks
All you have to do is open Code::Blocks by double clicking on the “MezzanineAndCatch.cbp” icon in your build directory, selecting the Build Target you want to build, and finally clicking on the green gear to compile.
To speed this up or better understand the process here is a little more information that might be useful.
Configuring for Multiple CPUs
When Code::Blocks is already open you can go to the “Settings” menu and select “Compiler and Debugger”, which will open a screen with a “Build Options” tab (you may need to scroll left or right to see it), which will have the “Number of parallel builds” option. This should be set to on or around the amount of hardware threads (CPUs + hyperthreading cores) your computer supports. On our i7 it is set to 9 and on the netbooks it was set to two or three.
In an IDE that uses make for the build process, you just add an argument in the menu that defines how make is called. In QT Creator, for example, you can configure it “-j9″ for nine compilation thread, in the “Projects” Sidebar in the “Build Steps” section. You can use any amount of threads that you see fit, try numbers around the amount of “Cores” your CPU provides.
Build Targets
There are many build targets to choose from, here is a brief synopsis of the interesting ones.
- All – Builds Everything
- Mezzanine – The engine and what it requires
- Catch – Just the Catch game and the engine if the files present aren’t current
- UnitTests – the Testing suite and the engine if the files present aren’t current
- EngineDemo – A simple Engine Demo and the engine if the files present aren’t current
- */fast – Builds whatever * is, but skips any checks of the engine
- Anything else – A component of the engine
Common Issues with CMake
One windows, if CMake complains about finding “sh.exe” in the system path then you will need to edit the system path variable to remove “c:\program files\git\bin” from your PATH. See above for instructions on Editing your PATH variable.
Make
If you open a Git Bash prompt on a window, or terminal on Mac OS X or Linux, then cd to your build directory and enter the “make” command, you have started the engine compiling. (This only works if using GCC, MinGW or Clang compilers)
This runs slightly faster than a compilation from Code::Blocks, but not by much. The easiest way to speed this up is to tell make to use multiple thread to perform the compilation. This can be done with the “-j” switch, and the number of threads you want to run. The following example will run the compilition in 4 threads which would be suitable for a typical quad-core machine:
make -j4
Compilation Issues
Ogre Little Endian issue
If you get the following warning, there is a workaround. This seems to have stopped happening since the release of the 1.7 branch of cmake.
libincludes/linux/ogresrc/include/OgreBuildSettings.h:19:1: warning: "OGRE_CONFIG_LITTLE_ENDIAN" redefined
: warning: this is the location of the previous definition
Then you could remark our one of those definitions like this one on line 19 of OgreBuildSettings.h. Double click on the warning message in the Messages Window which is at the bottom of Code::Blocks by default.
#define OGRE_CONFIG_LITTLE_ENDIAN
All you need to do is change the line like this:
//#define OGRE_CONFIG_LITTLE_ENDIAN
Then any time you compile the engine you won’t get anymore warnings for these bugs in the Ogre build process.
Rendersystem copy errors
Sometimes it is possible for Ogre to skip building a rendersystem, but not to let you know in a clear way. In general this happens if it have been tricked into compiling against a software open renderer. The Error looks something like:
Preparing File: /home/sqeaky/Projects/MezzanineCurrent/Build/Mezzanine/bin/data/linux/ogre/RenderSystem_GL.so
Error copying file (if different) from “/home/sqeaky/Projects/MezzanineCurrent/Mezzanine/Mezzanine/data/linux/ogre/RenderSystem_GL.so” to “/home/sqeaky/Projects/MezzanineCurrent/Build/Mezzanine/bin/data/linux/ogre/RenderSystem_GL.so”.
Installing libgles1-mesa-dev corrects that.
sudo apt-get install libgles1-mesa-dev
Please be patient as we complete this page.
The instructions provided will produce a working set of the Mezzanine binaries, but does not explain how to use them or where to find them.