Setting Up An Application using GNU Autotools - Linux

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.

Prerequisites

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

Ogre Wiki Tutorial Framework

Download the Ogre Wiki Tutorial Framework here:
 TutorialFramework.tar.bz2

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

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

Make this file (bootstrap) executable.

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)
 AC_OUTPUT

Makefile.am

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

The Autotools Dance

Run this in a console:

./bootstrap && ./configure && make

 
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.

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

pkg-config --list-all | grep OGRE

 
With OGRE 1.7.1 the following list should be displayed:

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

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

pkg-config --help

 
An option of interest is --modversion 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 OGRE >= 1.2 between the brackets.

With OGRE-Terrain the code for PKG_CHECK_MODULES will became:

PKG_CHECK_MODULES(OGRE, [OGRE >= 1.2 OGRE-Terrain >= 1.7.1])

 
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:

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

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

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

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 src/ and instruct the user to put the Tutorial Framework sources in that location.