The Allegro Wiki is migrating to github at https://github.com/liballeg/allegro_wiki/wiki

Using Allegro with autoconf/KDevelop

From Allegro Wiki
Jump to: navigation, search
Merge-arrows.gif
It has been suggested that this article or section be merged with KDevelop. (Discuss)


For a more general autotoolset tutorial, see autotoolset.

HOWTO Use Allegro with autoconf

Writing Makefiles can be a pain; maintaining them doubly so. autotoolset was designed to be a way around this pain. Unfortunately, many developers have no idea how to use autotoolset.

What is autotoolset?

Almost every package on the internet that contains a configure script was made using autotoolset. Autotoolset is comprised of several other tools. In this article we will only focus on autoconf and automake. Autoconf is the utility that will generate a configure script for you, and automake will be crafting all of your Makefiles.

Notes on KDevelop

KDevelop projects are actually simply autotoolset projects managed by KDevelop. When following this article, keep in mind a few things:

  • KDevelop does not track changes to your Makefile.am. When editing these files manually, you will need to close and reopen your project afterwards to see the changes in the automake manager.
  • KDevelop does not configure in the source directory by default. The default for KDevelop is to configure with the "Build Directory" set to debug/. This will not cause any problems until you run "./configure" yourself from the command line. When that happens, you have 3 choices:
    • Run "../configure" from the debug directory instead of "./configure" from the project directory.
    • Run "make distclean" before trying to build again in KDevelop.
    • In KDevelop, go to the Project menu -> Build Configuration -> default. This will make KDevelop use the project directory as the build directory instead of the debug directory. You can change the build configurations in the Project options dialog, under "Configure options".

What versions of Allegro are supported

We (the author of the script, kazzmir, and I, CGamesPlay) believe the script was added in the 4.1.17 version of Allegro. It might be in 4.1.16 as well. This doesn't mean a 4.0.x user couldn't, say, copy the newer allegro.m4 to his project aclocal.m4 file and follow all the directions in this article as normal, but I'm not sure if that would work or not.

Adding the configure check

The first step in adding Allegro support to your autotoolset project is making sure the end user has Allegro installed. Open up your configure.in. A simple one might look like this (of course, "project" is the name of the project you're working with):

AC_INIT(configure.in)

AM_CONFIG_HEADER(config.h)
AM_INIT_AUTOMAKE(project, 1.0.0)

AC_LANG_CPLUSPLUS
AC_PROG_CXX
AM_PROG_LIBTOOL

AC_OUTPUT(Makefile src/Makefile)

As you may or may not know, each of those lines is a macro. The macro that will test for the existence of Allegro is:

AM_PATH_ALLEGRO([MINIMUM-VERSION, [ACTION-IF-FOUND [, ACTION-IF-NOT-FOUND]]])

With this in mind, we can add rudimentary version checking support by adding the following line anywhere before the AC_OUTPUT line:

AM_PATH_ALLEGRO()

That will work nicely if you don't use any of the functions that have been added in the 4.1.x branch. If you do want to use functions like textout_ex, you'll have to change that:

AM_PATH_ALLEGRO(4.1.0)

You can follow that pattern to require any version of Allegro that you'd like. The test will be passed if the user's Allegro version is equal to or greater than the supplied version.

If the user doesn't have the necessary version of Allegro, they will see a message similar to the following:

*** The allegro-config script installed by Allegro could not be found
'''*''' If Allegro was installed in PREFIX, make sure PREFIX/bin is in
'''*''' your path, or set the ALLEGRO_CONFIG environment variable to the
'''*''' full path to allegro-config.

This doesn't mean the build will stop, however. Left as is, if the user doesn't have Allegro, config.h will say so and Allegro won't be linked in. Most likely, this isn't what you want. This is where the ACTION-IF-NOT-FOUND comes into play. If you want to require the user have Allegro, and fail the configure if they don't, you can use:

AM_PATH_ALLEGRO(, , AC_MSG_ERROR(project requires Allegro to be installed))

Of course, you can add a minimum version to the macro, if necessary.

Adding the necessary CFLAGS and LDFLAGS

Once AM_PATH_ALLEGRO has decided that the user has a suitable version of Allegro, it sets some variables that are passed off to the Makefiles. To accept these, we need to tell the Makefiles what they are. Open up the Makefile.am that defines the target that will be using Allegro. This is most likely src/Makefile.am. A sample one, not different from what KDevelop will often give (notice what bin_PROGRAMS equals. You should change "project" to the name of your program throughout this file):

bin_PROGRAMS = project
project_SOURCES = project.cpp

# set the include path found by configure
INCLUDES = $(all_includes)

# the library search path.
project_LDFLAGS = $(all_libraries) 

AM_PATH_ALLEGRO defines the make variables $(allegro_LIBS) and $(allegro_CFLAGS). To add them to the target, add the following lines:

project_LDADD = $(allegro_LIBS)
AM_CFLAGS = $(allegro_CFLAGS)
AM_CXXFLAGS = $(allegro_CFLAGS)

You can put them anywhere; the end will do.

And that's it!

Now all that's left is to rebuild the necessary files. Run the command `autoreconf` from the project directory. That actually runs the commands `aclocal`, `autoconf`, `autoheader`, and `automake`. If there were no errors, you can run `./configure` and `make` and verify that everything went well. If there were...

Possible problems

I get this error when I run autoreconf/aclocal/autoconf/configure!

When running aclocal: aclocal:configure.in:11: warning: macro `AM_PATH_ALLEGRO' not found in library
When running autoconf: configure.in:11: error: possibly undefined macro: AM_PATH_ALLEGRO
When running configure: ../configure: line 19469: syntax error near unexpected token `4.1.18,'

This comes about because aclocal cannot find allegro.m4. aclocal does not seem to search in /usr/local/share/aclocal for m4 files. This means that if you built allegro from sources yourself, you probably will have to move the file `/usr/local/share/aclocal/allegro.m4` to `/usr/share/aclocal/`. Alternatively you can create a symbolic link with:

ln -s /usr/local/share/aclocal/allegro.m4 /usr/share/aclocal/allegro.m4

Make sure you're doing this as root or with sudo.

I get lots of errors about 'underquoted definitions' when I run autoreconf/aclocal!

These aren't errors, they're warnings. They occur because of some incompatibility between a version change in aclocal. You can disregard them. As of the CVS for version 4.2.0 beta 3, this should be fixed.