=pod
=head1 NAME
Bot::Cobalt::Manual::Plugins::Dist - Packaging Cobalt plugins
=head1 DESCRIPTION
Packaging L<Bot::Cobalt> plugins is just like packaging any other Perl
module.
Typically, the easiest way to do so quickly is via L<Module::Build>.
(For more involved distributions you may want to look at
L<ExtUtils::MakeMaker>).
(This guide only covers packaging plugins; See
L<Bot::Cobalt::Manual::Plugins> for more on writing plugins and
L<Bot::Cobalt::Manual::Plugins::Tutorial> for a walk-through.)
=head2 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
=head2 Build.PL
L<Module::Build> requires a C<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
C<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.
=head2 Configuration files
L<Bot::Cobalt> comes with the L<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
=head1 AUTHOR
Jon Portnoy <avenj@cobaltirc.org>
=cut