Building OpenFrames

This page under construction

Building OpenFrames in Windows, Linux, and Mac Operating Systems

Overview

The OpenFrames build process can be broken down into four main steps:

1. Download and configure the dependencies
2. Create the build system using CMake
3. Build OpenFrames
4. Run OpenFrames
   The first two steps are generally "one-time" processes that are performed immediately after downloading the OpenFrames repository. They result in a build system (e.g. Visual Studio solution or makefiles) that will intelligently rebuild OpenFrames components as needed when source or configuration files are changed.

Below are step-by-step instructions on how to perform the aforementioned steps along with the background requirements that are needed before beginning.

Requirements

• OpenSceneGraph:
  • Windows: See the Building OpenSceneGraph in Windows wiki
  • Mac: See the Building OpenSceneGraph in Mac wiki
  • Ubuntu: See the Building OpenSceneGraph in Ubuntu 16.04 wiki
  • CentOS 7: See the Building OpenSceneGraph in Centos 7 wiki
• Choice of Git Client such as:
  • SourceTree - a GUI git and mercurial client
  • Git for Windows - a command line linux style shell and with git support or GUI based (runs over included MINGW)
• CMake to generate build systems on Mac OSX, Windows, and Linux. (used 3.12 as tested)

• Additional Requirements:

  • Windows:
    • Microsoft Visual Studio to run build and install processes (used VS 2013 Community edition ver 12.0.40629.00 Update 5 as tested)
      Note: MVS is freely available, however, one must register with Microsoft and login to the account within MVS to activate the free license.
    • These instructions were tested under Windows 10
  • Mac:
    • XQuartz v2.7.9 or greater
    • XCode v7.2 or greater. Available for free through the Mac App Store
  • Ubuntu 16.04:
    • GCC (version 5.3.1 as tested). sudo apt install gcc and dependencies.
  • CentOS 7:
    • GCC (version 4.8.5 as tested). sudo yum install gcc-c++ and dependencies.

• (Optional if you want to build the Winteracter demo) Winteracter Open Motif. Download the latest static library for your architecture (32 or 64-bit) and place it in a convenient location. It is recommended to place it in the Winteracter lib directory (e.g. lib.ifi64) next to the existing Winteracter libraries.

Step 1: Download OpenFrames

1. Get the OpenFrames Git repository. See here for the link. When checking out, ensure you have selected the "develop" branch instead of the "Master" branch.
2. The root OpenFrames folder will be referred to as [OF_FOLDER] in this page

Step2: Setup OpenFrames Build System

Windows/Mac:

(The following steps correspond to the numbered arrows in Figure 1 below.)

In CMake:

1. Specify [OF_FOLDER] as the Source Code location.
2. Specify [OF_FOLDER]\Win64build as the Build Binaries location. (Mac: [OF_FOLDER]/X11-build). Note: CMake makes slashes forward slashes
3. Click "Add Entry", and specify the following:
   • a. Name = OSG_DIR
   • b. Type = PATH
   • c. Value = Path to your [OSG_FOLDER]\install directory. (Mac: [OSG_FOLDER]/X11-install)
   • d. Description = empty
4. (Optional if you want to build the Winteracter example) Click "Add Entry", and specify the following:
   • a. Name = WINTER_ROOT
   • b.Type = PATH
   • c.Value = Path to your Winteracter \wint directory, e.g. C:\Users\xyz\Documents\wint
   • d.Description = empty
5. Press the "Configure" button
   • a. Say "ok" if you are asked to create the 'build' folder. (Mac: ' X11-build' folder)
   • b. Windows: Verify the default generator choice (Visual Studio 12 2013 Win64 in our case) or choose a different one. Check "Use default native compiler" (See Figure 2)
     • Mac: Select "unix makfiles" as the build system.
   • c. Click "finish"

Figure1: CMake GUI

Figure 2: CMake Specifications

Note: If you get a CMake error "OpenSceneGraph NOT FOUND", make sure you specified OSGDIR correctly (Step 3 above).
Note: If you get a CMake warning "Open Motif NOT FOUND", see below to set the path to libXm if you want to build the Winteracter demo.

Set CMake Variables:
The configure process sets up build variables that can be modified before generating the actual build system. The variable list can be organized by clicking the "Grouped" button. Set the following variables: (See Figure 3)
a. CMAKE_INSTALL_PREFIX = [OF_FOLDER]\OpenFrames-Windows-install
b.Select OF_FORTRAN_MODULE to build the Fortran interface and Winteracter example
c. Optional: Use CMAKE_LIBRARY_PATH to specify the directory containing Open Motif (libXm) if you are building the Winteracter example. Only needed if you did NOT place libXm next to the installed Winteracter libraries. (see Requirements above)

Finally, create the build system:
a. Press the "Configure" button again to enable the variable changes you just made
b. Press the "Generate" button to create the build system
c. Exit CMake

Figure 3: CMake Variables

Ubuntu 16.04/Centos 7:

In Terminal:

1. cd [OF_FOLDER]
2. mkdir build
3. mkdir install
4. cd build
5. cmake ..
6. ccmake -D OSG_DIR:PATH=[OSG_FOLDER]\install -D CMAKE_CXX_STANDARD=11 . (terminal based cmake that displays information in a textual based interface)
   • CMAKE_INSTALL_PREFIX = \[OF_FOLDER\]\install
   • press [c] to configure
   • if any XXX_LIBRARY file path is not found edit the entry (may require advanced mode edit):
     • XXX_LIBRARY= \[OSG_FOLDER\]\install\lib64\<filename>.so see reference below.
     • press [c] to configure
   • press [q] to quit
7. (OPTIONAL) ccmake -D WINTER_ROOT:PATH=Path to your Winteracter . (terminal based cmake that displays information in a textual based interface)
   • press [c] to configure
   • press [g] to generate
   • press [q] to quit
8. cmake ..

Step 3: Build and Install OpenFrames

Windows:

In Visual Studio: (See Figure 4.)

1. File->Open Project and navigate to [OF_FOLDER]\Win64build folder. Choose OpenFrames.sln and click "Open".
2. The Solution Explorer window will have ALL_BUILD selected
3. By default the Debug build solution may be selected. Choose the Release build solution and perform build (Build->Build Solution)
4. Once the build is complete perform the installation:
   • a. Within Solution Explorer window, find the list of CMakePredefinedTargets under ALL_BUILD, INSTALL etc. in the Solution Explorer window. (Highlighted in Figure 4.)
   • b. Right-click INSTALL, left-click build
5. Confirm that the ofsplitwindow executable is in [OF_FOLDER]\OpenFrames-Windows-install\bin (See Figure 5)

Figure 4: MS Visual Studio

Figure 5: Browse to locate ofsplitwindow

Mac/Ubuntu 16.04/CentOS 7:

In Terminal:

1. Go to the [OF_FOLDER]\build folder. (Mac: [OF_FOLDER]/X11-build)
2. Type make, or make -jN where N is the number of cores your computer has
3. Type make install to install the compiled OpenFrames into the [OF_FOLDER]/OpenFrames-Darwin-install folder
4. Confirm that the test1 executable is in [OF_FOLDER]/X11-Darwin-install/bin

Step 4: Test OpenFrames

Windows:

In System Properties:

1. Select the "Advanced" tab on your Windows machine.
2. Click on "Environment Variables" button (See Figure 6)
3. Edit Path under "User Variables". If Path doesn't exist, then create it. (See Figure 7)
4. Add [OF_FOLDER]\OpenFrames-Windows-install\bin to the Path by clicking "Edit" once Path is selected. Add the path as a new line in the table
5. Create a new user environment variable named OSG_FILE_PATH, and set its value to [OF_FOLDER]\install. This will allow OpenFrames demos to find their resources (images, models, etc.). If OSG_FILE_PATH variable already exists, then append the new value to its end by clicking "Edit" and adding a path as a new ling in the table
6. Click OK to close the editor dialog
7. Click OK to close the Environment Variables dialog
8. Open a new terminal (so the above changes take effect), change directory to [OF_FOLDER]\OpenFrames-Windows-install\bin and type ofsplitwindow. It should bring up a window where the top half has satellites orbiting the Earth, and the bottom half has a 3D time-history plot of one of the satellites.

Figure 6: Enviornment Variables

Figure 7: Environment Variables

Mac:

In Terminal:

1. Add the following to your .bash_profile (or equivalent) login file:

    export OF_ROOT=/path/to/OpenFrames-Darwin-install
    export DYLD_LIBRARY_PATH=$DYLD_LIBRARY_PATH:$OF_ROOT/lib

• Open a new Terminal window (so the above changes take effect), go to the OpenFrames-Darwin-install/bin folder, and type ./test1. XQuartz will launch (if not already running), and an OpenFrames example should run.

Ubuntu 16.04/CentOS 7:

In Terminal:
1. make sure that LD_LIBRARY_PATH locates the libraries for OSG and OF
* export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:[OF_FOLDER]\install\lib:[OSG_FOLDER]\install\lib64
2. cd [OF_FOLDER]\install\bin
3. ./test1

OpenFrames is now built and installed.

[Randy Eckman]

Step 4: Test OpenFrames, Windows, Step 5: I think the value of OSG_FILE_PATH should be [OSG_FOLDER]\install, not OF_FOLDER.