History: Setting Up An Application - Autotools - Linux

            {DIV(class="Layout_box6")}{SPLIT(colsize=15%|85%)}{img fileId="1981"}---
{DIV(class="bigBold")}Setting Up An Application using GNU Autotools - Linux{DIV}{SPLIT}
{DIV}
{DIV(class="Bloody_box1")}__IMPORTANT:__ These instructions are very old and only work with old releases of Ogre.

For recent versions of Ogre, please follow the ((Building Your Projects With CMake|CMake instructions)).{DIV}
%clear%
!Introduction
This set of instructions will walk you through setting up a C++ project from scratch using GNU Autotools.

When you have finished this tutorial you will be able to compile a working Ogre Application and you will be ready to start the ((Basic Tutorials)).

{maketoc}

!Prerequisites
You should have a working build environment set up ({MONO()}apt-get install build-essentials on Ubuntu{MONO})
Make sure that {MONO()}autoconf{MONO} + {MONO()}automake{MONO} + {MONO()}libtool{MONO} are installed.

!Ogre Wiki Tutorial Framework
Download the ((Ogre Wiki Tutorial Framework))

And uncompress it into an empty directory. In the following sections, it is assumed that you are executing the instructions from within that directory.

!bootstrap
{CODE(wrap="1", colors="bash")}#!/bin/sh
 rm -rf autom4te.cache
 libtoolize --force --copy &&  aclocal &&  autoheader &&  automake --add-missing --force-missing --copy --foreign &&  autoconf{CODE}
Make this file (bootstrap) executable.


!configure.ac
{CODE(wrap="1", colors="make")}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.9, OGRE-Overlay >= 1.9])
 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)
 AC_OUTPUT{CODE}

!Makefile.am
{CODE(wrap="1", colors="make")}
noinst_HEADERS= BaseApplication.h TutorialApplication.h

bin_PROGRAMS= OgreApp
 OgreApp_CPPFLAGS= -I$(top_srcdir)
 OgreApp_SOURCES= BaseApplication.cpp TutorialApplication.cpp
 OgreApp_CXXFLAGS= $(OGRE_CFLAGS) $(OIS_CFLAGS)
 OgreApp_LDADD= $(OGRE_LIBS) $(OIS_LIBS)

 EXTRA_DIST = bootstrap
 AUTOMAKE_OPTIONS = foreign{CODE}

!The Autotools Dance
Run this in a console:
{CODE(wrap="1", colors="bash")}./bootstrap && ./configure && make{CODE}

You should have successfully built your Ogre application. :)


!Adding more OGRE libraries
Through out the tutorials you will have to add optional components to the configure.ac file like the OGRE Terrain component in ((Basic Tutorial 3|#http://www.ogre3d.org/tikiwiki/tiki-index.php?page_ref_id=258|Basic Tutorial 3)).

To do this you have first to discover the OGRE libraries available to you. To get that list execute the following command:

{CODE(wrap="1",colors="bash")}pkg-config --list-all | grep OGRE{CODE}

With OGRE 1.7.1 the following list should be displayed:

{CODE(wrap="1",colors="bash")}OGRE-Paging                   OGRE-Paging - General purpose paging component for OGRE
OGRE-PCZ                      OGRE-PCZ - Portal-Connected Zone Scene Manager for OGRE
OGRE-RTShaderSystem           OGRE-RTShaderSystem - Real time shader generation component for OGRE
OGRE                          OGRE - Object-Oriented Graphics Rendering Engine
OGRE-Property                 OGRE-Property - General purpose property component for OGRE
OGRE-Terrain                  OGRE-Terrain - Outdoor terrain component for OGRE{CODE}

To see the options available to you with pkg-config, run:

{CODE(wrap="1",colors="bash")}pkg-config --help{CODE}

An option of interest is {MONO()}--modversion{MONO} which allow to display the version of the package provided as parameter of the command.

To add the required package to your configure.ac, insert the package name followed by >= and the minimum version of that lib required by your application in the second parameter of PKG_CHECK_MODULES after the text {MONO()}OGRE >= 1.2{MONO} between the brackets.

With OGRE-Terrain the code for PKG_CHECK_MODULES will became:

{CODE(wrap="1",colors="make")}PKG_CHECK_MODULES(OGRE, [OGRE >= 1.2 OGRE-Terrain >= 1.7.1]){CODE}

The file Makefile.am doesn't need to be modified.

Alternatively, instead of concatenating all the OGRE related libraries into one call to PKG_CHECK_MODULES, you can create one instance of PKG_CHECK_MODULES for each library to include in the build process. Like it is done for OGRE and OIS in the configure.ac above.

Below is an example with OGRE-Terrain:

{CODE(wrap="1", colors="make")}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(OGRE_TERRAIN, [OGRE-Terrain >= 1.2])
 AC_SUBST(OGRE_TERRAIN_CFLAGS)
 AC_SUBST(OGRE_TERRAIN_LIBS)
 
 PKG_CHECK_MODULES(OIS, [OIS >= 1.0])
 AC_SUBST(OIS_CFLAGS)
 AC_SUBST(OIS_LIBS)
 
 AC_CONFIG_FILES(Makefile)
 AC_OUTPUT{CODE}

In that case, you need to modify the Makefile.am accordingly. With the configure.ac above, the corresponding Makefile.am is:

{CODE(wrap="1", colors="make")}
noinst_HEADERS= BaseApplication.h TutorialApplication.h

bin_PROGRAMS= OgreApp
 OgreApp_CPPFLAGS= -I$(top_srcdir)
 OgreApp_SOURCES= BaseApplication.cpp TutorialApplication.cpp
 OgreApp_CXXFLAGS= $(OGRE_CFLAGS) $(OGRE_TERRAIN_CFLAGS) $(OIS_CFLAGS)
 OgreApp_LDADD= $(OGRE_LIBS) $(OGRE_TERRAIN_LIBS) $(OIS_LIBS)

 EXTRA_DIST = bootstrap
 AUTOMAKE_OPTIONS = foreign{CODE}

!Possible Improvements
Make a new build target which either copies the executable to a '''dist''' directory - see ((dflkjf)) - or a target which copies the Ogre configuration files (plugins.cfg and resources.cfg) from /usr/local/share/OGRE.

Another improvement would be to search the source code into a subdirectory called {MONO()}src/{MONO} and instruct the user to put the Tutorial Framework sources in that location.