NAME

Module::Build::Service - Manage services necessary for automated or interactive testing

VERSION

version 0.91

SYNOPSIS

You can either invoke Module::Build::Services in your Build.PL:

  use Module::Build::Services;
  Module::Build::Services->new (...,
                                services => [[postgresql => 1],
                                             [memcached => 0]])->create_build_script;

Or use it as a base class, adding hooks and such:

  package Foo::Build;
  use base qw{Module::Build::Service};

  sub SERVICE_pre_start_postgresql {
      warn "You're not gonna like this!";
  }

Then invoking that subclass in Build.PL:

  use Foo::Build;
  Foo::Build->new (...,
                   services => [[postgresql => 1],
                                [memcached => 0]])->create_build_script;

Then on the command line:

  ./Build test

or

  ./Build interact

DESCRIPTION

This subclass of Module::Build attempts to make it easy to start various support services that the testing environment may need to have access to. Browse the Module::Build::Service::* namespace for supported services, or use one of the existing definitions as a template to create your own.

Simplest usage

You have two options on how to use Module::Build::Service. If you can make do with a fairly vanilla configuration, you can simply use Module::Build::Services as you would Module::Build, and specify the services when you call new:

  use Module::Build::Services;
  Module::Build::Services->new (...,
                                services => [[postgresql => 1],
                                             [memcached => 0]])->create_build_script;

As a subclass

If you have more sophisticated needs---you need to use the hooks in the service modules to manipulate the process or something of that nature---you can use Module::Build::Service as a base class to define your hooks or otherwise add or change behavior:

  package Foo::Build;
  use base qw{Module::Build::Service};

  sub SERVICE_pre_start_postgresql {
      warn "You're not gonna like this!";
  }

Then use that subclass in Build.PL:

  use Foo::Build;
  Foo::Build->new (...,
                   services => [[postgresql => 1],
                                [memcached => 0]])->create_build_script;

As a subclass with Dist::Zilla

Since Dist::Zilla's support for Module::Build doesn't (or didn't when I first started using it a couple of years ago) make it easy to add parameters to the invocation, you need to override new to set up your services.

So you could override the base class in your dist.ini:

  [ModuleBuild]
  mb_class = Foo::Build

And then in your inc/Foo/Build.pm:

  use base qw{Module::Build::Service};
  sub new {
    my ($invokee, @args) = @_;
    my $self = $invokee->SUPER::new (@args);
    $self->services ([[postgresql => 1, service => 'llama'],
                      [memcached => 0]]);
    $self
  }

METHODS

test

In the altered build process, the test action iterates over the services that have been specified, and starts each in turn before running the tests. When the tests finish, we shut the services down in reverse order.

Called transparently when you do ./Build test.

interact

A new action, interact iterates over the services that have been specified, and starts each in turn before calling the interact method. When the method returns, we shut the services down in reverse order.

Called when you do ./Build interact.

CONFIGURATION

To configure the services to be started, you need to fill in the new services property on the Module::Build object.

The property is an arrayref, where each item is, in turn, an arrayref specifying:

the name of the service

This is the the name of a class in the Module::Build::Service namespace.

whether the service is required

A boolean flag indicating whether the failure of the service to initialize represents an error, or the build should continue.

any additional arguments

These are going to be specific to the service definition

AUTHOR

Michael Alan Dorman <mdorman@ironicdesign.com>

COPYRIGHT AND LICENSE

This software is copyright (c) 2012 by Ironic Design, Inc..

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

cpanm Module::Build::Service

perl -MCPAN -e shell
install Module::Build::Service