Building Ogre With CMake         Extensive guide to building Ogre using CMake
Print
Image

This section explains how to use CMake to build Ogre from source.

Getting the Ogre Sources

First you need to download the Ogre sources. You can get them - surprise! - from the Ogre website(external link). Stable, prepacked source releases can be found under the link "Download -> Source". Alternatively you can get the sources from the Mercurial repository, see "Developers -> Mercurial" 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_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_COMPONENT_OVERLAY - If enabled, Ogre's optional overlay component will be built.
  • OGRE_BUILD_COMPONENT_VOLUME - If enabled, Ogre's optional volume rendering component will be built.
  • OGRE_BUILD_COMPONENT_RTSHADERSYSTEM - If enabled, Ogre's optional runtime shader system component will be built.
  • OGRE_BUILD_PLATFORM_APPLE_IOS - If enabled, Ogre will be built for the iOS platform
  • OGRE_BUILD_PLATFORM_ANDROID - If enabled, Ogre will be built for the Android platform
  • OGRE_BUILD_PLATFORM_WINRT - If enabled, Ogre will be built for the Windows RT platform
  • OGRE_BUILD_PLATFORM_NACL - If enabled, Ogre will be built for Google's Native Client 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_GL3Plus - If enabled, the OpenGL 3+ 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_GLES2 - If enabled, the OpenGL ES 2 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_D3D11 - If enabled, the Direct3D11 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. Setting this to 1 does not work under Linux, using only modes 0 and 2 is recommended.
  • 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.
  • OGRE_CONFIG_STATIC_LINK_CRT - Enabling this option will build Ogre with statically linked MS CRT dlls (msvcrt). This option is only available when compiling with the MS compiler. The default value is false for this option. Note: The OGRE dependencies will also need to be compiled with statically linked CRT - else the linker will fail with "...error LNK2005: _xxxx already defined in...".
  • OGRE_LIB_DIRECTORY - You can use this option to select the library installation directory (such as /usr/lib64 for 64 bit architectures)

 
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 iOS

 
Of course you will need to have downloaded and installed CMake.

After that, head over to http://sourceforge.net/projects/ogre/files/(external link) and download the latest iOS dependencies package. Once it has finished downloading, double-click on the disc image to mount it. Copy the iOSDependencies 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 iOS is using Terminal. First change to the directory of the Ogre sources. Now create a build directory and change to it:

mkdir build && cd build

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:

cmake -D OGRE_BUILD_PLATFORM_APPLE_IOS=1 -G Xcode ..

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

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

Building and Installing

 
If you are installing on an iPod / iPhone, see the first troubleshooting link:

Creating resource group Essential
Added resource location '/Users/taehyungkim/Documents/ogre_src_v1-7-1-2/Samples/Media/thumbnails' of type 'FileSystem' to resource group 'Essential'
Current language: auto; currently c++
(gdb) continue
An exception has occurred: OGRE EXCEPTION(7:InternalErrorException): <path>/Media/packs/SdkTrays.zip - error whilst opening archive: Unable to read zip file. in ZipArchive::checkZzipError at <path>/OgreMain/src/OgreZip.cpp (line 280)

Looks like your app can't read the zip file. My guess is that your resources.cfg contains absolute paths to the resources and it's trying to load files that are outside the application bundle.

Change it to use absolute paths instead, like this:

Code: Select all

Zip=Media/packs/SdkTrays.zip

Troubleshooting

http://www.ogre3d.org/forums/viewtopic.php?f=2&t=58579(external link)


Contributors to this page: Hazzr762 points  , tp56 points  , TeaBag363 points  , RubenGarcia6 points  , masterfalcon435 points  , jacmoe180265 points  , intregus182 points  , brunobg130 points  and Beauty14565 points  .
Page last modified on Friday 06 of September, 2013 18:55:08 UTC by Hazzr762 points .


The content on this page is licensed under the terms of the Creative Commons Attribution-ShareAlike License.
As an exception, any source code contributed within the content is released into the Public Domain.