Autoconf

From WxWiki
Jump to: navigation, search

Overview

Autoconf provides a portable way to configure a build environment for software.

Autoconf can:

  • Check compilers, linkers and other build tools
  • Check system libraries and headers
  • Provide some continuity between different versions of the above
  • Check other libraries, programs and custom tests
  • Generate a Makefile for the target system from the Makefile template

Automake works with Autoconf to provide optional dependency tracking for Makefile templates. Using it also simplifies Makefile templates.

The GNU Autotools are very powerful, and to make the best use of them you will need the manuals:

Process

Autoconf generates a configure shell script that will run on any Bourne compatible shell. This includes virtually all Unix-like systems. Windows users can use MSYS (usually with MinGW) or Cygwin to run configure. The software maintainer generates the configure script so that users building the software do not need Autoconf themselves.

The configure script when run, generates the Makefile from a Makefile template. The Makefile will work with various make implementations.

Creating configure.ac

You can generate a basic configure.ac using autoscan.

  • Backup any previous build system & Makefiles used
  • Run autoscan in the top level folder of your project
  • Copy configure.scan to configure.ac
  • Edit configure.ac
  • Find the AC_INIT macro and fill in FULL-PACKAGE-NAME, VERSION, BUG-REPORT-ADDRESS.
  • Before AC_OUTPUT, add AC_CONFIG_FILES([Makefile subdir/Makefile]) listing Makefiles for each Makefile template, separating with spaces. These will be the output Makefiles after configure is run.

Checking for wxWidgets

The next step is to add tests for wxWidgets to configure.ac. Add these after the '# Checks for libraries' line.

AM_OPTIONS_WXCONFIG
reqwx=2.4.0
AM_PATH_WXCONFIG($reqwx, wxWin=1)
if test "$wxWin" != 1; then
	AC_MSG_ERROR([
		wxWidgets must be installed on your system.
 
		Please check that wx-config is in path, the directory
		where wxWidgets libraries are installed (returned by
		'wx-config --libs' or 'wx-config --static --libs' command)
		is in LD_LIBRARY_PATH or equivalent variable and
		wxWidgets version is $reqwx or above.
		])
fi
 
CPPFLAGS="$CPPFLAGS $WX_CPPFLAGS"
CXXFLAGS="$CXXFLAGS $WX_CXXFLAGS_ONLY"
CFLAGS="$CFLAGS $WX_CFLAGS_ONLY"
LIBS="$LIBS $WX_LIBS"

Set reqwx to the wxWidgets version number x.y.z required by your software.

You can then use @CPPFLAGS@, @CXXFLAGS@ and @LIBS@ in your Makefile template. They will be replaced in the output Makefile by their values found by running configure.

AM_OPTIONS_WXCONFIG and AM_PATH_WXCONFIG macros

The AM_OPTIONS_WXCONFIG and AM_PATH_WXCONFIG macros are distributed with wxWidgets in wxwin.m4 and should be installed if wxWidgets was built with the supplied configure script. The macros will be included in a local project file, aclocal.m4 when autoreconf is run. If you have not installed your build of wxWidgets, copy the wxwin.m4 file and include it before using the macros using m4_include(wxwin.m4).

Note: If you installed the library as an RPM package, wxwin.m4 is provided in the package wxGTK-devel (wx-common in Ubuntu 8.04). If using yum as your package manager, you can install this with the command yum install wxGTK-devel.

  • AM_OPTIONS_WXCONFIG adds options like --with-wx-config to enable using an uninstalled build of wxWidgets. You can see all these options by running ./configure --help=short
  • AM_PATH_WXCONFIG checks that the installed version of wxWidgets is at least the required version passed to it, and AC_SUBSTitute WX_CPPFLAGS, WX_CFLAGS, WX_CXXFLAGS, WX_CFLAGS_ONLY, WX_CXXFLAGS_ONLY, WX_LIBS, WX_LIBS_STATIC, WX_VERSION to use in a Makefile template.

Makefile templates

Autoconf will use Makefile.in as a Makefile template to generate the Makefiles, each specified earlier with AC_CONFIG_FILES. (If you use Automake, Makefile.am is used to generate Makefile.in).

Makefile.in is written like the output Makefile but with @VAR@ variables that will be replaced by their values found after running the configure script. Custom variables are set in configure.ac, using AC_SUBST. Standard variables defined include:

  • CXX, C++ compiler
  • CPPFLAGS, Pre-processor flags: includes and defines
  • CXXFLAGS, C++ compile flags (-g -O2 by default for GNU g++)
  • LIBS, libraries to link to
  • Various other tools and flags

Automake Makefile.am templates are not covered here (yet).

01-Feb-2009 Automake Template
This is an automake template ("Makefile.am") which builds three programs.


  • wxpanel --- a simple wxWidget program that just displays hello world in static text
  • togglebutton --- the three color toggle button from the tutorial site
  • cpexample --- a standard c++ program with only one source file and no headers
#sample Makefile.am
#builds two wxWidgets programs and one standard (text) c++ program

#define three output files
bin_PROGRAMS = wxpanel togglebutton cpexample

#wxpanel definitions
wxpanel_SOURCES = mainwxpanel.cc statictext.cc statictext.h main.h
wxpanel_LDADD = @LIBS@
wxpanel_CXXFLAGS = @CXXFLAGS@

#togglebutton definitions
togglebutton_SOURCES = togglebutton.cc main.cc statictext.h main.h togglebutton.h
togglebutton_LDADD = @LIBS@
toggelbutton_CXXFLAGS = @CXXFLAGS@

#cpexample definitions (note, use defaults, no definition necessary)
#cpexample_SOURCES = cpexample.cc

Once this Makefile.am is in place in your source directory, proceed to the top of the project directory and execute these commands to build Makefile.in, then Makefile, and then build your project

$ aclocal
$ autoconf
$ automake
$ ./configure
$ make

Generating the configure script

  • Run autoreconf -fvi

This runs the various autotools for you. The -fvi arguments are first used to install any required files. Rerun autoreconf without arguments if you change configure.ac. You can also use the -Wall option to show warnings.

Include config.h

autoscan should include the AC_CONFIG_HEADER macro in configure.ac, which integrates the autoheader tool. This generates a configuration header file with macros defined for the target build system.

You should include this file in all source files that use system headers, like this:

  • #include <config.h>

You can then make your code more portable by using the config.h macros to test which headers to include, e.g.:

#ifdef HAVE_SYS_TYPES_H
	#include <sys/types.h>
#endif

autoheader also defines useful macros like PACKAGE_STRING as "Program 0.1" based on the AC_INIT configure.ac macro.

Testing the build system

If autoreconf ran successfully, you should now have a configure script. The project can now be distributed, and can be built as follows:

  • Run ./configure
  • Run make

wxAuto example project

Note: this project uses custom checks for wxWidgets (instead of using wxwin.m4), and the configure.in name is deprecated in favour of configure.ac.

For an example on how to use autoconf/make for your wxWidgets project, see http://linus.mccabe.nu/?/article/articleview/wxAuto&themex=public

You will need gnu autotools: automake, autoconf, etc... I'd imagine these are available through whatever package manager you are using. After you have untarred wxAuto, have a look at the files and:

1) run ./autogen.sh

2a) If you've not done a system install of wxWidgets, try ./configure --with-wx-config=WX-INSTALL-DIR/build/wx-config

2b) else ./configure should be fine

3) make