Building from source
Written for CEGUI 0.8
Works with versions 0.8.x (stable)
Works with latest CEGUI stable!
|
This article is a work in progress and thus incomplete |
Obtaining the source
Stable Releases
Source code from the stable mercurial branches is released at various points in time and made available as source code packages. These packages can be found on the Downloads page.
Mercurial
The source code is kept in mercurial repositories at sourceforge.net. There are code repositories for the main CEGUI libraries as well as for other related items.
A mercurial client (GUI or CLI) is required to access the mercurial repositories and download code. The command necessary to obtain a copy of the code is 'clone':
hg clone SOURCE DESTINATION
where source is the URL of the repository to clone and destination is the local directory. To download a copy of CEGUI and place it in the cegui-source directory, you might use the following command:
hg clone http://crayzedsgui.hg.sourceforge.net/hgroot/crayzedsgui/cegui_mk2 cegui-source
Once you have this, the cloned repository is updated to the default (latest, unstable) code, so you most likely will want to switch to a stable branch instead, like this:
hg update -C v0-8
Repositories
The available repositories can be found here where you can also browse their code from your web browser. A couple of examples:
- Core CEGUI libraries - cegui_mk2
hg clone http://crayzedsgui.hg.sourceforge.net/hgroot/crayzedsgui/cegui_mk2 cegui-source
- CEED unified editor - CEED
hg clone http://crayzedsgui.hg.sourceforge.net/hgroot/crayzedsgui/CEED
Building
CEGUI uses CMake as a build system. CMake is cross-platform and open source so it's available on many platforms. There are binaries available for Windows, Mac and Linux, although on Linux your distribution will most probably have a CMake package ready. Make sure you install it before continuing.
Thanks to CMake and CEGUI's modular design, configuring and building CEGUI is a breeze.
The following instructions assume you have a cegui directory somewhere on your system so that all CEGUI related projects reside in it.
cegui (root working directory) cegui/cegui_mk2 (core CEGUI) cegui/CEED (editor) cegui/... (something else)
CEGUI
This section will focus on building the core CEGUI libraries, which is all you need to use CEGUI in a project. Most people will also want CEED, the unified editor for CEGUI, but it is not required.
Dependencies
CEGUI can be built without any dependencies to outside libraries. However, typical configurations require FreeType, a rendering module, an XML parser, and an image codec. CEGUI already provides support for several external libraries thanks to its modular design:
| Feature | Supported Libraries |
|---|---|
| Bi-Directional Language | MiniBIDI, FriBIDI |
| Font | FreeType |
| Image Codec | DevIL, FreeImage, OGRE, SILLY |
| Memory Management | OGRE, nedmalloc |
| Regular Expression | PCRE |
| Rendering | Direct3D, Irrlicht, OGRE, OpenGL |
| Resource Providers | Default (standard cross-platform file-access), minizip, OGRE |
| Scripting | Lua, Python |
| XML | Expat, LibXML2, RapidXml, TinyXML, Xerces-C++ |
CMake will automatically detect which external libraries exist on your system and will build CEGUI accordingly so make sure you install any external libraries you want to use before proceeding.
Directories
If you're following the directory structure outlined above, you should have something like:
cegui (root working directory) cegui/cegui_mk2 (core CEGUI)
Create the directory cegui/cegui_mk2/build and clone the cegui_mk2 repository inside cegui/cegui_mk2 with the name source. Example:
[~/cegui]$ mkdir cegui_mk2/build [~/cegui]$ hg clone http://crayzedsgui.hg.sourceforge.net/hgroot/crayzedsgui/cegui_mk2 cegui_mk2/source
The result should be:
cegui/cegui_mk2 (core CEGUI) cegui/cegui_mk2/build (will build here) cegui/cegui_mk2/source (the mercurial repository copy)
Build Options
There are several build options (or variables) supported by the CEGUI build system. To view them, you can use the command like or CMake GUI.
Using the command line
Enter the build directory and issue the following cmake command:
[~/cegui/cegui_mk2]$ cd build [~/cegui/cegui_mk2/build]$ cmake -LH ../source
[~/cegui/cegui_mk2/build]$ cmake -LH -DPYTHON_EXECUTABLE=/usr/bin/python2 ../source
CMake will run, it will look for the build systems available on your platform, will look for dependencies and then will print a list of variables, along with their description. For example:
// Select whether bi-directional text is enabled and which library should be used:
0: Disabled.
1: Use integrated minibidi library.
2: Use external fribidi library.
CEGUI_BIDI_SUPPORT:STRING=0
// Specifies whether to use embedded GLEW when external library was found
CEGUI_BUILD_EMBEDDED_GLEW:BOOL=OFF
Using CMake GUI
Start cmake-gui, select our source and build directories and click the Configure button. The available options will be listed in the main window. You can hover the mouse over an option and CMake will show a tooltip with a more detailed description.
Building
Configuring and Generating makefiles
The first step is to use CMake to configure the build and generate native makefiles. Without making any configuration changes, the command would be:
[~/cegui/cegui_mk2/build]$ cmake ../source
The same can be done using the CMake GUI. Select the source and build directories, click configure and finally click generate.
The build options can be changed via the GUI or via the CLI. If, for example, we want to turn off the slotted installation option and the python bindings we would run cmake like this:
[~/cegui/cegui_mk2/build]$ cmake ../source -DCEGUI_SLOTTED_INSTALLATION:BOOL=OFF -DCEGUI_BUILD_PYTHON_MODULES:BOOL=OFF
Another noteworthy option is the installation path, which is where CEGUI will be installed if you plan to install it via make install. Change the value of the CMAKE_INSTALL_PREFIX configuration variable to set it. Example:
[~/cegui/cegui_mk2/build]$ cmake ../source <other options here> -DCMAKE_INSTALL_PREFIX:PATH=/opt
so it will be installed in /opt/CEGUI (or /opt/CEGUI-0.8 if you use slotted installation).
Make
The second (and last required) step is using the generated native makefiles to build it. This is specific to your build environment; you may need to open the generated solution with MSVC or Xcode, or simply issue the make command.
<tabs> <tab title="GNU Make">
- You can speed make up significantly if you have a multi-core CPU by adding the -jN parameter, when N is the number of CPU cores on your machine.
[~/cegui/cegui_mk2/build]$ make -j4
- Optionally, run make install to install the binaries and the shared datafiles on your system.
</tab> <tab title="MSVC">
</tab> <tab title="Xcode">
</tab> </tabs>
Running the samples
Now that the build has finished, you can run the sample applications to check your build. The binaries should be in the bin directory:
cegui/cegui_mk2/build/bin
The samples may fail to run initially because they can't find the required data files. According to "cegui/cegui_mk2/source/Samples/common/include/CEGUISamplesConfig.h.in", the samples will look for the datafiles on "../datafiles" on Windows and on ${CMAKE_INSTALL_PREFIX}/${CEGUI_DATA_INSTALL_DIR} on other platforms.
It is possible to change this path without rebuilding, using the environment variable CEGUI_SAMPLE_DATAPATH. <tabs> <tab title="Linux">
[~/cegui/cegui_mk2/build]$ CEGUI_SAMPLE_DATAPATH=../source/datafiles bin/CEGUIDemo8-0.8
</tab> <tab title="Windows">
[C:\Users\User\cegui\cegui_mk2\build]$ SET CEGUI_SAMPLE_DATAPATH="C:\Users\User\cegui\cegui_mk2\source\datafiles" [C:\Users\User\cegui\cegui_mk2\build]$ bin/CEGUIDemo8-0.8.exe
</tab> </tabs>
Documentation
The documentation is written in doxygen format so you need Doxygen to build it. If you want to generate the nice class diagrams too, you need to install Graphviz.
Building the docs with the default options is easy:
[~/cegui/cegui_mk2/build]$ cd ../source/doc/doxygen [~/cegui/cegui_mk2/source/doc/doxygen]$ doxygen
This will create a directory named html which plenty of files, just open index.html.
If you'd rather change some of doxygen's options, you can edit the file source/doc/doxygen/doxyfile or, alternatively, use doxywizard (GUI). To change doxygen's output directory, one might do something like this:
[~/cegui/cegui_mk2/source/doc/doxygen]$ mkdir ../../../build/doc [~/cegui/cegui_mk2/source/doc/doxygen]$ nano doxyfile or use your editor of choice to edit doxyfile
Find the line
OUTPUT_DIRECTORY =
and change it to
OUTPUT_DIRECTORY = ../../../build/doc
Now run doxygen and it will create the html docs in build/doc.
CEED
CEED is the new CEGUI unified editor. It can edit layouts and imagesets, supports projects and multiple open file tabs, visual and source editing, preview and more. Please see CEED for a detailed description.
CEED is written in Python so there's no need to build it; all that's required is Python2 and it's dependencies.
Dependencies
CEED requires a Python 2 interpreter, version 2.6 or higher. Apart from PyCEGUI (the CEGUI Python bindings), it depends on the following libraries:
- PyOpenGL
- Qt4, PySide (+ PySide Tools)
- Boost.Python
<tabs> <tab title="Windows">
</tab> <tab title="Mac">
</tab> <tab title="Arch Linux"> You need at least python2, boost, python-opengl, pyside (AUR), pyside-tools (AUR).
</tab> <tab title="Debian">
- Wheezy
PySide is part of Sid at the moment, so you have to add its repository address to your /etc/apt/sources.list and then:
$ sudo apt-get update $ sudo apt-get install cmake python-opengl pyside-tools boost-python
</tab> <tab title="Fedora"> You need boost-devel, python-devel, python-opengl, python-pyside, pyside-tools. </tab> </tabs>
Running
If you're following the directory structure outlined in Building, you should have something like:
cegui (root working directory) cegui/CEED (CEED repository copy)
Running the main ceed-gui application could be as simple as:
[~/cegui/CEED]$ PYTHONPATH=.:$PYTHONPATH python2 bin/ceed-gui
If you don't have PyCEGUI installed system-wide but built it in cegui/cegui_mk2/build, you can run ceed-gui like this:
[~/cegui/CEED]$ PYTHONPATH=../cegui_mk2/build/lib:.:$PYTHONPATH python2 bin/ceed-gui
Running from Mercurial
If you've cloned the CEED mercurial repository, you will most likely get the following error when you try to run ceed-gui:
ImportError: No module named mainwindow
This is because the compiled .ui files are not part of the repository. Edit the file ceed/version.py with your favorite text editor and change the value of CEED_developerMode from False to True.
