Difference between revisions of "Building CEGUI for Ogre / OgreRenderer"

Revision as of 06:10, 11 September 2014

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.

• 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

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.

Please be aware that you need to know yourself if your Ogre version uses boost or not. There is no way we can automatically find this out. If you do not use boost in your Ogre version, you do not need to specify the boost library in the CEGUI CMake configuration. If you do use it, you should carefully read the instructions in this article regarding boost..

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.

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.
• 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 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. Here are examplatory paths for the environment variables:

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. Afterwards, 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 SampleFramework/SampleBrowser.

• 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

TODO

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