History: Building Mogre 1.7 Step By Step

Source of version: 15 (current)

!Building Mogre 1.7 step by step
This page describes the process of building Mogre step by step from source.
Written by McDonte in Septemer 2011.

{maketoc}

!!Paths And Directories
In this guide Mogre is build in the directory "C:\Mogre". You can change the folder without problems but then you also have to adapt every path later on.

!!Ogre With Or Without Mogre?
You will see that Ogre needs to be built twice, once with Mogre once without. To make this process as easy as possible there is the file "CLRConfig.h":
{CODE()}#pragma once

#define LINK_TO_MOGRE 1

#if LINK_TO_MOGRE
#ifdef _DEBUG
#pragma comment(lib, "../../../lib/Debug/mogre.lib")
#else
#pragma comment(lib, "../../../lib/Release/mogre.lib")
#endif
#endif{CODE}
By setting the directive "LINK_TO_MOGRE" to "1" Ogre is told to inlcude Mogre. You do not need the change anything in the project properties only this line. Before we can compile Mogre we need Ogre without Mogre, so we set "LINK_TO_MOGRE 0". When we compiled Mogre we go back to Ogre and now we need to compile it again but now with Mogre link: "LINK_TO_MOGRE 1".

But do not care about it yet. We will tell you when you have to switch the Mogre linking on and off.

!!Requirements
The process of building Mogre requires some tools and programs listed here:

!!!TortoiseHg (optional)
{QUOTE()}TortoiseHg is a Windows shell extension and a series of applications for the Mercurial distributed revision control system. It also includes a Gnome/Nautilus extension and a CLI wrapper application so the TortoiseHg tools can be used on non-Windows platforms.{QUOTE}
__TortoiseHg__ is used to grab the sources from a repository on the web. You can easily check out branches from a repository and update an already existing copy on your computer. It is not needed necessarily for the build because you can also get the sources within a simple archive and then extract them to your working directory but Ogre and Mogre building instructions always recommend to use it. __TortoiseHg is free and can be downloaded__ [http://tortoisehg.bitbucket.org/|here]. __Note:__ There are different versions for x86 and x64 systems!

!!!!Usage
Start cmd.exe. Now you have to execute hg.exe with some parameters. The combination of parameters you will use the most looks like this:
{CODE()}hg.exe clone repository -u branch directory{CODE}
*''repository = the URL of the repository''
*''branch = the name of the branch you would like to download''
*''directory = the directory on your local hard drive you want the files to be downloaded to''
!!!!Notes
*__Repository:__ You can get the URL of the repository by visiting the bitbucket site of the project. It is usually a "http" or "https" address.
*__Branch:__ Every time the developers of Ogre and Mogre are making changes to the sources they upload it to make it available to the users. To preserve the previous version they can choose to create separate branches. This is usually not done for every update but for big changes or experiments (for example there are branches for Ogre 1.6 and Ogre 1.7, but also for 1.7.0, 1.7.1 and so on).
*__Directory:__ I recommend to use absolute paths to make sure where your files are placed.
*__Parameters:__ A list and description of all parameters can be found [http://www.selenic.com/mercurial/hg.1.html|here].
!!!CMake
{QUOTE()}__CMake__, the cross-platform, open-source build system. CMake is a family of tools designed to build, test and package software. CMake is used to control the software compilation process using simple platform and compiler independent configuration files. CMake generates native makefiles and workspaces that can be used in the compiler environment of your choice.{QUOTE}
__CMake__ is used to generate the Visual Studio projects to build Ogre. By configuring CMake you can customize your build of Ogre/Mogre for example by selecting additional RenderSystems or Plugins. __CMake is free and can be downloaded__ [http://www.cmake.org/|here].

!!!!Usage
CMake is usually started as an interface application, by default start C:\Program Files\CMake 2.x\bin\cmake-gui.exe. You can also run it via the commandline therefore use the cmake.exe in the same folder with the following parameters:{CODE()}cmake.exe -D arguments -G "CompilerName" sourceDirectory{CODE}
*''arguments = a list of configuration options'' {QUOTE(replyto="CMake Help")}When running cmake from the command line, it is possible to specify command line options to cmake that will set values in the cache. This is done with a -DVARIABLE:TYPE=VALUE syntax on the command line. This is useful for non-interactive nightly test builds. {QUOTE}
*''CompilerName = the name of the compiler you want to use later on (full list [http://www.cmake.org/cmake/help/cmake-2-8-docs.html#section_Generators|here])''
*''sourceDirectory = the directory where the sources are located you want the project files for''
!!!!Notes
If you are using the graphical interface then check the "Advanced" box.

If you are using the command line version run it from the directory where you want your build files to be generated.

!!!Cpp2java (included)
__Cpp2java__ is a small command line tool that extracts information from C++ sources into XML files. Therefore it runs DoxyGen, configured to output the structure of the Ogre classes and structs in an XML format. The XML is then massaged  into a format understood by the next tool, AutoWrap.
__Note:__ If your Ogre sources are not located at the default "Main\OgreSrc\ogre" then you have to change the paths in the "ogre4j.doxygen" file:
{CODE()}INPUT                  = "../../Main/OgreSrc/ogre/OgreMain/Components/Terrain/include" \
                         "../../Main/OgreSrc/ogre/OgreMain/Components/Paging/include" \
                         "../../Main/OgreSrc/ogre/OgreMain/include" \
                         "../../Main/OgreSrc/ogre/OgreMain/include/WIN32" \
                         "../../Main/Ogre"{CODE}

Related links: [http://www.texttransformer.com/Cpp2Java_en.html|Cpp2java], [http://www.stack.nl/~dimitri/doxygen/|Doxygen], Wikipedia page of [http://en.wikipedia.org/wiki/Doxygen|Doxygen]

!!!AutoWrap (included)
__AutoWrap__ is a C# application. It will generate C++/CLI wrappers for all of the classes in the public Ogre headers. There is no need to configure anything because the program assumes that the needed files are all in place. The only action the user has to do is clicking on "Produce".

!!!Microsoft Visual Studio
Not only to develop your application but also for the building process you need Visual Studio installed. Express versions are absolutely adequate.
There are free versions (called [http://www.microsoft.com/visualstudio/en-us/products/2010-editions/express|"Express"]) and paid versions (called [http://go.microsoft.com/fwlink/?LinkID=186896|"Ultimate"], [http://go.microsoft.com/fwlink/?LinkID=186894|"Premium"] and [http://go.microsoft.com/fwlink/?LinkID=186892|"Professional"]). An overview can be found [http://msdn.microsoft.com/en-us/vstudio/aa718325|here].

!!Useful Resources
If you would like to understand the internal working of the wrapping process then these links could be useful for you.

!!!C++/CLI
{QUOTE(replyto="Microsoft")}In short, it is how you do .NET programming using C++ rather than C# or Visual Basic.{QUOTE}
C++/CLI is a language specification by Microsoft to provide the possibility to develop managed applications in C++. It is used to provide the native Ogre classes to be accessed by managed code.
Some references:
* [http://en.wikipedia.org/wiki/C%2B%2B/CLI|Wikipedia: C++/CLI]
* [http://msdn.microsoft.com/en-us/magazine/cc163681.aspx|Microsoft Article: Pure C++: Hello, C++/CLI]
* [http://www.functionx.com/cppcli/index.htm|Many tutorials]
* [http://www.codeproject.com/KB/mcpp/#C%2b%2b%2fCLI|Articles on Codeproject]

!!Build
!!!Get Mogre Sources
First the Mogre sources have to be downloaded. This can be either done with TortoiseHg or manually.

For TortoiseHg the command is:
{CODE()}hg.exe clone http://bitbucket.org/mogre/mogre -u Mogre17 C:\Mogre{CODE}

Here we are downloading the branch "Mogre17", you could alternatively also write "TerrainAndPaging" if you want to use the new Terrain and Paging components (Alpha in September 2011).

!!!Get Ogre Sources
Now we need the Ogre sources.

{CODE()}hg.exe clone http://bitbucket.org/sinbad/ogre -u 58266f25ccd2 C:\Mogre\Main\OgreSrc\ogre{CODE}

__58266f25ccd2__ is the internal name of the branch we are downloading.

!!!Mogre Patch
We need to apply a patch onto the Ogre sources we just grabbed. This adds some fields into public Ogre classes that will be used by Mogre to look up the managed wrappers. So when the Ogre API returns some object, like a texture, for which a managed wrapper already exists, Mogre can just look it up and return the existing wrapper.

The patch file is found here: __"C:\Mogre\Main\Ogre Patches\58266f25ccd2.patch"__. As you can see the patch is related to the Ogre version we downloaded. If you are using a patch for example for Ogre 1.7.3 and apply it onto Ogre 1.7.0 sources you will get some error messages. This is not always a problem because sometimes a patch is related to changes that are not yet made to the used sources.

!!!!Applying The Patch
Applying a patch can be done in three ways:
#Using TortoiseHg: Using the graphical interface is probably easiest. A description how to do can be found [http://tortoisehg.bitbucket.org/manual/2.0/patches.html#import-patches|here].
#Using the patch.exe tool from GnuWin (look [http://gnuwin32.sourceforge.net/packages/patch.htm|here]): With this tool you can simply apply the patch via the commandline. Place the tool in your working directory and then call it like this:{CODE()}patch.exe -p0 < C:\Mogre\Main\Ogre Patches\58266f25ccd2.patch{CODE}
#Applying the patch manually: Actually you can apply every patch also manually by editing the source files. The .patch file contains only the changes between two versions. __Note:__ This method is only useful if you are having heavy troubles applying the .patch file or you want to do your own changes.
!!!!Creating Own Patches
This can easily be done with TortoiseHg: [http://tortoisehg.bitbucket.org/manual/2.0/patches.html#export-patches|export].

!!!Download, Extract And Build The Dependencies
Ogre makes use of some other libraries that are not included in the official repository but are provided as separate archives. The sourceforge page with all downloads for Ogre 1.7 are [http://sourceforge.net/projects/ogre/files/ogre-dependencies-vc%2B%2B/1.7/|here]. There are different versions of the dependencies but since they are compiled on their own only big interface changes affect Ogre. So usually there is no difference which version of the dependencies you are using.
__Note:__ If you are building Mogre more than once it is worth to download the dependencies only once and have a directory with the compiled binaries for every Ogre/Mogre build you are doing later.

For this guide you can download [http://surfnet.dl.sourceforge.net/project/ogre/ogre-dependencies-vc%2B%2B/1.7/OgreDependencies_MSVC_20100501.zip|this archive]. After the download is finished extract it to "C:\Mogre\Main\OgreSrc\ogre" so a folder "Dependencies" is created.

__For VS2008__, open the dependencies solution file "C:\Mogre\Main\OgreSrc\ogre\Dependencies\src\OgreDependencies.VS2008.sln" in Visual Studio.
__For VS2010__, open the dependencies solution file "C:\Mogre\Main\OgreSrc\ogre\Dependencies\src\OgreDependencies.VS2010.sln" in Visual Studio.

Go to "Build" and then "Batch Build" to create all projects in the solution. __Note:__ You can choose if you want to compile only Win32, only x64 or both. Of course you will need to compile Ogre and Mogre for the same platform as you compiled the dependencies for later on.

!!!!ITERATOR_DEBUG_LEVEL Error
This error was first described by sinbad [http://www.ogre3d.org/forums/viewtopic.php?f=1&t=54533&start=100#p388654|here]. The error comes up when a release library is linked to debug libraries. Unfortunately it seems there is a bug in Visual Studio because the Project "FreeImageLib" links both in debug and release configuration to the debug libraries of the other image plugins.

The solution of this error is actually simple:
__Note:__ If you do not use different names for debug and release libraries then you should select "Configuration: All Configurations" before doing these changes so you have to do it only once.

Select the "FreeImageLib" project rightclick on it and select Properties. On the left side select the first entry "General Settings" and remove all references. __Note:__ There are only references to projects in this solution.

Now select "Librarian" and set "Link Library Dependencies" to "No".  Then select "Additional library directories". Add the following lines to it:
{CODE()}C:\Mogre\Dependencies\src\FreeImage-3.13.1\Source\LibJPEG\$(Configuration)
C:\Mogre\Dependencies\src\FreeImage-3.13.1\Source\LibMNG\$(Configuration)
C:\Mogre\Dependencies\src\FreeImage-3.13.1\Source\LibOpenJPEG\$(Configuration)
C:\Mogre\Dependencies\src\FreeImage-3.13.1\Source\LibPNG\$(Configuration)
C:\Mogre\Dependencies\src\FreeImage-3.13.1\Source\LibRawLite\$(Configuration)
C:\Mogre\Dependencies\src\FreeImage-3.13.1\Source\LibTIFF\$(Configuration)
C:\Mogre\Dependencies\src\FreeImage-3.13.1\Source\OpenEXR\$(Configuration){CODE}
Now select "Librarian" and "Additional Dependencies". Add the following lines:
{CODE()}LibJPEG.lib
LibMNG.lib
LibOpenJPEG.lib
LibPNG.lib
LibRawLite.lib
LibTIFF.lib
OpenEXR.lib{CODE}
Now you can compile your dependencies without getting this error. Since only the linking process is concerned use a rebuild for "FreeImageLib" release, because the source code did not change.

!!!Running CMake
In this guide it is recommended to use the interface because it is much more convenient to use. For building the Ogre build files configure CMake like this:
#Use "C:\Mogre\Main\OgreSrc\ogre" as source directory.
#Target "C:\Mogre\Main\OgreSrc\build" as output directory for CMake.
Click "Configure" and select either "Visual Studio 9 2008" or "Visual Studio 10" as cmake project type. For x64 builds you have the same generator name only with a "Win 64" postfix.
Now a list is generated with all options that can be configured to customize your build. Most of them are absolutely unimportant to you, but make sure you have OGRE_CONFIG_ENABLE_PVRTC switched ON and OGRE_CONFIG_CONTAINERS_USE_CUSTOM_ALLOCATOR switched OFF. Generally spoken all entries with "OGRE_" prefix could be interesting to you. Now you can select the RenderSytems and the plugins you want to have.

__Note:__ I advise you to disable the Ogre Samples if you don't need them. Besides of that you can consider to change "CMAKE_CONFIGURATION_TYPES" to "Debug;Release" because the other two configurations are not needed anyway.

!!!Run Cpp2java
Go to folder "C:\Mogre\Codegen\cpp2java" and execute "build.bat" in this folder. It's a batch file that will call the doyxgen with the prepared settings. You have two wait some minutes until all files are generated.

!!!Build And Run AutoWrap
__For VS2008__, open solution "C:\Mogre\Codegen\AutoWrap\AutoWrap.sln" in Visual Studio and compile the Debug configuration.
__For VS2010__, open solution "C:\Mogre\Codegen\AutoWrap\AutoWrap_vs2010.sln" in Visual Studio and compile the Debug configuration.

__Note:__ You do not need the Release build because the tool is only called once and does the job, doesn't matter which configuration.

Execute "AutoWrap.exe" in folder "C:\Mogre\Codegen\AutoWrap\bin\Debug" and press button "Produce". You can now see the process bar and have to wait until it's completed. Then click ok and close the program.

!!!Copy Some Files
Go to folder "C:\Mogre\Main\Ogre" and execute "copy_to_ogre.bat" in this folder. It will copy all source files in the folder to the Ogre include and source directory ("C:\Mogre\Main\OgreSrc\ogre\OgreMain\include" and "OgreMain\source"). You can also consider doing it manually, it does not make any difference.

Now copy the file "C:\Mogre\Main\include\auto\CLRObjects.inc" to folder "C:\Mogre\Main\OgreSrc\build\include". There are all classes store that need a CLR object.

!!!First Ogre Build
We need to build Ogre twice once without once with Mogre. Mogre itself needs Ogre already compiled so some building steps will be needed to be done twice.

Open the Visual Studio solution "OGRE.sln". __Note:__ There is only one version for both VS 2008 and VS 2010 because this file has been generated by CMake so it is what you specified as your desired compiler.

In the solution explorer window of Visual Studio, find the project "OgreMain" and right click it. Select "Add->Existing Item..." and navigate to "C:\Mogre\Main\OgreSrc\ogre\OgreMain\include", add "CLRConfig.h", "CLRHandle.h" and "CLRObject.h". Now select "Add->Existing Item..." and navigate to "Mogre\Main\OgreSrc\ogre\OgreMain\src", add "CLRHandle.cpp" and "CLRObject.cpp".

Open "CLRConfig.h" in Visual Studio and change "#define LINK_TO_MOGRE 1" to "#define LINK_TO_MOGRE 0". This is done because we need an Ogre library to compile Mogre.

Now click "Build->Batch Build" and select "Debug|Win32" and "Release|Win32" for the following projects:
*OgreMain
*OgrePaging
*OgreTerrain
Rebuild all selected projects. VisualStudio will compile these projects and this will take some time.

!!!!ITERATOR_DEBUG_LEVEL Error
Some people are experiencing a lot of these errors when compiling the Release configuration of OgreMain. The solution for this problem is described above at the Dependencies section.

!!!Build Mogre
Now finally we are dealing with Mogre itself.

__For VS2008__, open solution "C:\Mogre\Main\Mogre_vc9.sln" in Visual Studio.
__For VS2010__, open solution "C:\Mogre\Main\Mogre_vs2010.sln" in Visual Studio.

Use batch build to rebuild all projects.

!!!Second Ogre Build
Open solution "C:\Mogre\Main\OgreSrc\build\OGRE.sln" again. Open "CLRConfig.h" again and change "#define LINK_TO_MOGRE 0" back to "#define LINK_TO_MOGRE 1".

Now select all projects in batch build except "ALL_BUILD", "INSTALL", "PACKAGE". Use rebuild to save a lot of time, sine OgreMain only has to do the linking part.

!!!Result
The __Debug binaries__ are in "C:\Mogre\Main\lib\Debug" and "C:\Mogre\Main\OgreSrc\build\lib\Debug".
The __Release binaries__ are in "C:\Mogre\Main\lib\Release" and "C:\Mogre\Main\OgreSrc\build\lib\Release".

!!Mogre.Builder
There are intentions to develop a tool that is doing automatically the whole build process. So far there are no results but you can follow the discussions [http://www.ogre3d.org/addonforums/viewtopic.php?f=8&t=14021|here].

!!See also
* [http://www.ogre3d.org/addonforums/viewtopic.php?f=8&t=14817|Understanding the Mogre build process] (forum topic)
* [https://bitbucket.org/mogre/mogre/src|Documentation] - directory in the Mogre sources
* ((MogreBuilder)) - easy building of Mogre
History: Building Mogre 1.7 Step By Step

Source of version: 15 (current)

Search by Tags

Latest Changes

Search

Online Users
