NAME

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

DESCRIPTION

Packaging 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:

#!/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::Core' => '0.200',
  },
);
$build->create_build_script;

You'll want to create META files and a MANIFEST for your distribution. Module::Build can do this for you:

$ perl Build.PL

 # build a MANIFEST.SKIP for your dist:
$ ./Build manifest_skip

 # build MANIFEST:
$ ./Build manifest

 # build META files:
$ ./Build distmeta

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

App::cpanminus makes this even easier:

 # Ereate a dist tarball:
$ ./Build dist

 # Easy install via cpanm:
$ cpanm ./Bot-Cobalt-Plugin-MyPlugin-0.001.tar.gz

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