Spinning Topp Logo BlackTopp Studios
inc
Building the Mezzanine 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:

And be sure you have any optional dependencies installed that you want or need

If you are planning on developing software too it may be a good idea to install a copy of Code::blocks IDE , 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:


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.

Gitorious is dead

Gitorious , the original hosting site for BTS source code seemed to be non longer functional at the time of this writing. For historic interest here are the old links to those repositories.

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:

Building the Shipped Dependencies

In the past this was a significantly complex procedure, now almost all of our 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 itself, but they will need to be compiled. This will be handled automatically as part of the main source build process.

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.

CMake Options

In the graphical version these appear as series of checkboxes, in the command line version you can use the “-D” flag to set these:

Advanced CMake Options

Here are some of the advanced features:

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 on windows.
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 or Unity panel. Use that icon or menu entry to start it or use "cmake-gui" from a terminal.
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 ways to use 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\\

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


On Windows:


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.

If you read the output of cmake, it will tell you what is enabled or disabled in plain English. With messages being similar to

-- MezzanineAndCatch - Disabling gcc profiling and unsetting MEZZPROFILE
-- MezzanineAndCatch - Enabling Network subsystem, and setting MEZZNETWORK
-- MezzanineAndCatch - Enabling Support for Lua Scripting Language, and setting MEZZLUA51
-- MezzanineAndCatch - Disabling Support for Ruby Scripting Language, and unsetting MEZZRUBY
-- MezzanineAndCatch - Disabling Swig execution each build.
-- MezzanineAndCatch - Enabling EntreLua build.

You might want to disable an option, or use multiple. Here is an example of enabling debug support and disabling DirectX 11.

cmake ../Mezzanine/ -G"CodeBlocks - Unix Makefiles" -DMezz_Debug:boolean=true -DMezz_BuildRenderSystemDirectX11:boolean=false

Common Issues with CMake

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

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 or ninja from a command line (some Game Developers, people installing the engine and Package Maintainers)


This can take anywhere from 10 seconds to a couple of hourse 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.

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

Code::Blocks and 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 threads, 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 with Command Line

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 examples will run the compilition in 4 threads which would be suitable for a typical quad-core machine:


On Linux or Mac OS X:

make -j4


On windows:

mingw32-make -j4


On any OS with ninja installed:

ninja -j4

Build Targets

There are many build targets to choose from, here is a brief synopsis of the interesting ones.


In Code::Blocks you can just select these from the build menu, from the command prompt you can add these to the end the build command to build just one target. For example these will all build the EngineDemo and only what it requires (So it won't build Catch!):


On Linux or Mac OS X:

make -j4 EngineDemo


On windows:

mingw32-make -j4 EngineDemo


On any OS with ninja installed:

ninja -j4 EngineDemo

Compilation Issues

The are a ton of waystis can fail, here are some.

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

You could remark our one of those definitions like this one on line 19 of OgreBuildSettings.h. Double clicking on the warning message in the Messages Window which is at the bottom of Code::Blocks will open the file to the error 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 does 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”.

This has only been experience on Ubuntu and installing the Mesa GL headers fixes it:

sudo apt-get install libgles1-mesa-dev