Father Chrysostomos > Module-ConfigureRequires-0.03 > Module::ConfigureRequires

Download:
Module-ConfigureRequires-0.03.tar.gz

Dependencies

Annotate this POD

View/Report Bugs
Module Version: 0.03   Source  

NAME ^

Module::ConfigureRequires - Backward-compatible configure_requires replacement

VERSION ^

0.03 (beta)

SYNOPSIS ^

In your Makefile.PL or Build.PL:

  use ExtUtils::MakeMaker; # or Module::Build

  use inc::Module::ConfigureRequires;
  if( !eval{ require Some::Module } ) {
    Module::ConfigureRequires::set_up(
      error_message => "Please install Some::Module and re-run $0.\n",
    )
  }

Then include your configuration prerequisities among the run-time or build prerequisites.

DESCRIPTION ^

A CPAN distribution's META.yml can contain a configure_requires entry, that lists modules needed for Makefile.PL or Build.PL to run.

Tools such as CPAN.pm and CPANPLUS automatically read this file, and everything just works, if you have the latest version.

The problem is that perl 5.10.1 and earlier do not ship with a sufficiently recent version of CPAN.pm, and even the one that comes with 5.12.x has problems.

This module attempts to solve this problem by using a different approach: The Makefile (or Build script) can be made to re-run Makefile.PL (or Build.PL), if it was generated without the necessary modules, and then re-run the make command.

The Makefile.PL script will, of course, have to be able to generate at least a dummy Makefile if the configuration prerequisites are not present, in order for this to work. It must also list the configuration prerequisites along with the build- or run-time prerequisites.

So, this is how it would work under an old CPAN shell with this setup:

 1. User types ‘install Your::Module’ at the CPAN shell.
 2. CPAN.pm downloads and unpacks Your::Module.
 3. CPAN.pm runs Makefile.PL.
 4. CPAN.pm installs the modules that Makefile.PL claims it needs,
    including Some::ConfigurePrereq.
 5. CPAN.pm runs make.
 6. The Makefile runs Makefile.PL, and then re-runs make.
 7. CPAN.pm proceeds with the tests and installation.

To avoid looping, this module will die with an error message if, when the Makefile runs Makefile.PL, the prerequisites are still not installed.

SETUP ^

In your distribution's directory, type:

  perl -MModule::ConfigureRequires=bundle-up

to copy it to the inc directory and add it to MANIFEST.

Then, in your Makefile.PL or Build.PL, before any code that manipulates command line arguments, load inc::Module::ConfigureRequires.

  use ExtUtils::MakeMaker; # or Module::Build
  use inc::Module::ConfigureRequires;

This has to come first, as it uses a command line argument as a cookie to prevent infinite loops.

Then add code that checks whether the configuration requirements are present. Have it call Module::ConfigureRequires::set_up if (and only if) the required modules are not present. Include an error_message argument. This will be used if someone tries to run make before installing the required modules. E.g.,

  if(
       !eval{ require ExtUtils::Depends }
    || ExtUtils::Depends->VERSION < .2
  ) {
    Module::ConfigureRequires::set_up(
     error_message =>
       "ExtUtils::Depends .2 or higher is required to configure this\n"
      ."module. Please install it and then re-run $0.\n"
    )
  }

Then continue the rest of the Makefile.PL or Build.PL. Make sure to include the configure requirements among the build-time or run-time dependencies. (Otherwise CPAN.pm will not know to install them.) Parts of the Makefile.PL (or Build.PL) that require those modules will have to be skipped, or made to cope without them, at least for generating a dummy Makefile.

FUNCTIONS ^

This module does not export any functions. You have to call them with the full package name.

Module::ConfigureRequires::set_up

This function chooses between one of the two functions below, based on $0 or the caller's file name, whichever ends with either Makefile.PL or Build.PL.

Module::ConfigureRequires::set_up_for_mm
Module::ConfigureRequires::set_up_for_mb

These two functions do the actual work. If set_up is unable to figure which one to use, you will have to call one of these directly.

CAVEATS ^

set_up_for_mm defines a &MY::top_targets. If your Makefile.PL also defines one, there will be a conflict, and things just might not work. Make your Makefile.PL define it conditionally, based on whether the configure prerequisites are present.

set_up_for_mb puts a wrapper around &Module::Build::Base::create_build_script that modifies the Build script after it is generated. If you have code that modifies the Build script directly, this will conflict as well.

Don't list Module::ConfigureRequires under configure_requires! That would defeat the entire purpose of this module's existence.

It's somewhat ironic that we support Module::Build, even though it doesn't come with perl 5.8.x. In those cases, this module is absolutely useless unless you bundle Module::Build with your distribution.

BUGS ^

Probably.

There are no automated tests yet.

Please report them to bug-Module-ConfigureRequires@rt.cpan.org.

AUTHOR & COPYLEFT ^

Copyright 2010, Father Chrysostomos <sprout at a server named cpan.org>

This is free software. You may use or re-distribute it under the same terms as perl.

SEE ALSO ^

ExtUtils::MakeMaker, Module::Build

syntax highlighting: