Building CEGUI for Ogre / OgreRenderer

From CEGUI Wiki - Crazy Eddie's GUI System (Open Source)
Jump to: navigation, search

Written for CEGUI 0.7

Works with versions 0.7.x (obsolete)

Written for CEGUI 0.8

Works with versions 0.8.x (stable)

Works with latest CEGUI stable!

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.X and v0-8 branch supports basic configurations of Ogre 1.7 and 1.8 and 1.9. Other versions and specific configurations (such as using boost) are supported but might require additional steps from your side (see below).
  • CEGUI 0.8.5 (not yet released at the point of writing) and v0-8 branch support Ogre 2.0 and 2.1 with OGL3+ Renderer only.
  • 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 (unstable) contains an entirely changed but mostly functional OgreRenderer that should work with 1.7-2.0 but might need to be tested further.

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 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 latest stable release or select a Release version from the downloads page.

  • Additionally to the CEGUI source code you will need 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: 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.

Expand this to see an example on how to utilise the filters/search in CMake and how to set the Ogre variables

{{How to set CMake variables}}



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.

{{How to set CMake Boost variables}}

Optional: If you want to use CMake to set up your own project

We offer a FindCEGUI.cmake file in our repository *here* that you may want to use. An example CMake file can be found in this post: http://www.ogre3d.org/addonforums/viewtopic.php?f=34&t=30480&p=103432#p103432

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

Expand this field to get a very elaborate explanation on the CMake settings for Ogre, OIS and Boost including examplatory paths:

You can either use precompiled dependencies or build them yourself (preferred way if you want full debugging capabilities and you are not just "testing" Ogre and CEGUI) - please take a look at the Ogre documentation for how to do this.

Here is a full list of settings required to use 0.8.X with the Ogre 1.9.0 SDK (in this case for Visual Studio 2010) 

 OGRE_H_BUILD_SETTINGS_PATH = A:/Lukas/Desktop/ogretest/OgreSDK_vc10_v1-9-0/include/OGRE
 OGRE_H_PATH = A:/Lukas/Desktop/ogretest/OgreSDK_vc10_v1-9-0/include/OGRE
 OGRE_LIB = A:/Lukas/Desktop/ogretest/OgreSDK_vc10_v1-9-0/lib/Release/OgreMain.lib
 OGRE_LIB_DBG = A:/Lukas/Desktop/ogretest/OgreSDK_vc10_v1-9-0/lib/debug/OgreMain_d.lib

 OIS_H_PATH = A:/Lukas/Desktop/ogretest/OgreSDK_vc10_v1-9-0/include/OIS
 OIS_LIB = A:/Lukas/Desktop/ogretest/OgreSDK_vc10_v1-9-0/lib/debug/OIS.lib
 OIS_LIB_DBG = A:/Lukas/Desktop/ogretest/OgreSDK_vc10_v1-9-0/lib/debug/OIS_d.lib

 Boost_DIR = Boost_DIR-NOTFOUND
 Boost_INCLUDE_DIR = A:/Lukas/Desktop/ogretest/OgreSDK_vc10_v1-9-0/boost
 Boost_LIBRARY_DIR = A:/Lukas/Desktop/ogretest/OgreSDK_vc10_v1-9-0/boost/lib
 Boost_PYTHON_LIBRARY_DEBUG = Boost_PYTHON_LIBRARY_DEBUG-NOTFOUND
 Boost_PYTHON_LIBRARY_RELEASE = Boost_PYTHON_LIBRARY_RELEASE-NOTFOUND
 Boost_SYSTEM_LIBRARY_DEBUG = A:/Lukas/Desktop/ogretest/OgreSDK_vc10_v1-9-0/boost/lib/libboost_system-vc100-mt-gd-1_55.lib
 Boost_SYSTEM_LIBRARY_RELEASE = A:/Lukas/Desktop/ogretest/OgreSDK_vc10_v1-9-0/boost/lib/libboost_system-vc100-mt-1_55.lib
 Boost_THREAD_LIBRARY_DEBUG = A:/Lukas/Desktop/ogretest/OgreSDK_vc10_v1-9-0/boost/lib/libboost_thread-vc100-mt-gd-1_55.lib
 Boost_THREAD_LIBRARY_RELEASE = A:/Lukas/Desktop/ogretest/OgreSDK_vc10_v1-9-0/boost/lib/libboost_thread-vc100-mt-1_55.lib
 Boost_TIMER_LIBRARY_DEBUG = Boost_TIMER_LIBRARY_DEBUG-NOTFOUND
 Boost_TIMER_LIBRARY_RELEASE = Boost_TIMER_LIBRARY_RELEASE-NOTFOUND
 Boost_UNIT_TEST_FRAMEWORK_LIBRARY_DEBUG = Boost_UNIT_TEST_FRAMEWORK_LIBRARY_DEBUG-NOTFOUND
 Boost_UNIT_TEST_FRAMEWORK_LIBRARY_RELEASE = Boost_UNIT_TEST_FRAMEWORK_LIBRARY_RELEASE-NOTFOUND


For the following, more elaborate explanation, we assume the Ogre dependencies lie in the main folder of Ogre, so that if Ogre is installed to C:/Ogre, the dependencies will be in C:/Ogre/Dependencies:

  • OGRE_HOME (only necessary if you build it on your own from source code) - e.g.: C:/Ogre
  • OGRE_SDK - if you use SDK e.g.: C:/OgreSDK_vc10_v1-9-0 or if you build yourself e.g.: C:/Ogre/build
  • OIS_HOME- You can set this to point either to your OIS home or to your Ogre dependencies: C:/Ogre/Dependencies

In the case that the automatical finding of Ogre still does not work, you will have to set some CMAKE variables manually. For example, if the OGRE package was not found then you need to set the following variables:

  • OGRE_H_BUILD_SETTINGS_PATH - variable of type PATH which must be set to the directory where Ogre's build settings header file "OgreBuildSettings.h" is located (e.g. C:/Ogre/build/include/)
  • OGRE_H_PATH (before 0.8.3: OGRE_INCLUDE_DIR) - variable of type PATH which must be set to the directory where the OGRE header files are located (e.g. C:/Ogre/OgreMain/include)
  • OGRE_LIBRARIES - variable of type FILEPATH which must be set to the full file path of OgreMain.lib (e.g. C:/Ogre/build/lib/Release/OgreMain.lib)
  • OGRE_LIBRARIES_DBG(optional - if you don't intend to debug or are using CEGUI's "Release with Debug" build) - variable of type FILEPATH which must be set to the full file path of OgreMain_d.lib (e.g. C:/Ogre/build/lib/Debug/OgreMain_d.lib)
  • ( not in 0.8.3+ anymore: OGRE_FOUND - variable of type BOOL which must be set to TRUE )

Set all these variables analogously for OIS, here you can reference the dependency folder you used for Ogre , e.g.:

  • OIS_H_PATH - variable of type PATH which must be set to the directory where the OIS header files are located )(e.g. C:/Ogre/Dependencies/include/OIS)

Boost dependencies are often not found automatically. Boost requirements varied between different Ogre versions and, in addition to that, are now completely optional, but the precompiled release versions may often still depend on boost (such as Ogre 1.9 RC1 does). If you want to or have to use Boost and Boost wasnt found automatically on your system, please set the correct paths for these variables The following contains examplatory paths for the boost library, in this case we show you paths, which work for a precompiled Ogre SDK 1.9 package located in C:/Ogre/OgreSDK_vc11_v1-9-0:

  • Boost_INCLUDE_DIR - This path should contain the directory "boost" which contains all headers, e.g.: C:/Ogre/OgreSDK_vc11_v1-9-0/boost (Set this first otherwise it might erase your other boost paths)
  • Boost_SYSTEM_LIBRARY_DEBUG - C:/Ogre/OgreSDK_vc11_v1-9-0/boost/lib/libboost_system-vc110-mt-gd-1_55.lib
  • Boost_SYSTEM_LIBRARY_RELEASE - C:/Ogre/OgreSDK_vc11_v1-9-0/boost/lib/libboost_system-vc110-mt-1_55.lib

If you now click configure again, the following should be added to CMake:

  • Boost_LIBRARY_DIR - C:/Ogre/OgreSDK_vc11_v1-9-0/boost/lib

Also, Cmake will ask you to add two new paths (add them analogously to how you added the "SYSTEM" libraries):

  • Boost_THREAD_LIBRARY_DEBUG - C:/Ogre/OgreSDK_vc11_v1-9-0/boost/lib/libboost_thread-vc110-mt-gd-1_55.lib
  • Boost_THREAD_LIBRARY_RELEASE - C:/Ogre/OgreSDK_vc11_v1-9-0/boost/lib/libboost_thread-vc110-mt-1_55.lib

Some variables of Boost might still not be set, such as: Boost_DIR, Boost_PYTHON_LIBRARY_DEBUG/RELEASE, Boost_TIMER_LIBRARY_DEBUG/RELEASE, Boost_UNIT_TEST_FRAMEWORK_LIBRARY_DEBUG/RELEASE. This is not a cause for worry as they are not required for Ogre. They are only required if you want to build pyCEGUI (CEGUI with python bindings) or the CEGUI unit tests. Unless this is the case, you may ignore these settings.



If everything is set (and you are using boost), click configure again and you should get the following output in CMake: 

Found the following Boost libraries:
  thread
  system

You should now be able to generate the solution, including the optional SampleFramework/SampleBrowser, without getting any errors.

  • 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 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):
OGRE_PATHS = { "../OGRE", "include/OGRE", "lib" }
OIS_PATHS = { "../OGRE", "include/OIS", "lib" }

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: 

CEGUI_EXTRA_PATHS = { 
{ "../OGRE/boost_1_42", "", "lib", "CEGUIOgreRenderer" }
 }
  • 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.): 

$ 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


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.): 

$ ./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


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

Retrieved from "http://cegui.org.uk/wiki/index.php?title=Building_CEGUI_for_Ogre_/_OgreRenderer&oldid=5765"