1# Guide to building OGRE {#building-ogre} 2 3Ogre uses [CMake](https://cmake.org/) as its build system on all supported platforms. 4This guide will explain to you how to use CMake to build Ogre from source. You need a CMake version >= 3.3. 5 6What is CMake? 7------------------- 8 9CMake is a cross-platform build system - or perhaps more accurately a 10build configurator. It is a program which, from a set of CMake scripts, 11creates a native build system for your platform that allows you to 12build Ogre. 13The build process is configurable via CMake. Ogre provides several 14options which you can use to customise your build. 15 16Preparing the build environment 17------------------------------------ 18 19You should now create a build directory for Ogre somewhere outside 20Ogre's sources. This is the directory where CMake will create the 21build system for your chosen platform and compiler, and this is also 22where the Ogre libraries will be compiled. This way, the Ogre source 23dir stays clean, and you can have multiple build directories all 24working from the same Ogre source. 25 26Getting dependencies 27-------------------- 28 29By default ogre will build the essential dependencies automatically when you run cmake the first time. If you would rather use system wide libraries set `OGRE_BUILD_DEPENDENCIES=OFF`. 30 31Ogre will install the dependencies into the subfolder `Dependencies` in the build dir by default. You can configure it by setting `OGRE_DEPENDENCIES_DIR` in cmake. For instance to point to a common dependencies folder for all of your projects. Inside 32this directory you must have the subdirectories bin, lib and include 33where you place .dll, .lib and header files of the dependencies, respectively 34 35On linux you additionally need the following system headers to build the GL RenderSystems (command for Ubuntu): 36 37 sudo apt-get install libgles2-mesa-dev libxt-dev libxaw7-dev 38 39furthermore we recommend installing the following optional packages 40 41 sudo apt-get install nvidia-cg-toolkit libsdl2-dev doxygen 42 43these will enable input handling in the SampleBrowser and building the documentation. 44 45If you cannot obtain prebuilt binaries of a dependency for your platform, 46please refer to the list below and get a source package from the website, 47then build it according to its documentation. 48 49### Essential dependencies: 50 51* freetype: http://www.freetype.org 52 53### Recommended dependencies: 54 55* zlib: http://www.zlib.net 56* zziplib: https://github.com/paroj/ZZIPlib 57* SDL: https://www.libsdl.org/ 58 59### Optional dependencies: 60 61* DirectX SDK: http://msdn.microsoft.com/en-us/directx/ 62* FreeImage: http://freeimage.sourceforge.net 63* Doxygen: http://doxygen.org 64* Cg: http://developer.nvidia.com/object/cg_toolkit.html 65* Boost: http://www.boost.org (+) 66* POCO: http://pocoproject.org (+) 67* TBB: http://www.threadingbuildingblocks.org (+) 68 69(+) can be used for threading instead of `std::thread` 70 71Running CMake 72------------- 73 74Now start the program cmake-gui by either typing the name in a console 75or selecting it from the start menu. In the field *Where is the source 76code* enter the path to the Ogre source directory (the directory which 77contains this file). In the field *Where to build the binaries* enter 78the path to the build directory you created. 79Hit *Configure*. A dialogue will appear asking you to select a generator. 80 81Check the [CMake documentation](https://cmake.org/cmake/help/latest/manual/cmake-generators.7.html) for details on which one is appropriate for your platform and compiler. 82@note on OSX, you must to use the Xcode generator to get a proper SampleBrowser .app bundle. 83 84Click *Finish*. CMake will now gather some information about your 85build environment and try to locate the dependencies. It will then show 86a list of build options. You can adjust the settings to your liking; for 87example unchecking any of the `OGRE_BUILD_XXX` options will disable that 88particular component from being built. Once you are satisfied, hit 89*Configure* again and then click on *Generate*. CMake will then create 90the build system for you. 91 92Building 93-------- 94 95Go to your chosen build directory. CMake has generated a build system for 96you which you will now use to build Ogre. If you are using Visual Studio, 97you should find the file OGRE.sln. Open it and compile the target 98*BUILD_ALL*. Similarly you will find an Xcode project to build Ogre 99on MacOS. 100 101If you rather want to trigger the build form a console, then cd to your build directory and call the appropriate make program as 102 103 cmake --build . --config release 104 105to start the build process. 106 107If you have doxygen installed and CMake picked it up, then there will 108be an additional build target called *OgreDoc* which you can optionally build. 109This will freshly generate the API documentation for Ogre's classes from the header files. In Visual Studio, just select and build the target *OgreDoc*, on Linux type: 110 111 make OgreDoc 112 113 114Installing 115---------- 116 117Once the build is complete, you can optionally have the build system 118copy the built libraries and headers to a clean location. We recommend 119you do this step as it will make it easier to use Ogre in your projects. 120In Visual Studio, just select and build the target *INSTALL*. For Makefile based generators, type: 121 122 123 make install # (or sudo make install, if root privileges are required) 124 125 126On Linux Ogre will be installed to `/usr/local` by default. On Windows this will create the folder `sdk` inside your build directory and copy all the 127required libraries there. You can change the install location by changing the variable `CMAKE_INSTALL_PREFIX` in CMake. 128 129 130Building on Mac OS X for iOS OS 131------------------------------- 132 133To build Ogre for iOS, you need to specify the ios cross toolchain to cmake as 134 135 cmake -DCMAKE_TOOLCHAIN_FILE=CMake/toolchain/ios.toolchain.xcode.cmake -G Xcode . 136 137 138Unfortunately, you will now have to do a few manual steps to 139make the generated build system work properly. 140 141A Xcode project has now been generated in the build directory, so 142to start the Ogre build, open OGRE.xcodeproj and build as usual. 143To run samples on your device you will need to have a valid iOS Developer 144certificate installed. For each sample, double click on target in the Groups & 145Files list. Ensure that a valid identity is selected in the Code Signing Identity 146drop menu. 147Also, because we can't tell CMake what Xcode project format you want, you will 148have to change it yourself. Open the Project Menu, choose Edit Project Settings. 149Click on the General tab in the settings window. Change Project Format to 150Xcode 3.1-compatible. 151And another thing. You will need to manually set the Bundle Identifier property of 152the Info.plist file to match the App ID of the chosen code signing identity. 153This can be done from the Target Properties panel. It must match the bundle 154identifier of a valid developer certificate if you are building for devices. 155 156Building as Windows Store or Windows Phone application 157------------------------------------------------------------------- 158 159You need Windows 8.0 or later, Windows 10 is recommended. 160 161You need Visual Studio 2012 or later, Visual Studio 2015 is recommended 162as it is bundled with Universal 10.0.240.0, WinStore 8.0/8.1 and WinPhone 8.0/8.1 SDKs. 163 164Download and install CMake 3.4 or later. 165 166Patched dependencies must be used, compiled with appropriate WINAPI_FAMILY. 167Cg is not supported. 168You can use https://bitbucket.org/eugene_gff/ogre-dependencies-winrt - 169has VS2012 and VS2013 projects for Win32, WinRT (can be reused for WinPhone) 170Compile dependencies for all configurations that you plan to use before 171running CMake. Dependencies for Win32 and for WinRT must be located in 172separate folders, Win32 version can be built from OgreDependencies.VS201x.sln, 173WinRT from OgreDependencies.VS201x.WinRT.sln 174 175Run CMake, specify source and binaries folders, than "Configure", select 176"Visual Studio 14 2015" generator and "Specify options for cross-compiling" 177option, specify Operating System = "WindowsStore" or "WindowsPhone", 178Version = "8.0", "8.1" or for UAP Operating System = "WindowsStore", Version = "10.0.10240.0", "10.0.10586.0" then "Finish", specify WinRT dependencies folder 179for OGRE_DEPENDENCIES_DIR, "Configure", should be no more errors, then press 180"Generate". 181 182Select SampleBrowser as the start up project and run. 183 184### Notes 185 1861. The code and generated CMake solution should be on local NTFS drive, 187and can't be on a network drive, including VMWare shared folders - or 188you will get a errors when you will try to compile/link/run resulting exe. 189 1902. Ogre uses d3dcompiler_xx.dll to compile shaders, and WinStore and 191WinPhone 8.1 projects can use it without restriction as it is part of OS. 192But WinStore and WinPhone 8.0 applications should load already compiled 193shaders from cache, as d3dcompiler_xx.dll is available to them only during 194development. Therefore to avoid necessity to deploy d3dcompiler_xx.dll 195during development (additional configurations with d3dcompiler_xx.dll) 196and generation of such cache - use version 8.1 of these platforms. 197 1983. Running WinPhone emulator in OS running under VMware: 199We were able to run the emulation and debug without an issue by using two 200steps: (a) Under the settings of the VM > CPU, make sure you have the 201option to pass-through the Intel VT-x/EPT feature, (b) Edit the config 202file .vmx and add the parameter: hypervisor.cpuid.v0 = "FALSE" 203All versions of Visual Studio 2012 have a window refresh issue when running 204in VMware and the window is maximized, the solution is just to change the 205size of the Visual Studio window to be less the the screen width and height. 206 207Building on Ubuntu for Android 208-------------------------------------------- 209 210To build Ogre for Android, you need to specify the ios cross toolchain to cmake as 211 212 cmake -DCMAKE_TOOLCHAIN_FILE=CMake/toolchain/android.toolchain.cmake -DANDROID_NDK=path/to/android-ndk . 213 214this will build the core Ogre libraries. Also if your `PATH` contains the `android` executable it will generate the SampleBrowser APK. 215 216To manually generate the APK and install it on your device, run 217 218 ant debug install 219 220Building for HTML5 (Emscripten) 221----------------------------------------- 222Install the Emscripten SDK and make sure that the environment variables are correctly set. 223 224Run cmake in cross compile mode using emscripten as following: 225 226 cmake -DCMAKE_TOOLCHAIN_FILE=$EMSCRIPTEN/cmake/Modules/Platform/Emscripten.cmake . 227 228in cmake GUI change `CMAKE_AR` to `emcc`. Then run `make`. 229 230this will not build the full SampleBrowser, but just a minimal Sample. The resulting `EmscriptenSample.html` will be placed in `${CMAKE_BINARY_DIR}/bin/`. 231 232To prevent any cross-origin issues, start a local webserver as `python3 -m http.server 8000` and visit `localhost:8000`. 233