= Installing OSG on Windows with MinGW and Eclipse (including COLLADA) =
This tutorial describes how to set up OpenSceneGraph (optionally including the COLLADA plugin) with the Eclipse IDE and the MinGW compiler on Windows XP. The goal is to be able to develop projects using OpenSceneGraph rather than modifying the OpenSceneGraph source code. As always, unfortunately, free software and source code - at least on Windows - is a mess and some things just take forever to figure out. Hence this tutorial. The following is a list of packages used in this tutorial. Keep in mind that if you're using different versions or setups than these, the steps described here may change. Go ahead and install these packages (or unzip if required). You may use different installation directories. In the tutorial, simply replace the suggested directories with the ones you used.
== Packages Used in This Tutorial ==
* MinGW 5.1.4
* This includes the GCC compiler, linker, and everything else you need to build your software.
* '''Link''': http://sourceforge.net/project/showfiles.php?group_id=2435
* '''Download''': Automated MinGW Installer
* '''Target directory''': C:\MinGW
* '''Note''': Add C:\MinGW\bin to your PATH environment variable. See [http://www.computerhope.com/issues/ch000549.htm here] on how to do that.
* MSYS 1.0.10
* This is a basic Linux-like shell needed to compile the COLLADA DOM. You don't need this if you're not going to install the COLLADA plugin.
* '''Link''': http://sourceforge.net/project/showfiles.php?group_id=2435
* '''Download''': MSYS Base System > Current release: msys-1.0.10 > MSYS-1.0.10.exe
* '''Target directory''': C:\MSYS
* MSYS coreutils 3.81
* This is an add-on to MSYS which contains the fmt command needed to make the COLLADA DOM. You don't need this unless you're going to install the COLLADA plugin.
* '''Link''': http://sourceforge.net/project/showfiles.php?group_id=2435
* '''Download''': MSYS Base System > Technology Preview: MSYS-1.0.11 > coreutils-5.97-MSYS-1.0.11-snapshot.tar.bz2
* '''Target directory''': Save in C:\MSYS
* CMake 2.6.0
* OpenSceneGraph uses CMake to set up the sources and makefiles for your platform and environment.
* '''Link''': http://www.cmake.org/HTML/index.html
* '''Download''': Windows (Win32 Installer)
* '''Target directory''': C:\CMake
* Eclipse 3.3.2
* This is your IDE. If you already have Eclipse installed, you may instead add the CDT plugin for C/C++ development but the steps described in this tutorial are based on this specific download.
* '''Link''': http://www.eclipse.org/downloads/
* '''Download''': Eclipse IDE for C/C++ Developers
* '''Target directory''': C:\Eclipse
* Doxygen 1.5.6
* Doxygen creates documentation from your source code (and from the OpenSceneGraph source code). This one is optional.
* '''Link''': http://www.stack.nl/~dimitri/doxygen/download.html#latestsrc
* '''Download''': A binary distribution for Windows 95/98/ME/NT/2000/XP/Vista
* '''Target directory''': C:\Doxygen
* !GraphViz 2.18
* !GraphViz will generate the class inheritance tree graphics in your documentation. You don't need it if you don't generate the Doxygen documentation. And even then, you don't necessarily have to generate the inheritance trees.
* '''Link''': http://www.graphviz.org/Download_windows.php
* '''Download''': Windows > graphviz-2.18.exe
* '''Target directory''': C:\!GraphViz
* '''Note''': If you're prompted with something about a previously installed version, simply press "Yes".
* !OpenSceneGraph 2.6.1
* This contains most sources you'll need.
* '''Link''': http://www.openscenegraph.org/projects/osg/wiki/Downloads/DeveloperReleases
* '''Download''': source package: OpenSceneGraph-2.6.1.zip
* '''Target directory''': C:\!OpenSceneGraph
* COLLADA 2.1.1
* This is needed in order to import/export COLLADA files. This one is optional. Note that this is not the current version!
* '''Link''': http://sourceforge.net/project/showfiles.php?group_id=157838
* '''Download''': Collada DOM > colladadom.zip
* '''Target directory''': C:\colladadom
* iconv 1.9.2
* The COLLADA plugin apparently needs this character encoding converter library. You don't need this unless you intend to install the COLLADA plugin.
* '''Link''': http://gnuwin32.sourceforge.net/packages/libiconv.htm
* '''Download''': Complete package, except sources
* '''Target directory''': C:\libiconv
== Setting up the COLLADA DOM (optional step) ==
(See also http://collada.org/mediawiki/index.php/DOM_guide:_Setting_up)
Launch MSYS. (You should have it in your start menu.)
Install fmt.exe:
{{{
bunzip2 coreutils-5.97-MSYS-1.0.11-snapshot.tar.bz2
tar xf coreutils-5.97-MSYS-1.0.11-snapshot.tar coreutils-5.97/bin/fmt.exe
mv coreutils-5.97/bin/fmt.exe bin
}}}
Go to the COLLADA DOM directory and run make:
{{{
cd /c/colladadom/dom
mingw32-make
}}}
== Setting up OpenSceneGraph ==
Launch cmake-gui(beta). (You should have it in your start menu.)
Set both source code path and build path to C:\!OpenSceneGraph:
[[Image(cmakepath.gif)]]
Press "Configure". When prompted for the generator, choose "MinGW Makefiles". After the configuration has finished, there should be a list of variables on red background. Keep everything as is except the following:
* '''BUILD_OSG_APPLICATIONS''': These are utilities around OpenSceneGraph. You don't always need them but you may at some point so keep the box checked.
* '''BUILD_OSG_EXAMPLES''': If you want to compile the examples, check this box. I'll leave it unchecked.
* '''BUILD_REF_DOCS''': If you installed doxygen, check this box.
* '''CMAKE_INSTALL_PREFIX''': Set to C:\!OpenSceneGraph
* '''COLLADA_INCLUDE_DIR''': If you installed the COLLADA DOM, set this to C:\colladadom\dom\include
* '''COLLADA_LIBRARY''': If you installed the COLLADA DOM, set this to C:\colladadom\dom\build\mingw-1.4\libcollada14dom21.dll
Press "Configure" once more. There will be new variables on red background:
* '''BUILD_REF_DOCS_SEARCHENGINE''': If you have a web server with PHP installed, you can check this box to enable search.
* '''BUILD_REF_DOCS_TAGFILE''': You probably won't need this for now. Leave unchecked.
* '''COLLADA_USE_STATIC''': Leave unchecked.
Press "Configure" even once more. There should be no more variables on red background and the "Generate" button should be activated. Hit this "Generate" button (ignore the developer warning). When the generator is done, close the CMake GUI application.
Open a DOS command shell, go to the OpenSceneGraph directory, and run make (twice):
{{{
cd c:\OpenSceneGraph
mingw32-make
mingw32-make install
}}}
This may take a while. When it's done, the OpenSceneGraph sources will be compiled. Now let's generate the documentation:
{{{
cd c:\OpenSceneGraph\doc
doxygen -u
doxygen
}}}
You may see messages such as "Problems running dot". That's because you don't have !GraphViz installed which is used by doxygen to generate the class hierarchy images. Unless you insist on these graphs, you can simply ignore those messages. (Note also that doxygen doesn't seem to be able to handle Windows directory names which contain spaces. If you're using such directories, you may have to edit the Doxyfile and replace those directory names with their DOS counterpart such as "SETTING~1".) Your documentation is now here:
{{{
c:\OpenSceneGraph\doc\OpenSceneGraphReferenceDocs\index.html
}}}
== Creating a new project in Eclipse which uses OpenSceneGraph ==
Run Eclipse. Select File > New > C++ Project. Enter a project name. Select Executable > Hello World C++ Project. Hit Finish.
[[Image(cppproject.gif)]]
Select Project > Properties. Select C/C++ General > Paths and symbols. The "Include" tab should be selected. Click on "Add", then on "File system..." and select the C:\OpenSceneGraph\include directory. Check "Add to all configurations" and "Add to all languages".
[[Image(include.gif)]]
The OpenSceneGraph include files will now be found but the linker will not find the libraries you compiled. So, in the same fashion, add C:\OpenSceneGraph\lib in the "Library paths" tab. In the tree view on the left, select C/C++ Build > Settings. In the "Tool settings" tab, scroll down to MinGW C++ Linker > Libraries and select it. In the "Libraries (-l)" window, click on the "+" icon for each library you need. For example, for the "Basic Geometry" tutorial (http://www.openscenegraph.org/projects/osg/wiki/Support/Tutorials/BasicGeometry), you'll need "libosg" and "libosgViewer".
[[Image(libraries.gif)]]
Now you should be able to completely build your project. Try to build and run it by clicking on the "run" button. You'll notice, however, that nothing will happen. That's because the dynamic link libraries cannot be found. Select Run > Open Run Dialog... Make sure your application is selected (it was created when you tried to run it for the first time). Select the "Environment" tab. Click on "Select..." and select the "Path" variable. Hit "Ok".
[[Image(path.gif)]]
Select the newly added "Path" variable and click on "Edit...". In the variable field, append ";C:\OpenSceneGraph\lib" (without the quotes). If you're using the COLLADA plugin, also append ";C:\colladadom\dom\build\mingw-1.4". Your project should now run properly.
Well done. If something didn't work out for you, please figure it out and post the corrections and notes here.
'''Small rant''': Unfortunately, days went into figuring out all these steps. The main problem was getting COLLADA to compile into OSG. The old COLLADA version 1.4 is virtually impossible to compile using MinGW on Windows. At the time of writing, the newer versions 2.x weren't supported in the official OSG release (2.4.0), only in the developer release 2.5.0. But even there, the documentation also wasn't updated. In general, OSG could use a thorough installation document where every option is explained and all the requirements are listed.