The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.

NAME

Bot::Cobalt::Manual::Plugins::Dist - Packaging Cobalt plugins

DESCRIPTION

Packaging Bot::Cobalt plugins is just like packaging any other Perl module.

Typically, the easiest way to do so quickly is via Module::Build. (For more involved distributions you may want to look at ExtUtils::MakeMaker).

(This guide only covers packaging plugins; See Bot::Cobalt::Manual::Plugins for more on writing plugins and Bot::Cobalt::Manual::Plugins::Tutorial for a walk-through.)

Layout

Create a dist dir for your module:

  $ mkdir Bot-Cobalt-Plugin-MyPlugin

  $ cd Bot-Cobalt-Plugin-MyPlugin

   # create this dist's libdir:
  $ mkdir -p lib/Bot/Cobalt/Plugin/

  $ cd lib/Bot/Cobalt/Plugin/

   # create your plugin:
  $ $EDITOR MyPlugin.pm

Build.PL

Module::Build requires a Build.PL file.

Here's a simple one based around one centralized plugin; your plugin will need to declare a proper $VERSION:

  #!/usr/bin/perl
  ## Simple example Build.PL
  my $build = Module::Build->new(
    module_name   => "Bot::Cobalt::Plugin::User::MyPlugin",
    dist_abstract => "My Bot::Cobalt plugin",
    dist_author   => 'Me <myself@example.ext>',
    license => 'perl',
    create_makefile_pl => 'small',
    requires => {
      'Bot::Cobalt' => 0.01,
    },
  );
  $build->create_build_script;

Create a dist tarball: $ ./Build dist

Users of your plugin can install the distribution (and dependencies) via cpan by unpacking your plugin dist and specifying the local directory:

  $ cd Bot-Cobalt-Plugin-MyPlugin
  $ cpan .

...or via Module::Build directly:

  $ perl Build.PL

  $ ./Build

   # may need root access (or perhaps L<local::lib>):
  $ ./Build install

When your plugin is release-ready, please consider posting it to CPAN.

Configuration files

Bot::Cobalt comes with the cobalt2-plugin-installcf tool, allowing for easy installation of plugin-specific configuration files to user configuration directories.

In order to provide a configuration file installable via the installcf tool, your plugin needs a Conf.pm module providing a 'conf' class method.

Here's an example demonstrating using the DATA filehandle to provide an example configuration:

  ## In lib/Bot/Cobalt/Plugin/MyPlugin/Conf.pm
  package Bot::Cobalt::Plugin::MyPlugin::Conf;
  
  sub conf { local $/; my $cf = <DATA>; return $cf }

  __DATA__
  ---
  ## MyPlugin example configuration.
  Opts:

    Enable_Snacks:
      - pie
      - cake

    Do_Stuff: 1

AUTHOR

Jon Portnoy <avenj@cobaltirc.org>

http://www.cobaltirc.org