Building CEGUI for Ogre / OgreRenderer

2015-02-13T11:26:18Z

Underworldguardian: Added the most straight-forward way to compile a cmake project.

{{VersionBadge|0.7}}
{{VersionBadge|0.8}}

= General =
Since Ogre version 1.7 the CEGUI library isn't an Ogre dependency anymore and was replaced by a very simple UI overlay mainly used for the Ogre demos. Users now have to compile the CEGUI library against Ogre on their own, to use CEGUI together with Ogre. This guide has been created to help users building CEGUI against Ogre. We recommend CMake 2.8.X for all version of CEGUI at the moment.

== Tested versions ==
* CEGUI 0.8 supports basic configurations of Ogre 1.7 and 1.8 and 1.9. Other versions and special configurations (such as using boost) are supported but might require additional steps from your side.
* CEGUI v-0 branch and releases starting with 0.8.4 will support Ogre 1.7, 1.8, 1.9. They will also be updated from time to time to support the current version of Ogre default branch (right now it works with the Ogre default branch version of 6th Jan. 2014, including Ogre's OGL3 Renderer)
* CEGUI default branch is currently not containing a functional OgreRenderer and is not recommended to be used by Ogre users until the new OgreRenderer is finished

<p>If somebody wants to use CEGUI from v0-8 together with Ogre's Direct3D 11 Renderer urgently, we can try to help you modify the CEGUIOgreRenderer for D3D 11 compatibilities - with strong pre-existing knowledge about hlsl it shouldn't take longer than 1 hour with our help.</p>

== Environment variables for CMake ==
If you installed Ogre (or OIS or Boost), then certain environment variables might have been set on your computer already, helping CMake find your Ogre version (or OIS or boost). Here are some examplatory paths from my computer:
* OIS_HOME - A:/Libraries
* OGRE_HOME - A:/Libraries/OgreFromSourceCode (alternatively, if you use an SDK and do not compile from source, for example use: A:/Libraries/OgreSDK )
* OGRE_SDK - A:/Libraries/OgreFromSourceCode/build (alternatively, if you use an SDK and do not compile from source, for example use: A:/Libraries/OgreSDK )
* Boost looks for C:/Boost and if nothing is there it looks for BOOST_ROOT env variable: http://stackoverflow.com/a/8770217/3144964

== How to acquire the CEGUI source code ==
Here are all the links you will need to build CEGUI and its dependencies - which is the recommended approach:
* Visit the [http://static.cegui.org.uk/docs/current/downloading.html reference manual] for instructions on obtaining the latest CEGUI source code (be sure to be on a '''stable branch''', for example v0-8) - this is the recommended approach as it will include the latest fixes.
'''Note''': If the branch version's source code seems to be unstable or not working, you can try the [http://sourceforge.net/projects/crayzedsgui/files/latest/download?source=files latest stable release] or select a Release version from the [http://cegui.org.uk/download downloads page].
* '''Additionally''' to the CEGUI source code you will need [http://sourceforge.net/projects/crayzedsgui/files/CEGUI%20Mk-2%20Dependencies/0.8.x/cegui-deps-0.8.x-src.zip/download the source code of the CEGUI dependencies]. Download it and build the dependencies on your system (debug & release modes are common and are recommended to be built). You can use this document as guideline for the building process if needed: [http://static.cegui.org.uk/docs/current/building_deps.html Building dependencies]. Move the "dependencies" folder, which should have been created during the build process and should contain the headers, .lib files and .dll files, into your CEGUI main folder, so that it will co-exist next to the folders "bin", "cegui", "datafiles" etc.

== A snapshot of using CMake ==
CMake has a great GUI that allows to change your project's configuration by specifiying the dependencies, renderers and parsers you want. You need to fill out the paths to all files and folders the dependencies require.
<div class="toccolours mw-collapsible mw-collapsed" style="width:80%">
''' Expand this to see an example on how to utilise the filters/search in CMake and how to set the Ogre variables'''
<div class="mw-collapsible-content">
{{[[File:Ogrescreen.png|How to set CMake variables]]}}
</div>
</div>

<div class="toccolours mw-collapsible mw-collapsed" style="width:80%">
''' Expand this for an example of fully set boost variables based on a boost binary release. Reminder: For Ogre you only need thze include folder and the "system" and "thread" libraries.'''
<div class="mw-collapsible-content">
{{[[File:Boostconfig.png|How to set CMake Boost variables]]}}
</div>
</div>

= Step-by-step guide =

'''Important:''' If you make a mistake such as confusing Debug and Release paths and you already clicked "Configure" again, then please trigger "Delete Cache" (File->Delete Cache) in Cmake and start from 0 again!
Also we recommend you to switch on the "Advanced" and "Grouped" checkboxes.
* 1. Get the appropriate '''CEGUI''' version from the CEGUI download page or get the very latest CEGUI version from the SVN repository (see links and info above).

* 2. Get the latest '''Ogre''' version. If you are build it yourself (recommended), you will need to compile/link it first in the modes you want to use (Debug/Release) to get Ogre's .lib and .dll files ready for CEGUI.

== Steps for Microsoft Visual Studio ==

===CEGUI 0.8.x ===
* 3. Open the CMake GUI Utility
* 4. Set the '''source path''' to the directory where your CEGUI files are located (e.g. C:/CEGUI - contains folders like 'cegui' 'cmake' 'datafiles', etc. )
* 5. Set the '''build path''' to the directory where you want CMake to generate your build configuration(e.g. C:/CEGUI/build)
* 6. Press the '''Configure''' button. At this stage CMake will ask you for a generator for this project(e.g. Visual Studio 10) and then will try to find the required packages needed by CEGUI. Please note that you should have the CEGUI dependencies built and installed in your CEGUI_ROOT directory. E.g. if your CEGUI directory is C:/CEGUI then the dependencies would be expected to be in C:/CEGUI/dependencies by default
* 7. Search the '''CEGUI_BUILD_RENDERER_OGRE''' boolean variable in the list of CMake GUI Utility and set the value to TRUE by clicking on the checkbox.
* 8. Check if OGRE and OIS (and boost - '''IF''' your Ogre version was built with boost as dependency) were found by cmake. (For more information about how boost can be found by CMake please see the Cmake docu: http://www.cmake.org/cmake/help/git-master/module/FindBoost.html) Look through the CMake GUI Utility output to see if there is a message like 'Could NOT find OGRE'. '''If both Ogre and OIS (and boost) were found (and reference the right version in case you got multiple ones) you can jump to step #9 now'''. <span style="color:#3333AA"> If this was not the case it means that you either have not set the environment variables for Ogre (OGRE_SDK and OGRE_HOME) and OIS (OIS_HOME) at all, or that you have not set them correctly. You can try to fix this and click configure again to see if it works. If it does you can skip to #9. If it does not work then set the paths yourself.

<div class="toccolours mw-collapsible mw-collapsed" style="width:80%">
''' Expand this field to get a very elaborate explanation on the CMake settings for Ogre, OIS and Boost including examplatory paths: '''
<div class="mw-collapsible-content">
{{BUILD_OGRE_FOR_CEGUI_0_8_HELP}}
</div>
</div>

* 9 After you changed all the CMake settings to your liking (deactivating/activating Image codecs, parsers, renderer, etc.) you have to rerun '''Configure'''. You need to do this in order to save your additional variables in the CMake cache and in the build configuration.
* 10 Press the '''Generate''' button. At this stage CMake will read your build configuration and then generate a solution using your selected generator.
* 11 Go to the cegui build directory and open the Visual Studio solution '''cegui.sln'''
* 12 Build the entire cegui solution.
* 13 (Optional) Start the SampleBrowser to see if the samples work correctly (don't forget to copy the created samples.xml from build/datafiles/samples to your datafiles/samples folder so that the SampleBrowser can find the samples you want to use. Also make sure you copied all the dlls that your setup requires to the foldering containing the SampleBrowser.exe and in Visual Studio: for Project->Properties->Debugging->Working Directory set the value to $(OutDir) )

===CEGUI 0.7.x ===
* 3. In your CEGUI folder there should be a folder called "'''projects'''" with a subfolder called "'''premake'''". It is recommended to use the [https://sourceforge.net/projects/crayzedsgui/files/CEGUI%20Mk-2/premake/premake-3.7-custom.zip/download custom premake version of CEGUI]. Otherwise you can get version 3.6 or 3.7 of premake. Once you have premake extract the '''premake.exe''' file into the said folder.

* 4. Open '''config.lua''' in the premake folder and edit the Ogre and OIS paths accordingly, so that they will point to the dependency files. In my case for example the 2 lines look like this (having the OGRE and CEGUI main folders on the same level):

<pre>
OGRE_PATHS = { "../OGRE", "include/OGRE", "lib" }
OIS_PATHS = { "../OGRE", "include/OIS", "lib" }
</pre>

'''Note:''' Remember to use forward slashes here! Just copying the paths from the Windows explorer will give you backward slashes. Replace them!

Next, set all Renderers you do not need to "false", in this case we will only need ''OGRE_RENDERER''. You can also set all samples to false, except maybe ''SAMPLES_OGRE'' if you want to compile those.

'''Important:''' Since Ogre 1.7 the "boost" library is a new dependency of OGRE. If you are unsure if your Ogre version needs boost, you might want to check if there is a boost folder in your Ogre main folder. In case your Ogre version makes use of boost, you will additionally add boost to the extra paths of CEGUIOgreRenderer, in my case it looks like this:
<pre>
CEGUI_EXTRA_PATHS = {
{ "../OGRE/boost_1_42", "", "lib", "CEGUIOgreRenderer" }
}
</pre>

* 5. Next, we create our Visual Studio Projects - Execute '''build_vs2008.bat''' to create a Visual Studio 2008 project or execute any other .bat file for your respective compiler version.

* 6. This should create '''CEGUI.sln''' in the premake folder. Open it.

* 7. If you have the Ogre lib files seperated into a Debug and Release folder, you will have to change the path in the '''Linker''' settings of the project so they will point to the '''lib/Debug''' or '''lib/Release''' folder for each configuration respectively.

* 8. '''Build''' the '''CEGUIOgreRenderer''' in Debug and Release mode.
* 9. Now that you have built the .dll files and .lib files for CEGUI by yourself, you only have to change the linker settings of your project so that the needed .lib files and their folder paths are included there. Also you might want to include the dll's into a folder where your executable application will find them (for example just the folder your executable starts from). Finally remember to set the CEGUI '''include''' directory (for example "..\..\CEGUI\cegui\include\cegui") inside your C++ project settings.

== Steps for GNU and Unix-like environments ==
===CEGUI 0.8.x ===

Going to the extracted CEGUI source directory and running the following commands seems to work. It also seems that the configurations are not used anymore. (noobnote: don't include the dollar-signs at the start of the lines. They represent the prompt.):

<pre>
$ mkdir build && cd build

$ export NUMBER_OF_CORES=`cat /proc/cpuinfo | grep "cpu cores" | uniq | awk '{print $4}'`

$ cmake -D CMAKE_BUILD_TYPE=Release ..

$ make -j$NUMBER_OF_CORES

$ sudo make install

$ sudo ldconfig
</pre>

If everything worked out, you now have CEGUI up and running!

===CEGUI 0.7.x ===
Going to the extracted CEGUI source directory and running the following commands seems to work (noobnote: don't include the dollar-signs at the start of the lines. They represent the prompt.):

<pre>
$ ./bootstrap && mkdir build && cd build

$ export NUMBER_OF_CORES=`cat /proc/cpuinfo | grep "cpu cores" | uniq | awk '{print $4}'`

$ ../configure && make -j$NUMBER_OF_CORES

$ sudo make install

$ sudo ldconfig
</pre>

If everything worked out, you now have CEGUI up and running!

==Errors==
*CEGUI Exception - bad allocation
This error is rather cryptic in its meaning and can occur when linking debug libraries to release libraries or vice-versa. Simply check all CMAKE paths to see if you accidently mixed up the debug and release paths for libraries (OIS, Ogre). If you did not then this might be due to a now-fixed error in 0.8.3. If this is the case you will have to change the .lib file to the OgreMain_d.lib version in Debug mode. Otherwise delete the cache (see mention above) and restart the CMake configuration.

==Questions==
Feel free to edit this page using your CEGUI forum account login if you want to append something. If you have questions you can ask in the CEGUI forum or join our IRC channel #cegui on irc.freenode.net -
In case you need help building Ogre in general, I'd recommend reading for example [http://blog.tidalware.com/2009/08/building-ogre-with-visual-studio/ this short guide (might be outdated though)].

For the Ogre-wiki version of this article you can also check this link: http://www.ogre3d.org/tikiwiki/tiki-index.php?page=Building+CEGUI

[[Category:HowTo]]

CEGUI Wiki - Crazy Eddie's GUI System (Open Source) - User contributions [en]

Building CEGUI for Ogre / OgreRenderer