The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
ExtUtils-Autoconf-0.02
River stage zero No dependents
++
/ ExtUtils::Autoconf

NAME

ExtUtils::Autoconf - Perl interface to GNU autoconf

VERSION

Version 0.02

SYNOPSIS

    use ExtUtils::Autoconf;

    my $ac = ExtUtils::Autoconf->new;

    $ac->autogen;
    $ac->configure;

    $ac->clean;
    $ac->realclean;

DESCRIPTION

ExtUtils::Autoconf is a thin wrapper around GNU autoconf/autoheader which allows to run those tools easily from perl. This allows using autoconf for configuring perl modules and especially extensions in a portable way without messing around with the compilation of C code from perl.

TYPICAL USAGE

Typically ExtUtils::Autoconf is being used from Makefile.PLs in Perl module distributions.

AUTOCONF

To use it in your module you first need to create a directory called autoconf (or call it something else and set wd accordingly. This is the working directory for ExtUtils::Autoconf and the programs it invokes.

Create a configure.ac or configure.in file in this directory. This file contains invocations of autoconf macros that test the system features your package needs or can use. Autoconf macros already exist to check for many features; see Existing Tests, for heir descriptions. For most other features, you can use Autoconf template macros to produce custom checks; see Writing Tests, for information about them.

A typical configure.ac might look like this:

    AC_PREREQ(2.50)
    AC_INIT
    AC_CONFIG_HEADERS([config.h])

    AC_DEFINE_UNQUOTED(PERL_OSNAME, "$osname", [The operating system perl was ocnfigured for])

    AC_OUTPUT

In this script we first require autoconf version 2.50, then initialize the system and tell it to create a config header file called config.h with the results it gathered while running the configure script.

In this script we only have one result called PERL_OSNAME. This is simply set to the value of the environment variable $osname, which corresponds to perls $Config{osname}.

After our tests we do AC_OUTPUT to write our results to config.h.

That's it for the configure.ac part. Now include the autoconf/config.h file in your C or C++ code of the module and use the defines in there.

Makefile.PL

Execute the configure script which will be generated from the above configure.ac when someone tries to build your module you'll need to modify your Makefile.PL script.

It's better to assume that the user of your module doesn't have autoconf and autoheader installed so you need to generate configure and config.h before rolling your distribution together.

ExtUtils::MakeMaker

This is easily done by using the dist target of your generated Makefile:

    WriteMakefile(
        # usual arguments to WriteMakefile()..
        dist => {
            PREOP => q{$(PERLRUN) -MExtUtils::Autoconf -e'ExtUtils::Autoconf->run_autogen'},
        },
    );

autogen() and configure() automatically generate some files. To clean those up automatically when doing make clean or make realclean you can use MakeMakers postamble feature. We also add some additional Makefile targets for the ease of use:

    sub postamble {
        return <<"EOM";
    autogen :
    \t\$(PERLRUN) -MExtUtils::Autoconf -e 'ExtUtils::Autoconf->run_autogen'

    configure :
    \t\$(PERLRUN) -MExtUtils::Autoconf -e'ExtUtils::Autoconf->run_configure'

    autoclean :
    \t\$(PERLRUN) -MExtUtils::Autoconf -e'ExtUtils::Autoconf->run_realclean'

    realclean purge ::
    \t\$(PERLRUN) -MExtUtils::Autoconf -e 'ExtUtils::Autoconf->run_realclean'

    clean ::
    \t\$(PERLRUN) -MExtUtils::Autoconf -e 'ExtUtils::Autoconf->run_clean'
    EOM
    }

Now everything will work, except for the actual execution of the configure script during perl Makefile.PL. To make it work do something like this in Makefile.PL:

    use strict;
    use warnings;
    use ExtUtils::MakeMaker;

    if (!eval 'use ExtUtils::Autoconf;') {
        print STDERR $@, "\n";

        WriteMakefile(
                PREREQ_FATAL => 1,
                PREREQ_PM    => {
                    'ExtUtils::Autoconf' => 0,
                },
        );

        exit 1; # not reached
    }

    my $ac = ExtUtils::Autoconf->new;
    $ac->configure;

    # rest of the usual Makefile.PL here..

The if condition covers those cases where ExtUtils::Autoconf isn't installed yet. I'll raise a fatal error which will hopefully tell CPAN to install it and rerun Makefile.PL.

Module::Install

If you're using Module::Install for your Makefile.PL, you can simply install Module::Install::Autoconf and do configure() in it.

SUBROUTINES/METHODS

new

    my $ac = ExtUtils::Autoconf->new($arguments);

This is the constructor.. Takes an optional hashref with additional $arguments. Returns a new ExtUtils::Autoconf instance.

The following arguments are supported:

  • wd

    The working directory for autoconf. All commands issued by ExtUtils::Autoconf will be executed in this directory.

  • autoconf

    The name of the autoconf executable.

  • autoheader

    The name of the autoheader executable.

  • env

    A hash reference with the environment variables which will be set for each program execution issued by ExtUtils::Autoconf.

    The default looks like this:

        {
        MAKE     => $Config{ make     },
        SHELL    => $Config{ sh       },
        CC       => $Config{ cc       },
        CPPFLAGS => $Config{ cppflags },
        CFLAGS   => $Config{ ccflags  },
        LDFLAGS  => $Config{ ldflags  },
        LINKER   => $Config{ ld       },
        LIBS     => '',
        %Config,
    }

    Where %Config is the local perl configuration from Config.pm. To add additional environment variables or to override existing ones do:

        my $ac = ExtUtils::Autoconf->new({
            env => {
                key1 => 'val1',
                key2 => 'val2',
            },
    });

configure

    $ac->configure;

Runs the configure script. If the configure script doesn't exist yet it'll run autogen(). Returns 1 on success or croaks on failure.

autogen

    $ac->autogen;

Runs autoheader and autoconf to generate config.h.in and configure from configure.ac or configure.in. Returns 1 on success or croaks on failure.

clean

    $ac->clean;

Cleans up files which were generated during configure(). Always returns something true.

realclean

    my $success = $ac->realclean;

Cleans up files which were generated during autogen() and configure(). Always returns something true.

wd

    my $wd = $ac->wd;
    $ac->wd($new_wd);

Accessor for the wd (working directory) option. When called without any argument it returns the current working directory. When called with one argument the working directory is set to $new_wd and the new working directory is returned.

autoconf

    my $autoconf = $ac->autoconf;
    $ac->autoconf($new_autoconf);

Accessor for the name of the autoconf executable.

autoheader

    my $autoheader = $ac->autoheader;
    $ac->autoheader($new_autoheader);

Accessor for the name of the autoheader executable.

env

    my $env = $ac->env;
    my $value = $ac->env($key);
    $ac->env($key => $value);

Accessor for the environment option. When called without any option it returns a hash reference with all the environment variables that will be set when running any command.

When called with one argument it'll return the value of the environment variable corresponding to a given $key.

When called with two arguments the environment variable $key will be set to $value.

run_configure

    perl -MExtUtils::Autoconf -e'ExtUtils::Autoconf->run_configure' $wd

This class method is intended to be used from Makefiles and similar things and reads its arguments from @ARGV. It constructs a new ExtUtils::Autoconf instance with the given $wd and runs configure().

run_autogen

    perl -MExtUtils::Autoconf -e'ExtUtils::Autoconf->run_autogen' $wd, $autoconf, $autoheader

This class method is intended to be used from Makefiles and similar things and reads its arguments from @ARGV. It constructs a new ExtUtils::Autoconf instance with the given $wd, $autoconf, $autoheader and runs autogen().

run_clean

    perl -MExtUtils::Autoconf -e'ExtUtils::Autoconf->run_clean' $wd

This class method is intended to be used from Makefiles and similar things and reads its arguments from @ARGV. It constructs a new ExtUtils::Autoconf instance with the given $wd and runs clean().

run_realclean

    perl -MExtUtils::Autoconf -e'ExtUtils::Autoconf->run_realclean' $wd

This class method is intended to be used from Makefiles and similar things and reads its arguments from @ARGV. It constructs a new ExtUtils::Autoconf instance with the given $wd and runs realclean().

DIAGNOSTICS

configure failed. Check %s/config.log

Running ./configure failed. Diagnostic messages may be found in the according config.log file.

autogen failed. check the error messages above.

Running autoheader or autoconf failed. Probably your configure.ac is erroneous. Try running autoheader and autoconf manually.

AUTHOR

Florian Ragwitz <rafl@debian.org>

BUGS

Please report any bugs or feature requests to <bug-extutils-autoconf@rt.cpan.org>, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=ExtUtils-Autoconf. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

You can find documentation for this module with the perldoc command.

    perldoc ExtUtils::Autoconf

You can also look for information at:

ACKNOWLEDGEMENTS

Marc Lehmann <schmorp@schmorp.de> for the idea and a prof-of-concept implementation (autoconf.pm) in IO::AIO.

LICENSE AND COPYRIGHT

Copyright 2006 Florian Ragwitz, all rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.