History: CMake Quick Start Guide

Source of version: 67 (current)

{DIV(class="achtung")}__IMPORTANT:__ These instructions are meant to be used with old releases of Ogre.
For Ogre 1.10+, rather use [https://ogrecave.github.io/ogre/api/latest/building-ogre.html|BuildingOgre.md].{DIV}
{BOX(width="100%",class="Layout_box9")}{SPLIT(colsize=10%|70%)}{IMG(src="img/wiki_up/Star.png",imalign="left",link="CMake Quick Start Guide",title="CMake Quick Start Guide")}{IMG}
---
{DIV(class="bigBold")}((CMake Quick Start Guide|Quick Start Guide)){DIV}
For the impatient: Learn how to build Ogre with CMake in two minutes. If you encounter any problems or need some more advanced procedures, do read the rest of the sections below!
{SPLIT}{BOX}
!!Introduction
This guide is designed to get you building OGRE from source with the default settings in the shortest possible time, showing you the barest minimum of CMake to do that, and minus any real discussion. Remember that there is a lot more to the hows and whys of this process, so it's a good idea to go back to the ((Getting Started With CMake)) page and read the whole thing when you have time.

We assume here that you've already [http://www.ogre3d.org/download/source|downloaded / extracted the OGRE source code] into a folder on your local machine. From here, go to the section for your platform.

{VERSIONS(nav="y",default="Windows")}
{DIV(class="Layout_box6")}
%done% Make sure that you've sorted out the ((Prerequisites)) before attempting to build Ogre with CMake!	 
{DIV}
# Download the [https://bitbucket.org/cabalistic/ogredeps|Dependencies repository]. To i.e. C:\OgreSDK\Dependencies
# [http://www.cmake.org/cmake/resources/software.html|Download and install CMake]. You want the 'Win32 installer' release in the binary distribution section. Use version +2.8; version 3.x is not widely tested yet.
# Launch CMake via Start > Program Files > CMake 2.8 > CMake
# Point "Where is the source code" to C:\OgreSDK\Dependencies; and "Where to build the binaries" pointing to "C:\OgreSDK\Dependencies\build"
# Click 'Configure' and select the generator (i.e. if you're using Visual Studio 2013, select Visual Studio 12) {img fileId="2197"}
# Answer 'Ok' when asked if you want to create the build directory
# Sometimes on bleeding edge repos there might be CMake syntax warnings. Ignore them.
# Now click 'Generate'.
# Open C:\OgreSDK\Dependencies\build\OGREDEPS.sln under Visual Studio. If you have multiple versions of VS, make sure you open it with the one you targeted for in CMake.
# Build the whole solution; which should build FreeImage, freetype, OIS, zlib and zziplib. Make sure to build both Debug and Release
# Once it's finished, right click on INSTALL project, and click build. THIS IS VERY IMPORTANT. It will create the folder structure that Ogre needs. You need to do this both for Debug and Release.{img fileId="2198"}
# This should've created an SDK folder structure under C:\OgreSDK\Dependencies\build\ogredeps
# Now download [https://bitbucket.org/sinbad/ogre/|Ogre from the repository] into C:\OgreSDK.
# We now repeat the same process: Open CMake, set C:\OgreSDK and C:\OgreSDK\build as "Where is the source code" and "Where to build the binaries" respectively.
# Hit Configure and choose the same Visual Studio generator you did for the dependencies. It will now complain it can't find the Dependencies.
# Set OGRE_DEPENDENCIES_DIR to point to C:\OgreSDK\Dependencies\build\ogredeps as in the picture. Use the search filter to find the option quickly. Now hit configure again.{img fileId="2199"}
# Pro tip: If "C:\OgreSDK\Dependencies" contains the files that are generated in C:\OgreSDK\Dependencies\build\ogredeps; you can skip the previous step.
# Click Generate.
# Open the solution C:\OgreSDK\build\OGRE.sln and compile.
# Right click on INSTALL project if you wish to generate the SDK structure we provide in our official releases.
# You're done.
# If you are like me (I don't like using INSTALL feature for my own projects), you can add C:\OgreSDK\build\include to your project's include location and C:\OgreSDK\build\lib\Debug (and Release) to your additional library paths. The DLLs will be located in bin\debug (or release)

That's it for CMake! You now have a set of project files that are very much like you're used to in previous versions of OGRE, in the output folder you chose. There is now a special target called 'ALL_BUILD' which is a quick way to build all targets for a specific configuration. Note that all build output is now stored in a subfolder of this build folder, and not in the original OGRE source folder - so you can create multiple builds from one source directory now.

If you're more into video tutorials instead of reading, here's one:
{YOUTUBE(movie="https://www.youtube.com/watch?v=-3XwyYQ9OLg")}{YOUTUBE}
If the embedded player is not showing up, here's the link: [https://www.youtube.com/watch?v=-3XwyYQ9OLg]

---(Linux)--------------------------
{DIV(class="Layout_box6")}
%done% Make sure that you've sorted out the [http://www.ogre3d.org/tikiwiki/Prerequisites?tikiversion=Linux|Prerequisites] before attempting to build Ogre with CMake!	 
{DIV}

# [http://www.ogre3d.org/download/source|Download Ogre Source] (Instructions below assume current version of 1.8.0, update as needed)
# Decompress:{CODE(wrap="0", colors="bash")}tar xjf ogre_src_v1-8-0.tar.bz2{CODE}
# Move to source directory:{CODE(wrap="0", colors="bash")}cd ogre_src_v1-8-0{CODE}
# Create build directory:{CODE(wrap="0", colors="bash")}mkdir build{CODE}
# Move into build directory:{CODE(wrap="0", colors="bash")}cd build{CODE}
# Trigger cmake, passing path to Ogre source directory:{CODE(wrap="0", colors="bash")}cmake ..{CODE}See the ((Building Ogre With CMake|Extensive CMake)) page for a list of compilation options which can be passed to CMake at this stage, and ((Getting Started With CMake)) for even more background material. ~~#F00:N.B.~~ Please note that OGRE_CONFIG_THREADS = 1 is not supported on Linux.
# If the CMake results look good, build Ogre:{CODE(wrap="0", colors="bash")}make -j2{CODE}The {MONO()}-j2{MONO} specifies how many parallel compilation jobs to run.  Substitute the number of processor cores on your system, e.g. {MONO()}-j2{MONO} for a dual-core, {MONO()}-j4{MONO} for a quad core...
# Once compilation is successful, you can install into the system (by default, /usr/local):{CODE(wrap="0", colors="bash")}sudo make install{CODE}


---(Mac OS X)--------------------------
{DIV(class="Layout_box6")}
%done% Make sure that you've sorted out the [http://www.ogre3d.org/tikiwiki/Prerequisites?tikiversion=Mac+OSX|Prerequisites] before attempting to build Ogre with CMake!	 
{DIV}%clear%
!!!Building Ogre via CMake GUI (see alt. command line below)

Xcode 4.3 changed the layout of developer tools on disk which can cause some serious problems for CMake. The issue has been fixed but is not yet publicly released. CMake 2.8.8 will include Xcode 4.3 support. At the time of writing, a release candidate is available that includes this support.

You will also need to install the Command Line Tools from within Xcode's Downloads Preferences and set the Xcode path from the command line like this.

Assuming that Xcode is installed in /Applications,

sudo xcode-select -switch /Applications/Xcode.app/Contents/Developer

# [http://www.cmake.org/cmake/resources/software.html|Download CMake]. You want the 'Mac OS X Universal' release in the binary distribution section
# The .dmg will probably auto-mount when it downloads, if not, double-click it to open
# Double-click the .pkg installer, install on your main drive and opt to install the command-line tools too (in case you want to use them later, we will use the GUI here)
# Launch CMake via Applications
# In the "Where is the source code" box, type or browse to the root directory of your OGRE source (the one that contains the OgreMain folder)
# In the "Where to build the binaries" box, type or browse to any folder you like - this will be where the build output will go (libraries, headers, dlls & sample exes). The folder does not have to exist yet. Note that you can run this process more than once with different output folders if you want (but we won't complicate matters now)
# Hit the 'Configure' button near the bottom of the screen 
# Pick 'Xcode' as the generator and opt to use native compilers
# Answer 'Ok' when asked if you want to create the build directory
# Wait for the configure process to finish
# The screen will now have a bunch of configuration options on it, which will be red (this is to indicate this is the first time you've seen them). You can see the potential for customising your build here, but for now just click the 'Configure' button again
# The values will turn grey, and the 'Generate' button at the bottom will now be enabled. Click 'Generate'
# Build files will now be generated in the location you picked
# Now, open OGRE.xcodeproj in the build directory you picked, open it in Xcode. SampleBrowser will build everything!

Note: ALL_BUILD does not work properly with Xcode 4.

!!!Building Ogre via Command Line (see alt. GUI method above)
# [http://www.ogre3d.org/download/source|Download Ogre Source] (Instructions below assume current version of 1.8.0, update as needed)
# Decompress:{CODE(wrap="0", colors="bash")}tar xjf ogre_src_v1-8-0.tar.bz2{CODE}
# Move to source directory:{CODE(wrap="0", colors="bash")}cd ogre_src_v1-8-0{CODE}
# Create build directory:{CODE(wrap="0", colors="bash")}mkdir build{CODE}
# Move into build directory:{CODE(wrap="0", colors="bash")}cd build{CODE}
# Trigger cmake, specify Xcode generation and pass path to Ogre source directory:{CODE(wrap="0", colors="bash")}cmake -GXcode ..{CODE}See the ((Building Ogre With CMake|Extensive CMake)) page for a list of compilation options which can be passed to CMake at this stage, and ((Getting Started With CMake)) for even more background material.
# Build via Xcode{CODE(wrap="0", colors="bash")}xcodebuild -configuration RelWithDebInfo{CODE}(or open OGRE.xcodeproj and build within Xcode)

!!!Installing Ogre
You will find Ogre.framework in 'lib' within your build directory.  You can embed this in your application bundle, or drag it to /Library/Frameworks for system-wide installation.

You will also find plugins (Plugin_*.dylib and RenderSystem_GL.dylib) in the same location, you can copy these to the framework's Resource directory or your own application's bundle.  Be sure to configure you applications' plugins.cfg to match (e.g. /Library/Frameworks/Ogre.framework/Resources/)

---(iPhone)--------------------------
Detailed instructions on building OGRE for iPhone can be found on this page [Building From Source (for iPhone)]

---(Android)--------------------------

Here we target the lowest possible Android API, which is API 10 Android 2.3.3. This build process has been tested using OGRE v1.9 and v1.10 using both Linux and Windows hosts and up to Android 4.4 Kitkat (API 19).

__General Android Build Instructions__:
# Download and install the Android SDK: {CODE(wrap="0", colors="bash")}https://developer.android.com/sdk/{CODE}
# Follow the instructions on the SDK site to use the tools included in the SDK to download and install your target Android API version.
# Download and install the Android NDK. Android NDK revision 8b is not supported due a bug in the toolchain. {CODE(wrap="0", colors="bash")}https://developer.android.com/tools/sdk/ndk/{CODE}
# Initialize your Android SDK and NDK environment variables:
## Create environment variables ANDROID_SDK and ANDROID_NDK and set them to the full install path of the Android SDK and NDK respectively.
## Prepend %ANDROID_SDK%\tools, %ANDROID_SDK%\platform-tools, and %ANDROID_NDK% to the beginning of your PATH variable.
# Download and build the OGRE dependencies. This will require configuring `ogredeps` to target an Android build while running CMake.
## Download ogredeps. {CODE(wrap="0", colors="bash")}https://bitbucket.org/cabalistic/ogredeps{CODE}
## Navigate your command prompt to the root of the ogredeps build directory.
## Run CMake to create your build files. ANDROID_ABI is usually armeabi-v7a, ANDROID_NATIVE_API_LEVEL should match whatever API level you downloaded via the SDK utilities, ANDROID_TOOLCHAIN_NAME should match the toolchain (i.e., build system) you wish to use from %ANDROID_NDK%\toolchains, and replace "Unix Makefiles" with whatever build system you wish to use. Assuming you are building from ogredeps/build: {CODE(wrap="0", colors="bash")}cmake -G"Unix Makefiles" -DCMAKE_TOOLCHAIN_FILE="../cmake/android.toolchain.cmake" -DANDROID_ABI=armeabi-v7a -DANDROID_NATIVE_API_LEVEL=10 -DANDROID_TOOLCHAIN_NAME=arm-linux-androideabi-4.8 ..{CODE}
## Build as usual using your target build system.
# Build OGRE for Android.
## Download the OGRE source code (either via the Mercurial repo or the compressed source archive).
## Run CMake from the OGRE build directory. Again, change parameters like you did while building ogredeps to suit your Android target. Assuming you want to build OGRE in the folder ogre/build, run CMake like so: {CODE(wrap="1", colors="bash")}cmake -DCMAKE_TOOLCHAIN_FILE="../CMake/toolchain/android.toolchain.cmake" -DOGRE_DEPENDENCIES_DIR="/path/to/ogredeps/build" -DANDROID_ABI=armeabi-v7a  -DANDROID_NATIVE_API_LEVEL=10 -DANDROID_TOOLCHAIN_NAME=arm-linux-androideabi-4.8 ..{CODE}
## Build as usual using your target build system. Replace "darwin-x86" with the folder corresponding to your host build system. If using the Make build system, you may want to use the version of make included with the NDK. {CODE(wrap="0", colors="bash")}
android-ndk/prebuilt/darwin-x86/bin/make)
{CODE}
# (Optional) Build and install the OGRE SampleBrowser onto your Android device.
## Download and install ant (http://ant.apache.org/bindownload.cgi) which will be used to build Android projects from the command line and install them on your device. On most OS, this could be done either manually or using a package manager (including Chocolatey on Windows, MacPorts or Homebrew on Mac OS X, or whatever package manager comes with your Linux distro).
## Navigate your command prompt to the SampleBrowserNDK subfolder in your OGRE build folder.
## Build the SampleBrowser as a native activity using ndk-build. Optionally use the "-j <# threads>" option -- without the quotes of course -- for a parallel build. {CODE(wrap="1", colors="bash")}
ndk-build all
{CODE}
## Attach your Android device to your PC so that a call to 'adb devices' lists the device.
## Build a debug APK of the SampleBrowser and install on Android device: {CODE(wrap="1", colors="bash")}ant debug install{CODE}
# (Optional) Build and install the OGRE JNI example application, which demonstrates how to interface a C++ OGRE application with a Java Android bridge.
## TODO: Fill me in.

__Notes on building for Android on Linux host__:

__Notes on building for Android on Mac OS X host__:

__Notes on building for Android on Windows host__:
Standard NMake can only build one file at a time. For functionality similar to "make -j" (parallel builds), use JOM in place of the "nmake" command above. JOM can be found here: http://qt-project.org/wiki/jom

Here is a sample CMake configuration command for building OGRE for Android on Windows using NMake as the build system and armeabi as the Android ABI (assuming you are building from ogre/build):
{CODE(wrap="1", colors="bash")}cmake -G"NMake Makefiles" -DCMAKE_TOOLCHAIN_FILE=..\CMake\toolchain\android.toolchain.cmake -DOGRE_DEPENDENCIES_DIR="/path/to/ogredeps/build" -DANDROID_ABI=armeabi -DANDROID_NATIVE_API_LEVEL=9 -DANDROID_TOOLCHAIN_NAME=arm-linux-androideabi-4.8 ..{CODE}

{VERSIONS}
History: CMake Quick Start Guide

Source of version: 67 (current)

Search by Tags

Latest Changes

Search

Online Users
