Introduction of CMake and the OpenSceneGraph project

The OpenSceneGraph project uses CMake as its unified build system. CMake is able to read simple build scripts from the source tree and create from this a platform-specific build system. This build system can be in the form of VisualStudio project files, Unix Makefiles or XCode project files. CMake is able to automatically locate external dependencies, and allows you to toggle on/off module compilation and configure various build options.

The use of a unified build system has allowed to avoid build breakages that were common in the previous build method of maintaining three separate build targets for VisualStudio, Unix "make" and XCode. It also reduces the maintenance burden for core developers and contributors. Taken together usage of CMake should result in better consistency and more stable builds across all platforms for end users and a greater productivity in development of new versions. Hopefully with greater consistency of builds across platforms it will be easier for developers to use the development version of the OpenSceneGraph and help contribute to its testing and refinement, leading to a high-quality code base.

Where to get CMake

Under Windows, the OSG build system requires CMake version 2.4.6. The Mac OS X Xcode support is still in development so it's probably wise to try out the SVN version on Mac OS X, or ask on the osg-users mailing list about the status.

The choices for getting CMake are:

How to build under Unices (MinGW and Cygwin users: see Windows)

With CMake you can build the OSG libraries and executables in the source directory and have the files placed in the "lib" and "bin" directories, or you can build "out of source". In this case the whole build system, intermediate files and final binaries are built in a separate directory. Building "out of source" is very useful when you need to build multiple targets, such as 32-bit and 64-bit or Release versus Debug. You can also share your source directories across the network and have several platform builds sitting alongside each other, as an "out of source" build keeps the source tree completely clean. In general, CMake strongly recommends and promotes building "out of source".

Note: If you do build in-source, changing your mind later to build out-of-source will require you to manually purge CMake cache files in your source tree, otherwise CMake will get confused.

Using CMake on Unix is done from the command-line. Either use the command "cmake", which just directly creates the build system, or use "ccmake". The latter provides a text-based user interface that opens up in the console that allows you to adjust options. You can also use "make edit_cache", once the build system is built if you wish. (Wiki editing note: what does edit_cache do?)

Building out-of-source (recommended):

# Assuming we're in the directory where the OSG sources 
# are unpacked (usually as the directory "OpenScenGraph")
mkdir build_OpenSceneGraph
cd build_OpenSceneGraph
ccmake ../OpenSceneGraph
# Set build options in the user-interface
# Press 'c' to configure, possible multiple times
# Press 'g' to generate make-files
sudo make install
cd ..

Building in-source:

# Assuming we're in the directory where the OSG sources 
# are unpacked (usually as the directory "OpenScenGraph")
cd OpenSceneGraph
ccmake .
sudo make install
cd ..

Note: If you want to generate a project for a CMake-supported IDE such as KDevelop, you may use the CMake command switch -G<generator-name>. In the example above, you can replace 'ccmake' with 'ccmake -GKDevelop3'.

Building under Windows (includes Microsoft Visual Studio, MinGW, Cygwin, etc)

  • Launch CMake from the Start menu
  • Drag and drop the file CMakeLists.txt from the top of the OSG source directory on the CMake window
  • To build out-of-source (recommended) change the directory in the "Where to build the binaries" field (just add "\build" to the end, for example).
  • Click 'Configure' and choose your compiler/IDE.
  • Fill in missing mandatory fields, if any, and put the paths to any optional libraries you want to build with (CMake pops up an 'Error' dialog in the configuration process if something went wrong).
  • Click 'Generate'
  • The project files should now be generated. If using an IDE, you can open the project in your IDE (when building out-of-source, the project file will be in the directory specified in step 3 above). If generating Makefiles, you should be able to run make on them.

Note: You may also launch CMakeSetup.exe from the command line using the same techniques as the Unix instructions. Just substitute ccmake with CMakeSetup.exe (you will probably need to include the full path unless CMakeSetup.exe is already in your path).

Note: Another handy trick is to add CMake to the "Open with" menu when you right-click on a file. To do that, right-click on the top-level CMakeLists.txt, and go to "Open with..." or "Open with - Choose program...", then click browse and select your CMakeSetup.exe in the CMake installation directory. From then on, when you want to rebuild the project files, just right-click on the top-level CMakeLists.txt file, and go to "Open with - CMakeSetup". An extension binding could be added to .txt files for this, but the above should be sufficient.

Building under Mac OS X

(Wiki-editing note: is this still current?) Currently many Mac-specific features are missing such as Universal Binaries, install_name, and frameworks. However, things can be built without these features in the Unix style. See the Unix instructions above. You may also generate an Xcode project using the CMake switch '-GXcode'.

TODO list

The following items are left to complete:

  1. Fix/standardize Windows 3rd party binaries to use library names that work with standard Find*.cmake modules
    • remove lib prefix on libraries
    • remove version postfix on libraries (e.g. freetype219.dll)
  2. Fix official Findosg*.cmake modules for OSG 2.0. (not required to build OSG)
  3. Use CTest (not required to build OSG)
  4. Demonstration of how to make your own project use OpenSceneGraph and CMake. (optional)
  5. Mac OS X build support for frameworks (requires changes to CMake)
  6. Mac OS X install_name support
  7. Mac OS X Universal Binaries
    • May need changes to CMake for better OS version detection support
    • Should also start 64-bit testing for Leopard
    • Current bug in CMake (explicit -F/System/Library/Frameworks) makes building as Universal fail. Fixed in CMake CVS.
  8. Mac OS X correct CMake INSTALL behavior
    • INSTALL for Unix style probably already works
    • INSTALL for Mac style does not work
  9. Mac OS X build .app bundles
  10. Mac OS X build option using X11 instead of native