History: Setting Up An Application - Windows

Microsoft Visual C++ 2008

Important:

Make sure you have the current patchs and service packs for Visual Studio 2008.

Note: You can use the Ogre Application Wizard to set up a Visual Studio project. The project can be empty or include the files used by the Starting Tutorials.
These instructions cover how to manually set up a new application from scratch and only make the assumption that the Ogre SDK has been installed on your system. This means you downloaded the Ogre SDK or built and installed the Ogre SDK from source. It is possible to build the Ogre SDK from source and not go through the process of installation but the location of files will be different. There should be enough information in this article to figure out how to configure your project from that intermediate build point.

The steps involved are:

1. Create a new project: File | New | Project
2. Under project types 'Visual C++' then under Templates select 'Win32 Project'.
3. Enter a name for your project. I suggest OgreTemplate so that it's purpose is obvious. These files can be be copied over to a new directory when creating a new Ogre project thus avoiding this long process. Change the location to point to a work directory. It should not be in either the SDK directory or in the source files for Ogre.
   

1. Click the OK button and the Win32 Application Wizard will be displayed.
   

1. Press the Next Button.
   
2. Select 'Windows Application' and 'Empty project' when prompted for the type of project to create.
   

Press the Finish button
At this point, some of the steps become less intuitive. Good organization dictates that we at least keep our header (.h) files separate from our source(.cpp) files. There are several ways to create sub-directories under our project directory. I will stick to doing everything in Visual Studio. At this point, the Solution Explorer window should be displayed, probably docked on the left side of the Visual Studio Window. If it is not, select the menu View | Solution Explorer.

1. If you hover over the second button in the Solution Explorer's toolbar, you will see that it says "Show all files" It should not currently be toggled so you should click on it to toggle it. Now you will see this display of Solution Explorer.

1. Select the menu Project | New Folder and type "source" in the editable area that is displayed in the Solution Explorer. This will create a sub-directory under the project directory called "source".
2. Click on the project OgreTemplate in the Solution Explorer window. This will ensure that the next sub-directory gets created under the project directory and not under the source directory you just created. Select the menu Project | New Folder and type "include" in the editable area that is displayed in the Solution Explorer. This will create a sub-directory under the project directory called "include".
3. Again, click on the project OgreTemplate in the Solution Explorer window. Select the menu Project | New Folder and type "scripts" in the editable area that is displayed in the Solution Explorer. This will create a sub-directory under the project directory called "scripts".

1. Create a new source file by selecting 'Project -> Add New Item...'. Make sure the file is in the work directory. This step must be performed before editing project properties (otherwise the 'C/C++' page will be unavailable).
2. Save the project.

If you named your project "Testproject" and selected a location like C:\Work, and checked the box called "Create directory for solution", with a solution name of "Testsolution", then the directory structure will be: C:\Work\Testsolution\Testproject. If you do not create a directory for the solution, the structure will simply be: C:\Work\Testproject.

To clarify where the DLL files should be, an easy way is to copy the \bin folder (containing \debug and \release) and the \media folder from the OGRE installation directory to your Testproject folder (note: in this case you might be copying DLLs that won't be needed, but it's the hassle-free way). If you follow the convention presented above and you created folders for the header, scripts and source files, you have the following folders under \Testproject (excluding subfolders): 'bin', 'include', 'media', 'testsolution', 'scripts', and 'src'. However, if you don't want to copy them while running your Testproject from Visual Studio just add the path to OGRE's DLL files to the %PATH% global environment variable like this:

Debugging : Environment                             = PATH=%PATH%;%OGRE_HOME%\bin\debug

and for the release version

Debugging : Environment                             = PATH=%PATH%;%OGRE_HOME%\bin\release

This will not modify the %PATH% environment variable permanently, just for the given run, so its safer. You could modify it globally for all windows applications like this:

My Computer -> Properties -> Advanced -> Environment Variables -> System Variables -> Path    += ;%OGRE_HOME%\bin\debug

or

My Computer -> Properties -> Advanced -> Environment Variables -> System Variables -> Path    += ;%OGRE_HOME%\bin\release

but this could lead to confusion if working with different Ogre versions and is not recommended.

If you follow the next few steps carefully, your project should compile without errors.

Configure your project with the following settings. All of these are for the Debug configuration. To set up the Release configuration just change the directories from '\Debug\' to '\Release\'. Select "project properties" and under "configuration properties" add the following:

Debugging : Command                                 = $(OutDir)\$(ProjectName).exe
 Debugging : Working Directory                       = $(OutDir)
 C/C++ : Preprocessor : Preprocessor Definitions += _STLP_DEBUG (only in Debug mode, not needed for .Net 2003 and 2005)
 C/C++ : Code Generation : Use runtime library      = Multithreaded Debug DLL (Multithreaded DLL in Release)
 Linker : General : Output File                            = ..\bin\Debug\[appname].exe
 Linker : Input : Additional Dependencies                += OgreMain_d.lib OIS_d.lib  (OgreMain.lib OIS.lib in Release)

If you also use CEGUI, you need to tell Visual Studio to link the libs by doing this:

Linker : Input : Additional Dependencies                += CEGUIBase_d.lib OgreGUIRenderer_d.lib  (CEGUIBase.lib OgreGUIRenderer.lib in Release)

And, for those using the SDK:

C/C++ : General : Additional Include Directories      = ..\include;$(OGRE_HOME)\include;$(OGRE_HOME)\samples\include
 Linker : General : Additional Library Directories         = $(OGRE_HOME)\lib

Or, for those using the source release:

C/C++ : General : Additional Include Directories      = ..\include;$(OGRE_SRC)\OgreMain\include;$(OGRE_SRC)\Samples\Common\Include
 Linker : General : Additional Library Directories         = $(OGRE_SRC)\OgreMain\Lib\Debug

Visual Studio Debugging Settings - Shoggoth

Code::Blocks & MinGW 3.4.5 & STLPort 5.0

Have a look at the build options for Demo_CameraTrack, most of the demos use the same build options.

Note: with MinGW gcc 3.4.5 you can link directly against dll's built by gcc 3.4.5 and do not require an import lib. This is the same setup on Linux where you link directly to the shared object (.so). This is why the SDK does not come with import libs for Ogre. You don't need them.

Build options that you should use:

Normally you will have two targets: Debug and Release.

To create a new target:

1. Right click on the project in the Management window and select Properties in the popup and this will open up the properties window for your project.
2. Select the Target tab.
3. Select Add to define a new target.
4. Type in the target name ie Debug.
5. Select OK.

Select Build Options to modify build options for a target.

Project build options

will be used for both Debug and Release target build options:

ensure Selected compiler is: GNU GCC Compiler

• Compiler
  • Other options
    • -mthreads
    • -fmessage-length=0
    • -fexceptions
    • -fident
  • '#defines'
    • _STLP_NO_CUSTOM_IO

If your app does not define any custom IO templates then this define will speed up compiles.

• _STLP_USE_DYNAMIC_LIB

this ensures that the DLL version of STLPort is used.

• Linker
  • Other linker options:
    • -Wl,--enable-auto-image-base
    • -Wl,--add-stdcall-alias
• Directories
  • Compiler
    • $(OGRE_HOME)\stlport\stlport

VERY IMPORTANT: The stlport include directory has to be first in the include directories. If it is not then headers used for libstdc++ could get included which will cause conflicts with stlport during the link stage. You will most likely get undefined reference error messages with member methods saying they require std::string (method parameters). You should never see std:: in an error message and if you do then it means that the STLPort headers were not found and libstdc++ headers were used instead. If you do end up in this scenerio, after you correct the directory problem you must do a rebuild so that everything gets recompiled with the proper headers. Selecting build won't do it since CB will just attempt to do the link stage again since it doesn't detect any changes in the source and will fail again.

• $(OGRE_HOME)\include
• Your project include directories
• Linker
  • $(OGRE_HOME)\bin\$(TARGET_NAME)

Code::Blocks

Debug build target options:

ensure Selected compiler is: GNU GCC Compiler
set Policy to 'Append target options to project options'

• Compiler
  • '#defines'
    • WIN32
    • _DEBUG
    • _WINDOWS
    • _STLP_DEBUG

this tells STLPort to use the special debug build version of the dll

• Linker
  • Link libraries:
    • Your project dll's or static libs (.a)
    • OgreMain_d

this is the name of the debug build of OgreMain dll.

• stlportstlg.5.0

this must be the last entry

Release build target options:

ensure Selected compiler is: GNU GCC Compiler
set Policy to 'Append target options to project options'

• Compiler
  • '#defines'
    • WIN32
    • NDEBUG
    • _WINDOWS
• Linker
  • Link libraries:
    • Your project dll's or static libs (.a)
    • OgreMain

this is the name of the release build of OgreMain dll.

• stlport.5.0

this must be the last entry

Note: OGRE_HOME is a pre-defined environment variable setup by the SDK installer. OGRE_HOME points to the directory where the SDK is installed. You can use $(OGRE_HOME) within your build options when setting up paths to specific directories with the SDK that you will need to access.

WARNING Do not mix dll and static object builds using different STL implementations. Here is an example: You build a dll using stdlibc++ but your exe is built using STLPort. Everything that is c++ must be built using STLPort. This does not apply to C static libs and dll's.