Version 7 (modified by martin, 7 years ago)

--

Introduction of CMake and the OpenSceneGraph project

The OpenSceneGraph and OpenThreads projects have move across (in their SVN versions) to using [CMake] for a unified build system. CMake is able to read simple build CMakeLists.txt scripts in the source tree and create from this platform specific build system, be in 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 unified build system has allowed us to avoid build breakages that were common when maintaining the three separate build targets of VisualStudio, Unix make and !XCode, and reduces the maintenance burden on core developers and contributors. Taken together we'll see better consistently and more stable build across all platforms for end users and a greater productivity in development of new versions, and quicker convergence towards releases. We expect with greater consistency of build across platforms it'll be easier for developers to use 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, we require the CMake version 2.4.6. The OS X Xcode support is still in development so you'll probably need to try out the SVN version.

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

The unix build system is done via the command line console either using cmake which just directly creates the build system, or ccmake which provide 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 your wish. With CMake you build the libs and exectuables in the local source directories and placed in the local lib and bin directories, or build "out of source", with the whole build system, intermediate files and final libs being 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 share your source directories across the network and have several platform builds sitting alongside each other. It also 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.

Building in source:

cd OpenThreads
ccmake .
make
sudo make install
cd ..

cd OpenSceneGraph
ccmake .
make
sudo make install
cd ..

Building out of source (recommended):

mkdir build_OpenThreads
cd build_OpenThreads
ccmake ../OpenThreads
make
sudo make install
cd ..

mkdir build_OpenSceneGraph
cd build_OpenSceneGraph
ccmake ../OpenSceneGraph
make
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>. So above, you might replace 'ccmake' with 'ccmake -GKDevelop3'.

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

  • Launch CMake from the start menu
  • Drag and drop CMakeLists.txt on the frame
  • 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

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. missing from !CMake build support:
    • src/osgPlugins/dae (COLLADA plugin)
    • src/osgPlugins/jp2 (JPEG200 plugin)
    • src/osgPlugins/pfb (Performer plugin)
    • src/osgPlugins/vrml (libvrml based plugin)
    • src/osgPlugins/xine (xine-lib based plugin)
  2. Versioning of library names.
  3. Finish Doxygen documentation generation for OSG. (OpenThreads might be done.)
  4. 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)
  5. Test static library building (the link order of libraries looks wrong to me).
  6. Fix official Findosg*.cmake modules for OSG 2.0. (not required to build OSG)
  7. Use CTest (not required to build OSG)
  8. Use CPack?
  9. Demonstration of how to make your own project use OpenSceneGraph and CMake. (optional)
  10. Mac OS X build support for frameworks (requires changes to CMake)
  11. Mac OS X install_name support
  12. 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.
  13. Mac OS X correct CMake INSTALL behavior
    • INSTALL for Unix style probably already works
    • INSTALL for Mac style does not work
  14. Mac OS X build .app bundles
  15. Mac OS X build option using X11 instead of native