History: Building Ogre With CMake

• «
• »

            {DIV()}{IMG(src="img/wiki_up/OGRE_Libraries.png",imalign="left")}{IMG}-=Building Ogre with CMake=-
This section explains how to use CMake to build Ogre from source.{DIV}
%clear%

{maketoc}

!!Getting the Ogre Sources
First you need to download the Ogre sources. You can get them - surprise! - from the [http://www.ogre3d.org|Ogre website]. Stable, prepacked source releases can be found under the link "Download -> Source". Alternatively you can get the sources from the SVN repository, see "Developers -> Subversion" for that. Either way keep in mind that the CMake build system covered on this page was added in Ogre version 1.7 (Cthugha), so don't pick anything older than that.

If you downloaded a source archive, you need to unpack it somewhere. A checkout from svn will automatically create an Ogre source directory at the place of your choice. In addition to the source directory, you also need to decide on a build directory - this is the place where CMake will setup a build system for you and where all compiled object files will reside.
If you intend to build Ogre just once and then move on, you can pick any location. If, however, you plan on building Ogre several times, potentially with different configurations (static builds, threaded builds, ...), I recommend to adopt a directory layout similar to the following (but this is up to you):

* __Ogre__ (the root directory for Ogre building, somewhere on your disk)
** __Sources__ (Ogre sources of various releases)
*** __Cthugha__ (Sources of current stable release)
*** __trunk__ (Sources of SVN trunk)
** __Builds__ (CMake build directories)
*** __Cthugha__ (Standard build of current stable release)
*** __trunk__ (Standard build of SVN trunk)
*** __trunk.static__ (Static build of SVN trunk)

!!Preparing the Environment


!!Running CMake
For this step, you need to have downloaded and installed CMake. If you need instructions on that, look here: ((Getting Started With CMake))
Run CMake to prepare your build directory. Instructions are at the page linked above, but in quintessence: Start cmake-gui, then at the top select the build and source directory you want to use and click on "Configure". You will then be asked about the build system you want to generate; the default should be fine for most people.

Ogre offers a variety of build options you can configure with the help of cmake-gui. The default options provide a sensible default which will give you a build similar to the official SDK releases. Following is a list of available Ogre build options and their effect on the build process.

* __OGRE_BUILD_CEGUIRENDERER__ - If enabled, the CEGUI renderer component will be built. This requires that the CEGUI library was found by CMake.
* __OGRE_BUILD_COMPONENT_PAGING__ - If enabled, Ogre's optional paging component will be built.
* __OGRE_BUILD_COMPONENT_PROPERTY__ - If enabled, Ogre's optional property component will be built.
* __OGRE_BUILD_COMPONENT_TERRAIN__ - If enabled, Ogre's optional paging terrain component will be built.
* __OGRE_BUILD_PLATFORM_IPHONE__ - If enabled, Ogre will be built for the iPhone OS platform
* __OGRE_BUILD_PLUGIN_BSP__ - If enabled, the BSP SceneManager plugin will be built.
* __OGRE_BUILD_PLUGIN_CG__ - If enabled, the Cg ProgramManager plugin will be built. This requires that Nvidia's Cg compiler library was found by CMake.
* __OGRE_BUILD_PLUGIN_OCTREE__ - If enabled, the Octree SceneManager and Terrain SceneManager plugin will be built.
* __OGRE_BUILD_PLUGIN_PCZ__ - If enabled, the Portal Connected Zone SceneManager plugin will be built.
* __OGRE_BUILD_PLUGIN_PFX__ - If enabled, the ParticleFX plugin will be built.
* __OGRE_BUILD_RENDERSYSTEM_GL__ - If enabled, the OpenGL RenderSystem will be built.
* __OGRE_BUILD_RENDERSYSTEM_GLES__ - If enabled, the OpenGL ES RenderSystem will be built. This requires that CMake needs to have found the Open GL ES SDK.
* __OGRE_BUILD_RENDERSYSTEM_D3D9__ - If enabled, the Direct3D9 RenderSystem will be built. This requires a Windows platform, and CMake needs to have found the DirectX SDK.
* __OGRE_BUILD_RENDERSYSTEM_D3D10__ - If enabled, the Direct3D10 RenderSystem will be built. This requires a Windows platform and a sufficiently recent DirectX SDK.
* __OGRE_BUILD_SAMPLES__ - If enabled, Ogre's samples will be built. All samples need the OIS library, so this option requires that OIS has been found by CMake. Additionally, some samples depend on CEGUI or specific plugins and might be skipped if those dependencies are not met.
* __OGRE_BUILD_TESTS__ - If enabled, Ogre library test cases will be built. This requires that the cppunit library was found by CMake.
* __OGRE_BUILD_TOOLS__ - If enabled, this will build Ogre's command line tools (MeshUpgrader and ((-OgreXmlConverter|XMLConverter))).
* __OGRE_CONFIG_ALLOCATOR__ - This option determines the allocator to use for Ogre's memory allocations. A value of 1 will use standard STL allocators, the default value 2 selects an allocator based on nedmalloc. The value 3 is needed for a user-provided allocator.
* __OGRE_CONFIG_CONTAINERS_USE_CUSTOM_ALLOCATOR__ - Enabling this option has Ogre use the custom allocator for internally used STL containers.
* __OGRE_CONFIG_DISABLE_DDS__ - If this option is set, then Ogre's DDS image codec will __not__ be built.
* __OGRE_CONFIG_DISABLE_FREEIMAGE__ - If this option is set, the FreeImage image codecs will __not__ be built. If this option is not set, then the FreeImage library needs to have been found by CMake.
* __OGRE_CONFIG_DOUBLE__ - Enabling this option makes Ogre use the double type instead of float.
* __OGRE_CONFIG_MEMTRACK_DEBUG__ - Setting this option enables Ogre's memory tracker in debug mode.
* __OGRE_CONFIG_MEMTRACK_RELEASE__ - Setting this option enables Ogre's memory tracker in release mode.
* __OGRE_CONFIG_NEW_COMPILERS__ - If enabled, Ogre will use the new script compilers. This is the default.
* __OGRE_CONFIG_STRING_USE_CUSTOM_ALLOCATOR__ - If enabled, Ogre::String will use the custom allocator. Be aware that in this case Ogre::String will be incompatible with std::string.
* __OGRE_CONFIG_THREADS__ - This setting determines Ogre's threading support. A value of 0 disables threading support. A setting of 1 enables full background resource loading, whereas a value of 2 enables only background resource preparation.
* __OGRE_DEPENDENCIES_DIR__ - Contains the directory where Ogre's dependencies can be found. This setting can be used to help CMake locate dependencies; it is primarily important when using prebuilt dependencies for Windows / Mac platforms.
* __OGRE_FULL_RPATH__ - If enabled, then on Unix platforms installed program files will contain the full RPATH needed to run them. If disabled, only partial RPATH needed for the PCZ SceneManager is included. You can disable even that part by enabling CMAKE_SKIP_RPATH.
* __OGRE_INSTALL_DOCS__ - If enabled, Ogre documentation (manual and API reference) will be installed.
* __OGRE_INSTALL_MEDIA__ - If enabled, Ogre's sample media files will be installed.
* __OGRE_INSTALL_PLUGIN_HEADERS__ - If enabled, the headers of Ogre's plugins will be installed. Usually plugins are meant to be usable without explicitly linking to them, therefore headers are usually not required. There are, however, exceptional cases where you might need them.
* __OGRE_INSTALL_SAMPLES__ - If enabled, Ogre's samples will be installed. This requires that samples be built in the first place.
* __OGRE_INSTALL_SAMPLES_SOURCE__ - If enabled, the source code of Ogre's samples will be installed. Primarily targeted for official SDK packages.
* __OGRE_INSTALL_TOOLS__ - If enabled, the command line tools will be installed. This requires that they be built in the first place.
* __OGRE_STANDALONE_BUILD__ - An experimental option targeted for the Windows platform to pregenerate Visual Studio project files; intended for official SDK packages.
* __OGRE_STATIC__ - Enabling this option will build Ogre and all of its components and plugins (as far as they are enabled) as static libraries.

Choose options according to your wishes. In particular, disabling features you don't need will apparently reduce your compile time. Once you're satisfied, hit 'Configure' again in cmake-gui, then select 'Generate'. This will create a customised build system in your build directory, according to the options you just selected.

!!!Configuring for iPhone
Of course you will need to have downloaded and installed CMake.

After that, head over to [http://sourceforge.net/projects/ogre/files/] and download the latest iPhone dependencies package. Once it has finished downloading, double-click on the disc image to mount it. Copy the iPhoneDependencies folder to the root of the Ogre source tree. It should reside alongside folders such as OgreMain, Samples, Tests, PlugIns, etc.

The best way to configure for iPhone is using Terminal. First change to the directory of the Ogre sources. Now create a build directory and change to it:
{CODE()}mkdir build && cd build{CODE}
You need to run cmake from the build directory and provide it with the location of the build directory. If you followed the above guideline, then you can simply type:
{CODE()}  cmake -D OGRE_BUILD_PLATFORM_IPHONE=1 -G Xcode ..{CODE}
CMake will now parse the scripts in the Ogre source tree. Watch the output, especially if all necessary dependencies have been found. If not, you might need to install the missing ones or provide their locations manually

The linker paths are not correctly generated so now you must run the following script to take care of this. Type:
{CODE()} ../SDK/iPhone/fix_linker_paths.sh{CODE}
Then press return or enter.

A Xcode project has now been generated in the build directory, so to start the Ogre build, open OGRE.xcodeproj and build as usual.

To run samples on your device you will need to have a valid iPhone Developer certificate installed. For each sample, double click on target in the Groups & Files list. Ensure that a valid identity is selected in the Code Signing Identity drop menu.

Also, because we can't tell CMake what Xcode project format you want, you will have to change it yourself. Open the Project Menu, choose Edit Project Settings. Click on the General tab in the settings window. Change Project Format to Xcode 3.1-compatible.

And another thing. You will need to manually set the Bundle Identifier property of the Info.plist file to match the App ID of the chosen code signing identity. This can be done from the Target Properties panel. It must match the bundle identifier of a valid developer certificate if you are building for devices.

See the following PDF for information under Generating an App ID:
[http://adcdownload.apple.com/iphone/iphone_developer_program_user_guide/iphone_developer_program_user_guide__standard_program_v2.4.pdf]

!!Building and Installing
!!Troubleshooting