Compiling with Visual Studio .NET

(Note: These instructions are valid for Visual Studio .NET 2005 (8.0) and Visual Studio Express 2005 (see below), but they should also apply to Visual Studio .NET 2003 (7.0).)

Initial setup

The project files are set up so that if you have the dependencies in the same base directory as the OpenSceneGraph sources, then it will find them. Thus, the suggested directory structure is:

OpenSceneGraph-VERSION(replace VERSION by 1.2 or SVN or whatever)OpenSceneGraph-VERSION\3rdParty(put the contents of the 3rdParty zip file in here)OpenSceneGraph-VERSION\OpenSceneGraph

Note: for the 3rdParty directory, see Dependencies and download the dependencies for your platform from the osgtoy SVN repo. Place them so that the bin, lib etc. directories are directly under OpenSceneGraph-VERSION\3rdParty .

Generating Project & Solution files with CMake

Start the CMake GUI once it's installed, and select root OpenSceneGraph directory in the "Where is the source code" field. The same directory needs to be put into the "Where to build the binaries" field. If you like to do out-of-source builds, you can add \build to the end. Then click Configure.

You can then customize your build. Some variables will be filled in automatically (such as ACTUAL_3RDPARTY_DIR, if you followed the directory structure above). I typically enable BUILD_OSG_EXAMPLES and set CMAKE_INSTALL_PREFIX to the OpenSceneGraph directory so that the binaries are installed in OpenSceneGraph\bin. You can also set it to somewhere else if you want to keep your source tree clean. Check if the dependencies you have are detected - if not put in the paths manually. Any plugins or examples for which you don't have the dependencies will just not be part of the generated project files, which is cleaner than it was before (the projects would be there but just refuse to build, which resulted in lots of noise when building for things you knew would not build anyway).

Once your build configuration is to your liking, click Configure one last time and then click OK (Generate).

Building with Visual Studio

Open the generated OpenSceneGraph.sln file, which will be in the directory you entered unde "Where to build the binaries" (eg. OpenSceneGraph\build), with Visual Studio. Select your desired build type (Debug, Release, RelWithDebugInfo, MinSizeRel) and press F7 for "Build Solution". Assuming everything builds correctly, you can then right-click on the INSTALL project and build that, which will copy the compiled files to the correct directories (based on what you set CMAKE_INSTALL_PREFIX to). Before that, the compiled files all reside in the build directory, and I don't recommend you use them from there.

Just to reiterate: Always build the INSTALL project. The locations where the files are copied to as part of the INSTALL target are the correct locations from where you should use them (bin\ for application executables and DLLs, lib\ for libraries, include\ for headers, and share\OpenSceneGraph\bin\ for example executables). See "Environment variables" below for some tips to set up your build environment for your own project to use the files from the correct locations.

Notes

Compilation time

A word of warning, the first time you compile from source it will take some time. After that, if you update an SVN checkout for example, it will compile incrementally (only what changed) so that's quite a bit faster.

Always regenerate after checkouts

Note also that you should regenerate the project files with CMake each time you update from SVN or update to a newer snapshot of the source code. That will make sure that a) any new build configuration options added to the CMake build files will be taken into account, and b) any new files will be included in the VS projects and compiled correctly. You can regenerate the build files by just opening the root CMakeLists.txt in the CMake GUI and setting the build directory to the same thing you had before (OpenSceneGraph\build, for example), that way any settings you had made will still be there. Just click Configure then Generate, open the OpenSceneGraph.sln and build.

Freetype plugin

If have the 3rdparty libraries installed, the BUILD_OSG_PLUGINS is ON in your CMake file and the FREETYPE_LIBRARY_DEBUG path is found it might still happen that the project files for Freetype plugins or not built. Select "Show Advanced Values" in CMake and copy the directory found in FREETYPE_INCLUDE_DIR to FREETYPE_INCLUDE_DIR_freetype2 and FREETYPE_INCLUDE_DIR_ft2build.

Cleanup the CMake cache

Finally, note that from time to time, to see new settings, you will need to delete the CMakeCache.txt file in the build directory, which will also erase your settings... This should be rare though.

Using Visual Studio Express 2005/2008

Visual Studio Express is a free Microsoft development system, a complete Visual Studio based on Visual Studio .NET 2005/2008, with all the features of VS 6 (debugger, icon designer, MS interface developer) . The download is free but a pretty large download; the license is perpetual but MS reserve the right to charge after Nov 2006. You can also download C#, J# and other studio components. You will also need the Platform SDK to provide links and some needed libraries.

For 2005, please follow the instructions at this page to download the Platform SDK (which is included with commercial versions but a separate download for the Express 2005 version). Also, it appears that some features of VS, such as ability to produce a Console application, are hidden until you modify the configuration files (instructions also at the previous link, at the bottom of the page). These notes do not apply for Visual C++ Express 2008.

See the instructions for Visual Studio .NET above to compile OpenSceneGraph with Visual Studio Express 2005/2008.

All in all it works as well as the commercial version (Visual Studio .NET 2005/2008).

Note that the Express Edition does not include MFC, so any example written for MFC will fail to build (currently, osgviewerMFC). There is now an option in the CMake setup to disable building the MFC example, which is the default, so that takes care of that.

Compiling with Visual Studio 6.0

With the advent of Visual Studio Express 2005 (see above), going through all the hoops required to get OpenSceneGraph to compile on Visual Studio 6.0 seems a lot less appealing. It's probably a lot easier to just install VS Express and the Platform SDK and use those. You get a free, up-to-date compiler and development environment in which you can work, and you don't need to worry about VS 6's issues. Nonetheless, instructions to get OpenSceneGraph to compile in Visual Studio 6.0 follow.

STLport instructions

Please use STLport-4.5, since earlierer and newer versions cause more or less problems!!!
You only need the header files supplied with stlport - no need to compile or edit the code installed, with the following exception:

Edit stlport/stl_user_config.h at about line 45 (your's may vary) and comment _IN_ (should be commented _OUT_ by default)

# define _STLP_NO_OWN_IOSTREAMS 1

Set the include file paths (under tools Options..., subtab Directories) to include the stlport include directory, and raise this directory up the list of include search paths (or else MS's old and non-useful stl will be used first). This is a good opportunity to add the Openthreads & Producer include file paths as well since they will be used by many projects.

The Directories tab can also be used to set search path for libraries - set these to include
Producer & Openthreads.

The .dsp files included with the 1.2 versions of OpenSceneGraph, Producer, and OpenThreads have some settings that are not compatible with VS 6, in order to enable 64 bit builds in VS 8. These settings must be changed, prior to building with VS 6, by replacing all instances of:

$(PlatformName) with win32, and

$(ConfigurationName) with Debug or Release as appropriate.

A Perl script is in OpenSceneGraph/VisualStudio/fixup-vc6-dsps.pl to perform these changes automatically. Run it using either Windows or Cygwin Perl.

Extensionless headers and syntax highlighting on Visual Studio 6

The OpenSceneGraph uses Standard C++ style extensionless headers, which poor Visual Studio doesn't automatically recognize as suitable for syntax highlighting (compile works fine though), even the Standard C++ header themselves require a hack to get Visual Studio to highlight them properly. The easy answer is to use that same hack to get it to recognize the OpenSceneGraph headers too. To make easy a modified header listing file can be found in the VisualStudio?/LANDEXT.DAT. First copy the original LANDEXT.DAT file (located in C:\Progam Files\Microsoft Visual Studio\Common\MSDev98\Bin) to LANDEXT.DAT.BKP, and then copy over the OpenSceneGraph one. Once you have done this Visual Studio will syntax highlight them without problem.

In the OSG sources, in the PlatformSpecifics?\Windows directory, there is a text file "VisualStudio?_Syntax_Highlighting.txt" in which you can find instructions to get syntax highlighting on extensionless header files. It basically says:

Go to Tools-Options, then Text Editor-File Extension, check "Map Extensionless Files To" at the bottom and select "Microsoft Visual C++" in the list to the right.

Starting a new project

There are two basic ways to start a new project using the OSG.

Create a new solution and project, and add the OSG libs as dependencies

Pros:

Keeps everything separate, you can keep a tight control over the files in your project.

If your own project is in SVN, it won't conflict with the OSG SVN.

It's easy to distribute your project.

Cons:

If you need to modify the OSG or look something up, you need to open the OSG's workspace/solution separately.

I normally start the project by copying OpenSceneGraph\applications\osgViewer\osgViewer.cpp into my new project's src directory, and compiling that. If that doesn't compile and run, there's a problem. See "Environment Variables" below for how to set up the compiler's include and library search paths easily. -- Jean-Sebastien Guay

Create a project directly in the OSG workspace / solution

Pros:

If you have to modify OSG itself for your project, the Visual Studio dependency check will recompile what is needed automatically.

You can quickly switch from the project on which you're working to the OSG code itself.

You can examine code for any src/example easily.

Cons:

Your OSG workspace/solution will quickly become crowded once you start adding lots of your projects to it (as if it wasn't enough already...).

When you regenerate the build files with CMake, you will have to re-add your project(s) to it.

It's hard to separate your project from the OSG for distribution, so the other way is "cleaner".

You can't keep your project in SVN if your OSG directories are also from SVN, unless you copy your project's files somewhere else, in which case why don't you just use the first method instead of having to do both?

I guess you can see that I don't recommend this way of doing. The OSG workspace/solution is already so big as it is, I think it's best to keep your mind uncluttered by creating a separate project for your own stuff. The rest of this guide is based on using the first option. -- Jean-Sebastien Guay

Environment variables

If you select the first method, a way to simplify things and to make your project files work on multiple different machines is to use some standard environment variables. I use the following:

Then, add %OSG_BIN_PATH% and %OSG_SAMPLES_PATH% to your PATH environment variable. That way, not only can you run examples easily, but the latest DLLs will always be found. When starting an application, Windows looks for the required DLLs first in the executable's directory, then in the PATH.

In your project's properties, use those environment variables to get Visual Studio to find the OSG libraries. Here are the settings I use:

Remember to do the same thing in your project's Debug configuration, but add a d to the end of the OSG and OpenThreads library names (osg.lib becomes osgd.lib and so on).

Once that's done, your project should be able to compile, link and run. If not, you can test your paths in a console (Start-Run, type cmd, press enter), by for example typing echo %OSG_LIB_PATH% or dir %OSG_LIB_PATH%. With those commands you should be able to see what is wrong.

Important note about plugins

Once in a while, we get a message on the mailing list asking why the version number is added to the bin\osgPlugins directory name. Normally, the reason they ask is that after updating their copy of OSG, they had to modify their project files or their PATH to change the version number to point to the new directory.

There is never a need to add that directory to your library search paths or PATH environment variable. The OSG knows how to find the plugins by itself. In general, it will try to add osgPlugins-<version> to the directories in your PATH until it finds the right one. And since it knows its own version, it will find the right plugins directory.

If you had to add that directory to your PATH, for example in order to get examples to load the .osg files (cow.osg for example), that means that you didn't build the INSTALL target after compiling OSG. In that case, the plugins will reside in directories like ...\OpenSceneGraph\build\lib\osgPlugins-<version>\release. So the problem is not the version added to the directory name, it's the lib instead of bin, and the release subdirectory. That's because CMake builds DLLs in the lib tree, and then the INSTALL target copies them to the bin tree, more specifically to ...\OpenSceneGraph\bin\osgPlugins-<version>. And since ...\OpenSceneGraph\bin is on your PATH, OSG will find them fine.

More generally, you should never have to put a reference to a subdirectory of the build directory into your environment variables. That is just a temporary location where things get built. Once the INSTALL target is run, the files will be in their final locations, which are bin\ for application executables and DLLs, lib\ for libraries, include\ for headers, and share\OpenSceneGraph\bin\ for the example executables.