Difference between revisions of "Building from source"

From CEGUI Wiki - Crazy Eddie's GUI System (Open Source)
Jump to: navigation, search
m (Directories: color CLI prompt)
(Documentation)
 
(37 intermediate revisions by 5 users not shown)
Line 2: Line 2:
 
{{notice|message=This article is a work in progress and thus incomplete}}
 
{{notice|message=This article is a work in progress and thus incomplete}}
  
=Obtaining the source=
+
==Official documentation==
{{Note|If you'd rather use precompiled SDKs, please follow [[Downloads]].}}
+
PLEASE use the documentation of your CEGUI version as your main source of information, e.g.: [http://static.cegui.org.uk/docs/current/compiling.html Latest API docs for building/compiling]
 +
 
 
==Stable Releases==
 
==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.
 
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==
 
==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.
+
The source code is kept in mercurial repositories at bitbucket.org. There are code repositories for the main CEGUI libraries as well as for other related items.
  
 
A mercurial client (GUI or <abbr title="Command-line Interface">CLI</abbr>) is required to access the mercurial repositories and download code. The command necessary to obtain a copy of the code is 'clone':
 
A mercurial client (GUI or <abbr title="Command-line Interface">CLI</abbr>) 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
 
  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:
 
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
+
  hg clone https://bitbucket.org/cegui/cegui 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:
 
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:
Line 20: Line 21:
  
 
===Repositories===
 
===Repositories===
The available repositories can be found [http://crayzedsgui.hg.sourceforge.net/hgweb/crayzedsgui/ here] where you can also browse their code from your web browser. A couple of examples:
+
The available repositories can be found [https://bitbucket.org/cegui/ here] where you can also browse their code from your web browser. A couple of examples:
* Core CEGUI libraries - [http://crayzedsgui.hg.sourceforge.net/hgweb/crayzedsgui/cegui_mk2 cegui_mk2]
+
* Core CEGUI libraries - [https://bitbucket.org/cegui/cegui/src cegui]
  hg clone http://crayzedsgui.hg.sourceforge.net/hgroot/crayzedsgui/cegui_mk2 cegui-source
+
  hg clone https://bitbucket.org/cegui/cegui cegui-source
* CEED unified editor - [http://crayzedsgui.hg.sourceforge.net/hgweb/crayzedsgui/CEED CEED]
+
* CEED unified editor - [https://bitbucket.org/cegui/ceed/src CEED]
  hg clone http://crayzedsgui.hg.sourceforge.net/hgroot/crayzedsgui/CEED
+
  hg clone https://bitbucket.org/cegui/ceed
  
{{Note|The difference between the ''hg clone'' URLs and the web-interface URLs is ''hgroot'' vs ''hgweb''}}
+
{{Note|The difference between the ''hg clone'' URLs and the web-interface URLs is the appended ''/src'' on the web URLs}}
  
 
=Building=
 
=Building=
CEGUI uses [http://www.cmake.org/ 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.
+
CEGUI uses [http://www.cmake.org/ 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 have some 2.8.X version installed because CMake 3.x.x will break with our scripts at the moment.
 
{{Note|CMake does not build the code directly, it generates native makefiles and workspaces that can be used in the compiler environment of your choice.}}
 
{{Note|CMake does not build the code directly, it generates native makefiles and workspaces that can be used in the compiler environment of your choice.}}
 
Thanks to CMake and CEGUI's modular design, configuring and building CEGUI is a breeze.
 
Thanks to CMake and CEGUI's modular design, configuring and building CEGUI is a breeze.
Line 38: Line 39:
 
  cegui/CEED        (editor)
 
  cegui/CEED        (editor)
 
  cegui/...          (something else)
 
  cegui/...          (something else)
{{Todo|Check directory structure so that CEED (which depends on CEGUI) works}}
 
  
 
==CEGUI==
 
==CEGUI==
Line 46: Line 46:
 
CEGUI can be built without any dependencies to outside libraries. However, typical configurations require [http://en.wikipedia.org/wiki/FreeType FreeType], a rendering module, an XML parser, and an image codec. CEGUI already provides support for several external libraries thanks to its modular design:
 
CEGUI can be built without any dependencies to outside libraries. However, typical configurations require [http://en.wikipedia.org/wiki/FreeType FreeType], a rendering module, an XML parser, and an image codec. CEGUI already provides support for several external libraries thanks to its modular design:
  
{| class="wikitable"
+
{| class="wikitable sortable" border="1" style="text-align: center;"
 +
|+ External libraries supported by CEGUI
 
|-
 
|-
! Feature
+
! scope="col" | Type
! Supported Libraries
+
! scope="col" | Name
 +
! scope="col" halign="left" | Additional information
 +
 
 +
|- style="background: #eaffe8;"
 +
| rowspan="5" | Rendering Module
 +
| OpenGL 3.2+ Core Profile
 +
| style="text-align: left;" | Uses the programmable rendering pipeline and only non-deprecated functionality and is therefore compatible with OpenGL Core Profile contexts (available since OpenGL 3.2). It can also be used with older OpenGL versions and/or Compatibility Profile, as long as the required functionalities are available.
 +
|- style="background: #eaffe8;"
 +
| OpenGL
 +
| style="text-align: left;" | Uses the fixed-function rendering pipeline. It is designed to be compatible with very early OpenGL versions, as early as OpenGL 1.2, using some OpenGL extensions.
 +
|- style="background: #eaffe8;"
 +
| Microsoft Direct3D
 +
| style="text-align: left;" | Microsoft Direct3D 9, 10, and 11 are supported using seperate modules.
 +
|- style="background: #eaffe8;"
 +
| OGRE
 +
| style="text-align: left;" | The latest stable Ogre version is supported in the releases.
 +
|- style="background: #eaffe8;"
 +
| Irrlicht
 +
| style="text-align: left;" | The latest stable Irrlicht version is supported in the releases.
 +
 
 +
|- style="background: #edfcfb;"
 +
| rowspan="4" | Image Codec Module
 +
| SILLY
 +
| style="text-align: left;" | Default image codec, which is based on the SILLY library. Supports many formats, see [[SILLY]]
 +
|- style="background: #edfcfb;"
 +
| DevIL
 +
| style="text-align: left;" | Image codec based on the DevIL library.
 +
|- style="background: #edfcfb;"
 +
| FreeImage
 +
| style="text-align: left;" | Image codec based on the FreeImage library.
 +
|- style="background: #edfcfb;"
 +
| OGRE
 +
| style="text-align: left;" | Image codec that loads data via image loading facilities of OGRE.
 +
 
 +
|- style="background: #dfeff1;"
 +
| rowspan="3" | Resource Provider Module
 +
| Default
 +
| style="text-align: left;" | The default resource provider of CEGUI uses standard cross-platform file-access.
 +
|- style="background: #dfeff1;"
 +
| OGRE
 +
| style="text-align: left;" | Ogre users can use CEGUI's Ogre ResourceManager. This way the resource locations of CEGUI can be specified in the same way as it is done for the Ogre resources already.
 +
|- style="background: #dfeff1;"
 +
| minizip
 +
| style="text-align: left;" | CEGUI's MinizipResourceProvider allows users to provides the ability to load the resource files from locations within .zip files.
 +
 
 +
|- style="background: #e9ebfc;"
 +
| rowspan="5" | XML Parser Module
 +
| Expat
 +
| style="text-align: left;" | Ddefault XML parser of CEGUI. Uses the Expat library for XML parsing.
 +
|- style="background: #e9ebfc;"
 +
| LibXML2
 +
| style="text-align: left;" | Uses the LibXML2 library for XML parsing.
 +
|- style="background: #e9ebfc;"
 +
| RapidXml
 +
| style="text-align: left;" | Uses the RapidXml library for XML parsing.
 +
|- style="background: #e9ebfc;"
 +
| TinyXML
 +
| style="text-align: left;" | Uses the TinyXML library for XML parsing.
 +
|- style="background: #e9ebfc;"
 +
| Xerces-C++
 +
| style="text-align: left;" | Uses the Xerces library for XML parsing. It can do schema validation using the .xsd files provided in CEGUI's resources.
 
|-
 
|-
| Bi-Directional Language
+
 
| MiniBIDI, FriBIDI
+
|- style="background: #fae9fc;"
|-
+
| rowspan="1" | Font Module
| Font
+
 
| FreeType
 
| FreeType
|-
+
| style="text-align: left;" | FreeType is the default font library of CEGUI and currently the only officially supported one.
| Image Codec
+
 
| DevIL, FreeImage, OGRE, SILLY
+
|- style="background: #f4e0e7;"
|-
+
| rowspan="1" | Regular Expression Module
| Memory Management
+
| Perl Compatible Regular Expressions (PCRE)
| OGRE, nedmalloc
+
| style="text-align: left;" | Default regular expression library and currently the only officially supported one. Uses the PCRE library.
|-
+
 
| Regular Expression
+
|- style="background: #fcf3e9;"
| PCRE
+
| rowspan="2" | Scripting Module
|-
+
| Lua
| Rendering
+
| style="text-align: left;" | Provides lua bindings using tolua++.
| Direct3D, Irrlicht, OGRE, OpenGL
+
|- style="background: #fcf3e9;"
|-
+
| Python
| Resource Providers
+
| style="text-align: left;" | Official Python bindings are available using [[PyCEGUI]]
| Default (standard cross-platform file-access), minizip, OGRE
+
 
|-
+
|- style="background: #f2eeca;"
| Scripting
+
| rowspan="2" | Memory Management
| Lua, Python
+
| OGRE
|-
+
| style="text-align: left;" | Ogre's memory allocator can optionally be used for CEGUI's memory management.
| XML
+
|- style="background: #f2eeca;"
| Expat, LibXML2, RapidXml, TinyXML, Xerces-C++
+
| nedmalloc
 +
| style="text-align: left;" | nedmalloc can optionally be used as memory allocator.
 +
 
 +
|- style="background: #f6fce9;"
 +
| rowspan="2" | Bi-Directional Language Module
 +
| MiniBIDI
 +
| style="text-align: left;" | MiniBIDI based implementation of CEGUI's Bidi visual mapping.
 +
|- style="background: #f6fce9;"
 +
| FriBIDI
 +
| style="text-align: left;" | FriBIDI based implementation of CEGUI's Bidi visual mapping.
 +
 
 
|}
 
|}
  
 
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.
 
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.
{{Todo|Does the above ^ work on Windows and Mac?}}
 
 
{{Note|You can turn off individual CEGUI modules from building (even if you have the required libraries installed) by changing the default [[Building from source#Build Options|Build Options]].}}
 
{{Note|You can turn off individual CEGUI modules from building (even if you have the required libraries installed) by changing the default [[Building from source#Build Options|Build Options]].}}
  
Line 87: Line 156:
 
  cegui                          (root working directory)
 
  cegui                          (root working directory)
 
  cegui/cegui_mk2                (core CEGUI)
 
  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:
+
Create the directory ''cegui/cegui_mk2/build'' and clone the ''cegui'' repository inside cegui/cegui_mk2 with the name ''source''. Example:
<span style="color:#080">[~/cegui]$</span> mkdir cegui_mk2/build
+
{{CLI|~/cegui|mkdir cegui_mk2/build}}
<span style="color:#080">[~/cegui]$</span> hg clone http://crayzedsgui.hg.sourceforge.net/hgroot/crayzedsgui/cegui_mk2 cegui_mk2/source
+
{{CLI|~/cegui|hg clone https://bitbucket.org/cegui/cegui cegui_mk2/source}}
 
The result should be:
 
The result should be:
 
  cegui/cegui_mk2                (core CEGUI)
 
  cegui/cegui_mk2                (core CEGUI)
 
  cegui/cegui_mk2/build          (will build here)
 
  cegui/cegui_mk2/build          (will build here)
 
  cegui/cegui_mk2/source        (the mercurial repository copy)
 
  cegui/cegui_mk2/source        (the mercurial repository copy)
 +
 +
{{Todo|Add instructions on where to extract the stable source packages (when available) so that we maintain a common directory structure}}
  
 
===Build Options===
 
===Build Options===
Line 100: Line 171:
 
====Using the command line====
 
====Using the command line====
 
Enter the ''build'' directory and issue the following cmake command:
 
Enter the ''build'' directory and issue the following cmake command:
  [~/cegui/cegui_mk2]$ cd build
+
  {{CLI|~/cegui/cegui_mk2|cd build}}
  [~/cegui/cegui_mk2/build]$ cmake -LH ../source
+
  {{CLI|~/cegui/cegui_mk2/build|cmake -LH ../source}}
 
{{Note|On systems that default to python3 (like Arch Linux) you have to tell it to use python2 like this:}}
 
{{Note|On systems that default to python3 (like Arch Linux) you have to tell it to use python2 like this:}}
  [~/cegui/cegui_mk2/build]$ cmake -LH -DPYTHON_EXECUTABLE=/usr/bin/python2 ../source
+
  {{CLI|~/cegui/cegui_mk2/build|2=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:
 
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:
 
  // Select whether bi-directional text is enabled and which library should be used:
Line 122: Line 193:
 
====Configuring and Generating makefiles====
 
====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:
 
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
+
{{CLI|~/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 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:
 
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
+
{{CLI|~/cegui/cegui_mk2/build|2=cmake ../source -DCEGUI_SLOTTED_INSTALLATION:BOOL=OFF -DCEGUI_BUILD_PYTHON_MODULES:BOOL=OFF}}
 
{{Note|The python bindings are required by [[#CEED|CEED]] so don't disable them if you plan to use it.}}
 
{{Note|The python bindings are required by [[#CEED|CEED]] so don't disable them if you plan to use it.}}
  
 
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:
 
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
+
{{CLI|~/cegui/cegui_mk2/build|2=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).
 
so it will be installed in /opt/CEGUI (or /opt/CEGUI-0.8 if you use slotted installation).
  
Line 136: Line 207:
 
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.
 
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.
  
=====Windows / MSVC=====
+
<tabber>
 +
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.
 +
{{CLI|~/cegui/cegui_mk2/build|make -j4}}
 +
* Optionally, run ''make install'' to install the binaries and the shared datafiles on your system.
 +
|-|
 +
MSVC=
 
{{Todo|MSVC notes}}
 
{{Todo|MSVC notes}}
 
+
|-|
=====Mac / Xcode=====
+
Xcode=
 
{{Todo|Xcode notes}}
 
{{Todo|Xcode notes}}
 +
</tabber>
  
=====GNU Make=====
+
===Running the samples===
* 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.
+
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]$ make -j4
+
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''.
 +
<tabber>
 +
Linux=
 +
{{CLI|~/cegui/cegui_mk2/build|2=CEGUI_SAMPLE_DATAPATH=../source/datafiles bin/CEGUIDemo8-0.8}}
 +
|-|
 +
Windows=
 +
{{CLI|C:\Users\User\cegui\cegui_mk2\build|2=SET CEGUI_SAMPLE_DATAPATH="C:\Users\User\cegui\cegui_mk2\source\datafiles"}}
 +
{{CLI|C:\Users\User\cegui\cegui_mk2\build|2=bin/CEGUIDemo8-0.8.exe}}
 +
</tabber>
  
 
===Documentation===
 
===Documentation===
{{Note|The documentation for stable releases can be found online [http://www.cegui.org.uk/docs/current here]}}
+
{{Note|The documentation for stable releases can be found online [http://static.cegui.org.uk/docs/ here]}}
{{Todo|Doxygen howto}}
+
 
 +
The documentation is written in doxygen format so you need [http://www.doxygen.org/ Doxygen] to build it. If you want to generate the nice class diagrams too, you need to install [http://graphviz.org/ Graphviz].
 +
 
 +
Building the docs with the default options is easy:
 +
{{CLI|~/cegui/cegui_mk2/build|cd ../source/doc/doxygen}}
 +
{{CLI|~/cegui/cegui_mk2/source/doc/doxygen|doxygen}}
 +
 
 +
This will create a directory named ''html'' with 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:
 +
{{CLI|~/cegui/cegui_mk2/source/doc/doxygen|mkdir ../../../build/doc}}
 +
{{CLI|~/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==
{{Todo|Short description}}
+
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.
{{Todo|Note and link to prebuilt binary downloads}}
+
  
===Dependencies===
+
CEED is written in [http://www.python.org/ Python] so there's no need to build it; all that's required is Python2 and it's dependencies.
{{Todo|Dependencies general}}
+
  
====Windows====
+
{{Note|If you'd rather use a stable package that includes dependencies, please follow [[Downloads]]}}
{{Todo|Windows deps & notes}}
+
  
====Mac====
+
===Dependencies===
{{Todo|Mac deps & notes}}
+
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
  
====Linux====
+
<tabber>
{{Todo|Linux deps & notes}}
+
Windows=
 +
{{Todo|Windows dependencies notes}}
 +
|-|
 +
Mac=
 +
{{Todo|Mac dependencies notes}}
 +
|-|
 +
Arch Linux=
 +
You need at least python2, boost, python-opengl, pyside (AUR), pyside-tools (AUR).
 +
{{Note|The packages from AUR may have been included in the ''[community]'' repository by now so check there first.}}
 +
|-|
 +
Debian=
 +
;Wheezy
  
=====Distro1=====
+
PySide is part of Sid at the moment, so you have to add its repository address to your /etc/apt/sources.list and then:
{{Todo|Distro specific deps & notes}}
+
 
 +
{{CLI||sudo apt-get update}}
 +
{{CLI||sudo apt-get install cmake python-opengl pyside-tools boost-python}}
 +
|-|
 +
Fedora=
 +
You need boost-devel, python-devel, python-opengl, python-pyside, pyside-tools.
 +
|-|
 +
Gentoo=
 +
You can use these supplied ebuilds:[https://bitbucket.org/ChrisTrenkamp/gentoo-ogre3d-tools]. Copy these ebuilds to your local overlay[http://en.gentoo-wiki.com/wiki/Overlay#Local_Overlays], add the necessary options to your package.keywords and package.use files, and run '''''emerge -av dev-util/ceed'''''
 +
</tabber>
  
 
===Running===
 
===Running===
{{Todo|Running}}
+
{{Todo|Update this section when CEED/CEGUI 0.8 is released}}
 +
If you're following the directory structure outlined in [[#Building|Building]], you should have something like:
 +
cegui                          (root working directory)
 +
cegui/CEED                    (CEED repository copy)
 +
 
 +
{{Todo|Add instructions on where to extract the stable source packages (when available) so that we maintain a common directory structure}}
 +
 
 +
Running the main ''ceed-gui'' application could be as simple as:
 +
{{CLI|~/cegui/CEED|2=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:
 +
{{CLI|~/cegui/CEED|2=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'''.
  
 
=Troubleshooting=
 
=Troubleshooting=
{{Todo|Problems? -> Forum!}}
+
If you encounter a problem that's not listed here, please make a post on the appropriate forum: [http://www.cegui.org.uk/phpBB2/viewforum.php?f=10 CEGUI], [http://www.cegui.org.uk/phpBB2/viewforum.php?f=15 CEED].
 +
 
 +
For comments about this article, you may use it's discussion page.
 +
 
 +
=Related articles=
 +
* [[Eclipse and CEGUI]]
 +
* [[Contribution|Contributing to the development of CEGUI]]
  
=Related Articles=
+
[[Category:HowTo]]
* [[Eclipse_and_CEGUI]]
+

Latest revision as of 07:55, 5 November 2015

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


Official documentation

PLEASE use the documentation of your CEGUI version as your main source of information, e.g.: Latest API docs for building/compiling

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 bitbucket.org. 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 https://bitbucket.org/cegui/cegui 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
Warning: Be aware that the -C option here will discard any local file changes without additional warning

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
hg clone https://bitbucket.org/cegui/cegui cegui-source
  • CEED unified editor - CEED
hg clone https://bitbucket.org/cegui/ceed
Note: The difference between the hg clone URLs and the web-interface URLs is the appended /src on the web URLs

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 have some 2.8.X version installed because CMake 3.x.x will break with our scripts at the moment.

Note: CMake does not build the code directly, it generates native makefiles and workspaces that can be used in the compiler environment of your choice.

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:

External libraries supported by CEGUI
Type Name Additional information
Rendering Module OpenGL 3.2+ Core Profile Uses the programmable rendering pipeline and only non-deprecated functionality and is therefore compatible with OpenGL Core Profile contexts (available since OpenGL 3.2). It can also be used with older OpenGL versions and/or Compatibility Profile, as long as the required functionalities are available.
OpenGL Uses the fixed-function rendering pipeline. It is designed to be compatible with very early OpenGL versions, as early as OpenGL 1.2, using some OpenGL extensions.
Microsoft Direct3D Microsoft Direct3D 9, 10, and 11 are supported using seperate modules.
OGRE The latest stable Ogre version is supported in the releases.
Irrlicht The latest stable Irrlicht version is supported in the releases.
Image Codec Module SILLY Default image codec, which is based on the SILLY library. Supports many formats, see SILLY
DevIL Image codec based on the DevIL library.
FreeImage Image codec based on the FreeImage library.
OGRE Image codec that loads data via image loading facilities of OGRE.
Resource Provider Module Default The default resource provider of CEGUI uses standard cross-platform file-access.
OGRE Ogre users can use CEGUI's Ogre ResourceManager. This way the resource locations of CEGUI can be specified in the same way as it is done for the Ogre resources already.
minizip CEGUI's MinizipResourceProvider allows users to provides the ability to load the resource files from locations within .zip files.
XML Parser Module Expat Ddefault XML parser of CEGUI. Uses the Expat library for XML parsing.
LibXML2 Uses the LibXML2 library for XML parsing.
RapidXml Uses the RapidXml library for XML parsing.
TinyXML Uses the TinyXML library for XML parsing.
Xerces-C++ Uses the Xerces library for XML parsing. It can do schema validation using the .xsd files provided in CEGUI's resources.
Font Module FreeType FreeType is the default font library of CEGUI and currently the only officially supported one.
Regular Expression Module Perl Compatible Regular Expressions (PCRE) Default regular expression library and currently the only officially supported one. Uses the PCRE library.
Scripting Module Lua Provides lua bindings using tolua++.
Python Official Python bindings are available using PyCEGUI
Memory Management OGRE Ogre's memory allocator can optionally be used for CEGUI's memory management.
nedmalloc nedmalloc can optionally be used as memory allocator.
Bi-Directional Language Module MiniBIDI MiniBIDI based implementation of CEGUI's Bidi visual mapping.
FriBIDI FriBIDI based implementation of CEGUI's Bidi visual mapping.

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.

Note: You can turn off individual CEGUI modules from building (even if you have the required libraries installed) by changing the default Build Options.

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 repository inside cegui/cegui_mk2 with the name source. Example:

[~/cegui]$ mkdir cegui_mk2/build
[~/cegui]$ hg clone https://bitbucket.org/cegui/cegui 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)
Todo: Add instructions on where to extract the stable source packages (when available) so that we maintain a common directory structure

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
Note: On systems that default to python3 (like Arch Linux) you have to tell it to use python2 like this:
 [~/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.


Note: Changing the options and building is explained below, in Building.

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
Note: The python bindings are required by CEED so don't disable them if you plan to use it.

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.

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

Todo: MSVC notes

Todo: Xcode notes

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.

[~/cegui/cegui_mk2/build]$ CEGUI_SAMPLE_DATAPATH=../source/datafiles bin/CEGUIDemo8-0.8

[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

Documentation

Note: The documentation for stable releases can be found online here

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

Note: If you'd rather use a stable package that includes dependencies, please follow Downloads

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

Todo: Windows dependencies notes

Todo: Mac dependencies notes

You need at least python2, boost, python-opengl, pyside (AUR), pyside-tools (AUR).

Note: The packages from AUR may have been included in the [community] repository by now so check there first.

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

You need boost-devel, python-devel, python-opengl, python-pyside, pyside-tools.

You can use these supplied ebuilds:[1]. Copy these ebuilds to your local overlay[2], add the necessary options to your package.keywords and package.use files, and run emerge -av dev-util/ceed

Running

Todo: Update this section when CEED/CEGUI 0.8 is released

If you're following the directory structure outlined in Building, you should have something like:

cegui                          (root working directory)
cegui/CEED                     (CEED repository copy)
Todo: Add instructions on where to extract the stable source packages (when available) so that we maintain a common directory structure

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.

Troubleshooting

If you encounter a problem that's not listed here, please make a post on the appropriate forum: CEGUI, CEED.

For comments about this article, you may use it's discussion page.

Related articles