BuildWithCMake.txt

   1 OGRE CMake BUILD SYSTEM
   2 ========================================================================
   3
   4 Welcome to the new CMake build system for Ogre. This readme file will
   5 explain what CMake is and how you can use it to build the Ogre libraries
   6 and the sample applications.
   7
   8
   9 1. What is CMake?
  10 -------------------
  11
  12 CMake is a cross-platform build system - or perhaps more accurately a
  13 build configurator. It is a program which, from a set of CMake scripts,
  14 creates a native build system for your platform which then allows you
  15 to build Ogre.
  16 The build process is configurable via CMake. Ogre provides several
  17 options which you can use to customise your build.
  18
  19
  20 2. Getting CMake
  21 ------------------
  22
  23 CMake is available from http://www.cmake.org (Resources -> Downloads).
  24 You can get its sources, but there are precompiled binaries for all
  25 platforms. Furthermore, if you are on a Linux system, chances are high
  26 that your distributor offers a package for CMake. You need a CMake
  27 version >= 2.6, though.
  28
  29
  30 3. Basic concepts
  31 -------------------
  32
  33 There are three directories involved in the build process. First is
  34 the source dir where the Ogre sources reside as well as the CMake
  35 scripts. The next is the build dir in which CMake will store the
  36 build configuration and where the generated build system will
  37 create the object files and other intermediate files. In theory
  38 you can use the source dir as the build dir, but this will clutter
  39 the sources with CMake stuff and object files, and there's no easy
  40 way to clean it up again. Therefore I recommend you choose a different
  41 build directory. You might want to create a subdirectory "build" in
  42 your Ogre sources and use that one as the build directory.
  43 Finally there's the install directory. People familiar with Unix know
  44 the concept, this is where the Ogre libraries will finally be copied
  45 to alongside with all the necessary headers and other dependencies.
  46 This is basically where the clean output is put so that you can start
  47 working with it.
  48 The layout of the install directory will resemble that of the Ogre SDK
  49 packages. Under bin, you'll find the sample binaries along with
  50 the necessary .cfg files as well as the DLLs (on Windows). In include
  51 you'll find the Ogre headers, lib contains the link libraries.
  52
  53
  54 4. Using CMake on Windows
  55 ---------------------------
  56
  57 Start CMake from the Start menu. You will notice two entries, "CMake"
  58 and "cmake-gui (beta)". Both are graphical interfaces which work
  59 similar, so you can choose either. I recommend the latter because it
  60 has a cleaner interface.
  61 First, in the field "Where is the source code" enter the path to where
  62 your Ogre sources lie. Then, in the field "Where to build the binaries"
  63 you are required to select the build directory (see above).
  64 Once you have selected the directories, hit the button "Configure" in
  65 the lower left. This will start a first CMake run on the build scripts,
  66 and CMake will ask you to select the build system you want to create.
  67 Choose the appropriate one for your compiler, for example:
  68   Visual Studio 9 2008
  69 Now, CMake will present you with a list of configuration options. They
  70 are explained further down. You can also toggle advanced options (or
  71 select "Group view" from the dropdown box in cmake-gui) where you
  72 will be able to see some more advanced config options. Modify any of
  73 them to your liking. The most important ones are those with the
  74 OGRE prefix. There's also CMAKE_INSTALL_PREFIX which determines where
  75 the built libraries will be installed.
  76 If you get any error messages from CMake, check the log window at the
  77 bottom, it will contain a log of all the actions CMake does. Chances
  78 for errors are that a necessary dependency package was not found.
  79 You might need to manually provide their locations in the advanced
  80 options (or install them in the first place).
  81
  82 Once satisfied with the selected options, hit "Configure" again.
  83 CMake will update its settings. Then hit "Generate" to finally
  84 create the build system.
  85 Now, in your build directory you will find a build system as per
  86 your request. In case of Visual Studio, you should find a solution
  87 file "OGRE3D.sln" which you can open. You will see the usual
  88 projects as well as some custom CMake targets (like ALL_BUILD,
  89 INSTALL etc.). Now do the following:
  90 - Select your build type (Debug, Release, ...)
  91 - Right-click on ALL_BUILD and choose to build it. This will compile
  92 all parts of Ogre that you have enabled in the CMake config.
  93 - If you have doxygen installed (and CMake found it) and you want
  94 to generate the API docs, right-click on the target "doc" and build it.
  95 - Right-click on target INSTALL and "build" it. This will create your
  96 install directory where all necessary include, library und runtime
  97 files will be installed.
  98 - If you want, repeat for a different build type.
  99
 100
 101 5. Using CMake on Linux
 102 -------------------------
 103
 104 Check if cmake-gui is available. If so, you can use it in much the same
 105 way as described in 4. Otherwise you will need to work with the console.
 106 In the console, first change to the directory of the Ogre sources. Now
 107 create a build directory and change to it:
 108   mkdir build && cd build
 109 You need to run cmake from the build directory and provide it with the
 110 location of the build directory. If you followed the above guideline,
 111 then you can simply type:
 112   cmake ..
 113 CMake will now parse the scripts in the Ogre source tree. Watch the
 114 output, especially if all necessary dependencies have been found. If not,
 115 you might need to install the missing ones or provide their locations
 116 manually (more in a minute).
 117 Now, we want to configure the build. Run:
 118   ccmake ..
 119 Which will give you a frontend to configure the CMake build settings.
 120 You will see several available options, those prefixed with OGRE
 121 configure the build process. There's also CMAKE_INSTALL_PATH which
 122 determines where the final libraries will be installed (see 3).
 123 CMAKE_BUILD_TYPE determines the type of build you will get. Available
 124 options are (Release, Debug, MinSizeRel, RelWithDebInfo). Choose
 125 the one you want. There are more options available which you can toggle
 126 with 't'. If any dependency was not found, you need to do this to
 127 set the corresponding variables manually (most importantly
 128 PKG_INCLUDE_DIRS and PKG_LIBRARY, with PKG being the dependency that
 129 wasn't found).
 130 Once you are content with your choices, hit 'c' to configure the build.
 131 Afterwards, hit 'g' to generate a build system. Press 'q' to quit ccmake.
 132 A set of Makefiles have now been generated in the build directory, so
 133 to start the Ogre build, simply type:
 134   make
 135 as usual. This will build all libraries and samples depending on your
 136 CMake settings. Now, if you have doxygen installed and want to create
 137 the API documentation for Ogre, type
 138   make doc
 139 This will invoke doxygen (may take a while...).
 140 Once all is done, you can install the build as usual via
 141   make install (might need root privileges)