Building Examples

Introduction

Prerequisites

Environment variables

Project generation using CMake GUI

Project generation using CMake in command line

Creating/Modifying project


Introduction

All example projects files for Linux and MacOS must be generated on the host computer by CMake. For MS Visual Studio the project files are delivered with the package.

CMake is used to control the software compilation process using simple platform and compiler-independent configuration files (see CMakelists.txt in each example directory).
Most rules for specific platforms and architecture are built-in in CMake modules, but all of them can be specifically configured depending on needs. All Open Inventor example-specific rules can be found in the installed CMake directory.

CMake generates native make Makefiles or Visual Studio solutions that can be used in the compiler environment of your choice.

For details information on CMake, please see the official CMake website.

Prerequisites

The following packages must be installed before project files can be generated for the examples.

  • Open Inventor Toolkit
    Note: You must install the version that matches the Open Inventor Demos package you are using.
  • CMake (see System Requirements Overview for more details about CMake version).
    Download it for your specific platform on the CMake Website (main version 3 and at least 3.8.0 or higher)
  • Qt 5.9 : Optional for Windows and Linux. Mandoatory for MacOS.
    If you want Qt-based examples to be built, or if you're using a Mac, you must install the Qt package.
    Installers can be found on the official Qt website http://www.qt.io/download/.

    Recommended version is Qt 5.9 as this is the version we tested and officially support.

  • CUDA/OpenCL (Optional)
    If you want CUDA and/or OpenCL-based examples to be built, you must install the package for your specific GPU.
    Installers can be found on the official website of your GPU providers.

Environment variables

Before generating and building examples example projects, following environment variables must be properly set:

  • OIVHOME must be set to the Open Inventor home installation folder (e.g. C:\Open Inventor\9.4.0 C++ Visual2012 x64 or /Applications/OpenInventor.app/Contents/9.8.0 for MacOS).
  • OIVARCH must be set to the Open Inventor version (e.g. arch-Linux-x86_64-gcc44-release, arch-Windows-x86_64-msvc11-Release, arch-MacOSX-x86_64-clang60-release and so on).
  • LD_LIBRARY_PATH : Only for Linux. This variable must be set to $OIVHOME/$OIVARCH/lib

Here is how to define these variables depending on the Operating System you are running

  1. On linux (tcsh) : 
    1. setenv OIVHOME <path to Open Inventor>
    2. setenv OIVARCH arch-Linux-x86_64-gcc44-release
    3. setenv LD_LIBRARY_PATH $LD_LIBRARY_PATH:$OIVHOME/$OIVARCH/lib
    4. setenv PATH $PATH:<QT installation dir>/bin
  2. On MacOS :
    1. export OIVHOME=<path to Open Inventor>
    2. export OIVARCH=arch-MacOSX-x86_64-clang60-release
    3. export PATH=$PATH:<QT installation dir>/bin
  3. On Windows (batch command line) : 
    1. set OIVHOME=<path to Open Inventor>
    2. set OIVARCH=arch-Windows-x86_64-msvc14-Release
    3. set PATH=%PATH%;<QT installation dir>/bin

Project generation using CMake GUI - Windows

Below the steps to use CMake GUI tool provided by the CMake installer.

  • Setup the Open Inventor examples input directory "Where is the source code" (e.g. E:/OIVofficial/OpenInventorC++980-Windows-Visual2015-x86_64/examples in picture above).
  • Setup the output directory "Where to build the binaries" where all generated files will be stored (e.g. E:/build/tests  in picture above ).
  • Press the Configure button.
  • CMake allows you to select the compiler version project target among those installed on the machine (e.g.: Visual Studio 14 2015 in picture below):

  • After this step, CMake has checked the compiler options and library dependencies on your host computer, and allows you to customize some values:

Most of the time no changes are required. However, if desired, you can change default compiler options, set different paths to third party libraries, or just check that everything has been found correctly using this GUI.

  • If an error occurs, you are warned about it so that you can fix it and press the Configure button again. Repeat as necessary until the "Configuring done" message appears and no longer errors are shown.
  • Press the Generate button, CMake will generate all Makefiles or Projects/Solutions for all examples in the selected output directory:

  • If you have CMake errors, please check that:
    • If OIVHOME and OIVARCH are not set, or wrongly set, CMake will be unable to find Open Inventor binaries needed to generated the demo projects and will generate an error. Be sure these two variables are well defined (please refer to this section for additional details)
    • With Linux: it is important to have this CMAKE_BUILD_TYPE=Release for release version and CMAKE_BUILD_TYPE=Debug for debug version.
    • Verify paths to third party libraries, see page system requirement for details on specific Operating System.
    • For QT make sure the installation has been done properly and that Qt installer updated your environnement variable with correct value (this value are used by CMake to retrieve needed Qt information)

Project generation using CMake GUI - Linux / MacOS

  • Define the requested environment variable : OIVHOME and OIVARCH
  • On MacOS, we recommend to run CMake GUI from command line. If you launch the application using Finder, you may face some environment issue. If you run the classic CMake installation, just enter in a command line shell /Applications/CMake.app/Contents/bin/cmake-gui&. This will bring the following window

  • In this windows you have two settings to set : the path to the examples source (Where is the source code), and where you want to generate the Xcode projects (where to build the binaries). As you can't change the folder where Open Inventor is installed, the first setting will be /Applications/OpenInventor.app/Contents/10.0.0/examples. Once both variables are set, you can click on the Configure button (image below has been taken from an 9.8.2 installation).

  • CMake will then ask you what kind of binaries you want to generate. In the drop down list, select Xcode and click on Done. CMake will then start the configuration needed for the generation.

  • During the configuration step CMake may generated critical error if your environment is not set properly.
    1. If OIVHOME or OIVARCH are not set, CMake will stop because it's impossible to find Open Inventor. Be sure to set environment variable properly before launching cmake-gui in the command line windows. In this case, you will have to quit CMake, check (and fix) your environment, and relaunch CMake for change to be taken in account.
    2. It's also possible that CMake does not find your Qt installation. In this case the following error will be displayed

      In such case, click on Ok, then in the Search text box enter QT5_DIR. CMake will show the actual value of Qt5_DIR variable which will either not being set (value set to QT5_DIR-NOTFOUND) or wrongly set. Click on the button on the right in front of the variable name, it will allow you to specify where is located your Qt installation. Important note : the folder you must select is the one where Qt Cmakefiles are located. It might be something like <Your Qt Installation Folder>/5.9/clang_64/lib/cmake/Qt5 (see image below, taken from a Qt 5.6.2 installation done in folder /Users/buildsystems/Qt5.6.2)

  • Click on configure again so the Qt5_DIR variable will be taken in account and CMake will be able to configure everything with the QT you just specified. Once configuration is done, you might see a window like the one below, with all values automatically set by CMake (note that Qt5 variables may appear on red, but this is not a problem, CMake is just showing what has been updated automatically).

  • Next step is to specify which build type you want. For this, in Search text box just enter CMAKE_BUILD_TYPE and press Enter. Just as before CMAKE will show the value of the variable and it must be empty. You can enter Release or Debug depending on what you intend to do with the demo. Below we decided to build the Release version of the examples. Do not forget to click on Configure for the change to be taken in account.

  • Once the configuration is done, you can check Open Inventor Librairies have been properly selected by CMake. Search for INVENTOR in the Search text box, and a lot of variable will be shown by CMake. Some may be marked as NOTFOUND but these are some unsupported libraries on MacOS. Look for value associated to variable InventorBsae_LIBRARY, it should be set properly like image below

  • Important Note: For MacOS above 10.10 you must also change the compiler version in CMake to allow it to find Open Inventor Librairies. In Search text box type COMPILER and update value of OIV_CXX_COMPILER_VERSION and CMAKE_CXX_COMPILER_VERSION_DOT shown by CMake. In screenshot below (left part) you can see the CMake has been launched on a machine with Clang 9.0. Simply replace values so OIV_CXX_COMPILER_VERSION is set to 60 and CMAKE_CXX_COMPILER_VERSION_DOT  is set to 6.0 like in image below. Valid by clicking on Configure.

    You can then click on the Generate button so CMake will generate the Xcode projects in the folder you defined at the beginning of the procedure. Once the generation is done, you can open the AllModulesExamples.xcodeproj with Xcode application. From there you'll be able to run, debug, modify any examples provided with Open Inventor.


Project generation using CMake in command line

On all platforms you can also use the comand line to generate VcProj (Windows), Xcode (MacOS) or Makefiles (Linux)

Below an example using Linux command line: 

  1. Set environment variable and make sure <CMake Installation Dir>/bin is in the $PATH environment variable (so you can run CMake command from everywhere in your command line window).
  2. Create a new folder for binaries in which you will run the CMake command. This folder must not be inside of the <OIVHOME>/examples folder, for instance <OIVHOME>/buildDemo_release
    1. cd ${OIVHOME}
    2. mkdir buildDemo_release
  3. go inside this new folder : cd <OIVHOME>/buildDemo_release
  1. Type the following command line
    1. On MacOS : 

      cmake -DCMAKE_BUILD_TYPE=Release -DQt5_DIR=<Qt5 Installation Dir>/5.6/clang_64/lib/cmake/Qt5 -DOIV_CXX_COMPILER_VERSION=60 -G Xcode $OIVHOME/examples

    2. On Linux: cmake -DCMAKE_BUILD_TYPE=Release $OIVHOME/examples
    3. On windows: cmake -DCMAKE_BUILD_TYPE=Release -G <Generator Name>* $OIVHOME/examples

*<Generator Name>: on Windows to define the generator you must use:

  • Visual Studio 11 for VS 2012
  • Visual Studio 12 for VS 2013
  • Visual Studio 14 for VS 2015

add Win64 if you want to generate 64 bit vcproj.

So, for example, to generate VS 2015 64 bit vcproj the command line would be : 

cmake -D-DCMAKE_BUILD_TYPE=Release -G Visual Studio 14 Win64 %OIVHOME%/examples

If you have cmake errors please refer to cmake-gui chapter.

Creating/Modifying project

  • To modify an existing project, edit the CMakeLists.txt file located in the source folder of the demos. 
    Do not edit the project files, Makefiles or Visual studio project files (.vcproj/.sln or .vcxproj/.sln) directly, as CMake manages dependencies and they are rebuilt automatically when CMakeLists.txt files are changed.