Setting Up An Application - Linux - Shoggoth        
Page actions
Print

%prevogre%

Autotools

To build your application using the ubiquitous GNU autotools (autoconf + automake + libtool), create these files in your project folder with the following content:

bootstrap
: 

#!/bin/sh
 rm -rf autom4te.cache
 libtoolize --force --copy &&  aclocal &&  autoheader &&  automake --add-missing --force-missing --copy --foreign &&  autoconf
configure.ac
: 



AC_INIT(configure.ac)
 AM_INIT_AUTOMAKE(SampleApp, 0.1)
 AM_CONFIG_HEADER(config.h)
 
 AC_LANG_CPLUSPLUS
 AC_PROG_CXX
 AM_PROG_LIBTOOL
 
 PKG_CHECK_MODULES(OGRE, [OGRE >= 1.2])
 AC_SUBST(OGRE_CFLAGS)
 AC_SUBST(OGRE_LIBS)
 
 PKG_CHECK_MODULES(OIS, [OIS >= 1.0])
 AC_SUBST(OIS_CFLAGS)
 AC_SUBST(OIS_LIBS)
 
 AC_CONFIG_FILES(Makefile include/Makefile src/Makefile)
 AC_OUTPUT
Makefile.am
: 



SUBDIRS = include src
 EXTRA_DIST = bootstrap
 AUTOMAKE_OPTIONS = foreign
include/Makefile.am
: 



noinst_HEADERS= SampleApp.h
src/Makefile.am
: 



bin_PROGRAMS= SampleApp
 SampleApp_CPPFLAGS= -I$(top_srcdir)/include
 SampleApp_SOURCES= SampleApp.cpp
 SampleApp_CXXFLAGS= $(OGRE_CFLAGS) $(OIS_CFLAGS)
 SampleApp_LDADD= $(OGRE_LIBS) $(OIS_LIBS)

Your First Application or Minimal Application to create include/SampleApp.h and src/SampleApp.cpp.

You probably want to add plugins.cfg and resources.cfg to the executable folder (src) (see Prerequisites).

To build your app run ./bootstrap && ./configure && make. Subsequent builds only need running make.

To execute your app go to the src folder and run ./SampleApp.

Scons

Scons is a multiplatform building tool programmed in Python, designed to replace GNU Make and other similar tools (autoconf, automake, etc).

For compiling using scons, you'll only need to type: 

scons

in your command line. The scons building tool will automatically check for all needed libraries and include files in your system before trying to compile.

For using scons, you'll need to create a SConstruct file. You'll had to pay a visit to scons.org to learn the directives for building with that tool. But here we provide a sample SConstruct file, that will build both in Ubuntu Linux and in Windows (using Visual Studio 2003 at least).

For a simple program composed by a file named main.cpp, using Ogre Eihort and OIS, this would be the SConstruct file needed: 

platform = ARGUMENTS.get('OS', Platform())
 mode = ARGUMENTS.get('mode', "release")
 
 if platform.name == "linux":
    listinc=[
       # our main include directory
       'include',
 
       # location of ogre includes
       '/usr/local/include/OGRE',
       # location of ois includes
       '/usr/local/include/OIS',
       ]
 else:
    listinc=[
       # our main include directory
       'include',
 
       # location of ogre includes
       'E:/ogre-eihort/ogrenew/OgreMain/include',
       # location of ois includes
       'E:/ogre-eihort/ogrenew/Dependencies/include/OIS',
       ]
 
 if platform.name == "linux":
    debugcflags=['-g']
    releasecflags=[]
 
    if mode=="debug":
       env=Environment(CPPPATH=listinc, LIBPATH='.', CCFLAGS = debugcflags)
    else:
       env=Environment(CPPPATH=listinc, LIBPATH='.', CCFLAGS = releasecflags)
 else:
    debugcflags = ['-W1', '-GX', '-EHsc', '-D_DEBUG', '/MDd', '/Zi']   #extra compile flags for debug
    releasecflags = ['-O2', '-EHsc', '-DNDEBUG', '/MD']         #extra compile flags for release
 
    if mode=="debug":
       env=Environment(CPPPATH=listinc, LIBPATH='bin/windows/debug'
           , CCFLAGS = debugcflags, CPPDEFINES=["WIN32", "_DEBUG", "_WINDOWS"], LINKFLAGS='/DEBUG'
            )
    else:
       env=Environment(CPPPATH=listinc, LIBPATH='bin/windows/release'
           , CCFLAGS = releasecflags, CPPDEFINES=["WIN32", "NDEBUG", "_WINDOWS"]
            )
 
 
 # check for required include files and libraries
 conf = Configure(env)
 if not conf.CheckCXXHeader('Ogre.h'):
    print 'Ogre must be installed!'
    Exit(1)
 if not conf.CheckCXXHeader('OISPrereqs.h'):
    print 'OIS must be installed!'
    Exit(1)
 if platform.name == "linux":
    if not conf.CheckLib('OgreMain'):
       print 'OgreMain library must be in path'
       Exit(1)
    if not conf.CheckLib('OIS'):
       print 'OIS library must be in path'
       Exit(1)
 
 
 # list of files needed for compiling the program
 main_program_list=Split("""
    src/main.cpp
    """)
 
 
 
 if platform.name == "linux":
    # list of libraries needed for linking
    libs_list=Split("""
       OgreMain
       OIS
       """)
 else:
    # list of libraries needed for release
    libs_release_list=Split("""
       c:/ogre-eihort/ogrenew/OgreMain/lib/Release/OgreMain
       c:/ogre-eihort/ogrenew/Dependencies/lib/Release/OIS
       kernel32.lib
       user32.lib
       gdi32.lib
       winspool.lib
       comdlg32.lib
       advapi32.lib
       shell32.lib
       ole32.lib
       oleaut32.lib
       uuid.lib
       odbc32.lib
       odbccp32.lib
       """)
    # list of libraries needed for debug
    libs_debug_list=Split("""
       c:/ogre-eihort/ogrenew/OgreMain/lib/Debug/OgreMain_d
       c:/ogre-eihort/ogrenew/Dependencies/lib/Debug/OIS_d
       kernel32.lib
       user32.lib
       gdi32.lib
       winspool.lib
       comdlg32.lib
       advapi32.lib
       shell32.lib
       ole32.lib
       oleaut32.lib
       uuid.lib
       odbc32.lib
       odbccp32.lib
       """)
 
 
 if platform.name == "linux":
    if mode=="debug":
       env.Program('bin/linux/debug/main_d', main_program_list, LIBS=libs_list, LIBPATH='.')
    else:
       env.Program('bin/linux/release/main', main_program_list, LIBS=libs_list, LIBPATH='.')
 else:
    if mode=="debug":
       env.Program('bin/windows/debug/main_d', main_program_list, LIBS=libs_debug_list, LIBPATH='.')
    else:
       env.Program('bin/windows/release/main', main_program_list, LIBS=libs_release_list, LIBPATH='.')

You might need to change the file paths in the file though.

Use:

  • Put your main.cpp file in directory src; create the following empty directories: 

include
 bin/windows/debug
 bin/windows/release
 bin/linux/debug
 bin/linux/release
  • In linux, write any of the following lines in the command line: 



scons OS=linux mode=debug # build in debug mode
 scons OS=linux # build in release mode
 scons OS=linux mode=debug -c # clean in debug mode
 scons OS=linux -c # clean in release mode

In windows, use the following lines:

  • For debug build: 

scons MSTOOLKIT=yes OS=windows mode=debug
  • For release build: 



scons MSTOOLKIT=yes OS=windows
  • For debug clean: 



scons MSTOOLKIT=yes OS=windows mode=debug -c
  • For release clean: 



scons MSTOOLKIT=yes OS=windows -c

Alternate Scons File



Please actually read this file, it's easy to understand and will require some modification for use. 

# A Linux Ogre/CEGUI/OIS/OgreOde build Script by [[User:Grey|Grey]], with many thanks to keir from #scons on freenode.
 
 # Setup our Build Environment, Smarter scripts might be able to change this at the command line,
 env = Environment(
    CCFLAGS='-ggdb -pg -g3 -DEXT_HASH',
    LDFLAGS='-pg'
 )
 
 # Our External Libs
 # Got some fugly stuff ( || true ) in there to supress unreadable crashes, it
 # ends up using the nicer formatted error messages below 
 env.ParseConfig('pkg-config --silence-errors --libs --cflags OGRE || true')
 env.ParseConfig('pkg-config --silence-errors --libs --cflags OIS || true')
 env.ParseConfig('pkg-config --silence-errors --libs --cflags CEGUI-OGRE || true')
 env.ParseConfig('pkg-config --silence-errors --libs --cflags OgreOde_Core || true')
 
 # Get out current config so we can verify we have everything we need.
 # There is an autoadd method here, but then we'd have to specify full paths for 
 # the libs and headers, which is lame.
 config = Configure(env);
 
 # Everyone needs OIS :)
 if not config.CheckLibWithHeader('OIS', 'OISPrereqs.h', 'C++'):
  print 'OIS must be installed!'
  Exit(1)
 
 # this should work to get Ogre included
 if not config.CheckLibWithHeader( 'OgreMain', 'Ogre.h', 'C++' ):
  print "Ogre Must be installed!"
  Exit(1)
 
 # Any other component libraries you use can be added and tested in this manner
 if not config.CheckLibWithHeader( 'OgreOde_Core', 'OgreOde_Core.h', 'C++'):
  print 'OgreOde must be installed!'
  Exit(1);
 
 # Substitute with your GUI of choice
 if not config.CheckLibWithHeader('CEGUIBase', 'CEGUI.h', 'C++'):
  print "You need CEGUI to compile this program"
  Exit(1);
 
 if not config.CheckLibWithHeader('CEGUIOgreRenderer', 'OgreCEGUIRenderer.h', 'C++'):
  print "You need OGRE-CEGUI to compile this program"
  Exit(1);
 
 # Validate the configuration and assign it to our env
 env = config.Finish(); 
 
 # Build our main program
 env.Program(
    target = 'main',
    # Replace these with your source files of course
    source = [
        'main.cpp', 'GUISystem.cpp', 'EventQueue.cpp', 'InputManager.cpp',
        'CommandListener.cpp', 'CameraController.cpp', 'KeyMap.cpp',
        'OdeManager.cpp', 'PhysModel.cpp', 'ODECharacterController.cpp', 'RayCharacterController.cpp',
        'ChaseCameraController.cpp'])

Eclipse



See the Eclipse setup pages for Ogre IDE Eclipse.

Anjuta IDE

A complete working project and sample can be found here: http://waxor.com/page/ogre-dome.tgz

  1. Create a new Generic/Terminal App project.
  2. Choose c++ and Executable target when prompted.
  3. Delete all of the included template code in main.cc. It will be replaced with the sample code below.
  4. Go to the Settings Menu and choose Compilier and Linker Settings.
  5. Open the following tabs and add each entry one line at a time: replace $OGRE_HOME/ with the full path to the ogrenew folder you compiled from. Also note you may have Ogre in /usr/local/include and /usr/local/lib depending on how you installed it.

Include Paths

$OGRE_HOME/Samples/Common/include
         /usr/include/OGRE               (Not necessary if you include like this '#include <OGRE/Ogre.h>')
         /usr/include/CEGUI
         /usr/include/OIS
Library paths



/usr/local/lib
Libraries



OgreMain
         CEGUIBase
         CEGUIOgreRenderer
         OIS
Options 



check "Enable Debugging" (adds -g to the command line)
Options | Compilier flags (CFLAGS)



-DEXT_HASH

KDevelop IDE



KDevelop is a nice flexible IDE for Linux, and it is easy to set up with OGRE.

  • Create a new C++ "Simple Hello world program" project.

  • Open "configure.in" and add the following line above the AC_OUTPUT statement. 

PKG_CHECK_MODULES(OGRE, [OGRE >= 1.2.0])
  • Open "src/Makefile.am" and add the following lines. 



LDADD = @OGRE_LIBS@
 AM_CXXFLAGS = @OGRE_CFLAGS@
  • To avoid linker errors, add these lines to src/Makefile.am 



sampleapp_LDADD = /usr/local/lib/libOIS.so  /usr/local/lib/libOgreMain.so
  • You may need to change /usr/local/lib/ to the location of your OGRE/OIS libs. Also, you if you get errors about missing libs later, you will have to link/copy them to /lib or /lib64.



  • You may wish to have the program run in the sample apps directory when debuging so you do not have to copy all the runtime resource files over. To do this go into project options (top menu) then click run options, then select the custom directory option and put in "<insert ogre root dir here>/Samples/Common/bin/"

  • If you choose to derive your application from the ExampleApplication class that comes with OGRE, open the automake manager, right click on your target, choose "Add Existing Files..." and add the files ExampleFrameListener.h and ExampleApplication.h from ogrenew/Samples/Common/include.

  • You also need to tell KDevelop where to find the OGRE specific headers. Click on Project->Project Settings->Configure Options, click on the C++ tab and add the following line to "Compiler flags (CXXFLAGS)" :


-I <insert ogre root dir here>OgreMain/include -I <insert ogre root dir here>OgreMain/include/GLX

  • Insert the SampleApp code below for the application, build and run the project.

  • To use the debugger, open the projects options, choose the debugger tab and select "Enable separate terminal for application IO".

Cross compiling Win32 applications in Linux


Cross Compiling OGRE on Linux
Cross-Compiling OGRE on Debian

See also: How to compile applications for MS Windows platform from within Linux

Getting Help

Probably the top two problems people have with Ogre are not being able to compile or a missing dependency. For the first, you are going to need to learn how to use your compiler. If you barely know C++ then expect a challenge, but don't give up! Thousands of people have successfully gotten Ogre to work with both the GCC and MSVC compilers, so look in the wiki and forums for what they have done that you haven't. For missing dependencies, these are libraries that aren't installed, that aren't linked against your program, or that aren't in your runtime path. Other dependencies are incorrect rendering plugins in your plugins.cfg file or incorrect paths in your resources.cfg file, or missing one of the files all together.

If you have problems reread this page as well as Installing An SDK - Shoggoth and Building From Source - Shoggoth and look in the Ogre.log file. You may also find your problem answered in the Build FAQ. If you need further help, search the forums. It is likely your problem has happened to others many times. If this is a new issue, read the forum rules then ask away. Make sure to provide relevant details from your Ogre.log, exceptions, error messages, and/or debugger back traces. Be specific and people will be more able to help you.

Your First Application

Now we will create a basic source file for starting an OGRE application. This program, like the included samples, uses the example framework.

Copy the following code and include it as a new file in your project settings. Following our conventions, you'd put it in work_dir/src and name it SampleApp.cpp. Since this is dependent upon ExampleApplication.h and ExampleFrameListener.h make sure these files are accessible by your project. Our convention would have you put them in work_dir/include. You can copy them from the Samples directory. 

#include "ExampleApplication.h"
 
 ''// Declare a subclass of the ExampleFrameListener class''
 '''class''' MyListener : '''public''' ExampleFrameListener
 {
 '''public''':
     MyListener(RenderWindow* win, Camera* cam) : ExampleFrameListener(win, cam)
     {
     }
 
     '''bool''' frameStarted('''const''' FrameEvent& evt)
     {
         '''return''' ExampleFrameListener::frameStarted(evt);        
     }
 
     '''bool''' frameEnded(const FrameEvent& evt)
     {
         '''return''' ExampleFrameListener::frameEnded(evt);        
     }
 };
 
 ''// Declare a subclass of the ExampleApplication class''
 '''class''' SampleApp : '''public''' ExampleApplication 
 {
 '''public''':
    SampleApp() 
    {
    }
 
 '''protected''':
    ''// Define what is in the scene
    '''void''' createScene('''void''')
    {
        // put your scene creation in here
    }
   
    ''// Create new frame listener''
    '''void''' createFrameListener('''void''')
    {
        mFrameListener = '''new''' MyListener(mWindow, mCamera);
        mRoot->addFrameListener(mFrameListener);
    }
 };
 
 #ifdef __cplusplus
 extern "C" {
 #endif
 
 #if OGRE_PLATFORM == OGRE_PLATFORM_WIN32 
 #define WIN32_LEAN_AND_MEAN 
 #include "windows.h" 
 '''INT''' WINAPI WinMain(HINSTANCE hInst, HINSTANCE, LPSTR strCmdLine, '''INT''') 
 #else 
 '''int''' main('''int''' argc, '''char''' **argv) 
 #endif 
 {
     ''// Instantiate our subclass''
     SampleApp myApp;
 
     '''try''' {
         ''// ExampleApplication provides a go method, which starts the rendering.''
         myApp.go();
     }
     '''catch''' (Ogre::Exception& e) {
 #if OGRE_PLATFORM == OGRE_PLATFORM_WIN32 
         MessageBoxA(NULL, e.getFullDescription().c_str(), "An exception has occured!", MB_OK | MB_ICONERROR | MB_TASKMODAL);
 #else
         std::cerr << "Exception:\n";
         std::cerr << e.getFullDescription().c_str() << "\n";
 #endif
         '''return''' 1;
     }
 
 '''return''' 0;
 }
 
 #ifdef __cplusplus
 }
 #endif

Compile this code now. However before running the program, make sure you have a plugins.cfg and a resources.cfg in the same directory as the executable. Review the Prerequisites section for the purpose of these files. Edit them and make sure the paths are correct. Otherwise your OGRE setup dialog box may not have any rendering libraries in it, or you may recieve an error on your screen or in Ogre.log that looks something like this: 

Description: ../../Media/packs/OgreCore.zip - error whilst opening archive: Unable to read zip file

When the program starts it will display the OGRE setup dialog and start the application with a blank, black screen containing little more than the OGRE logo and an FPS (frame per second) display. We haven't added anything to this scene yet, as evidenced by the empty createScene method. Press ESC to quit the application.

If you didn't get this, something is not right in your setup. See the Prerequisites and the Getting Help sections to review your installation.

The ExampleApplication framework will boot the OGRE system, displaying a configuration dialog, create a window, setup a camera and respond to the standard mouselook & WSAD controls. All you have to do is to fill in the 'createScene' implementation. If you want to do more advanced things like adding extra controls, choosing a different scene manager, setting up different resource locations, etc, you will need to override more methods of ExampleApplication and maybe introduce a subclass of ExampleFrameListener.

As mentioned before, you don't have to use the ExampleApplication and ExampleFrameListener base classes. Use them to work through the tutorials and to test things out. For larger projects you'll want to write your own framework, or use one of the frameworks or engines available on Projects using OGRE.

Note for American readers
:


Sinbad the lead developer and creator of OGRE, is British. Naturally he uses British spellings such as "Colour", "Initialise" and "Normalise". Watch out for these spellings in the API.

See below to learn about your resources for getting help. Then your next step is to work through the Ogre Tutorials.

History Source