Latest revision as of 10:48, 1 May 2016

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.

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.

 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

Found the following Boost libraries:
  thread
  system

• 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