BlackTopp Studios inc
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.
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.
Here is an example of similar commands on Linux:
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 , 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.
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:
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.
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.
In the graphical version these appear as series of checkboxes, in the command line version you can use the “-D” flag to set these:
Here are some of the advanced features:
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.
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.
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:
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:
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:
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:
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
You might want to disable an option, or use multiple. Here is an example of enabling debug support and disabling DirectX 11.
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.
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.
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.
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.
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:
On windows:
On any OS with ninja installed:
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:
On windows:
On any OS with ninja installed:
The are a ton of waystis can fail, here are some.
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.
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.
Then any time you compile the engine you won’t get anymore warnings for these bugs in the Ogre build process.
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:
This has only been experience on Ubuntu and installing the Mesa GL headers fixes it:
1.8.9.1. Thanks to the
Open Icon Library
for help with some of the icons.
