= BarnOwl Modules =

BarnOwl Modules are perl packages that live in the `BarnOwl::Module::` namespace. There are two ways to install a module such that BarnOwl will recognize it:

 * As a directory tree: You can install the `MyModule` module with a directory named `MyModule` containing the file `lib/BarnOwl/Module/MyModule.pm` 
 * As a [http://par.perl.org/wiki/Main_Page PAR package] containing `lib/BarnOwl/Module/MyModule.pm`

In both cases, the `lib/` directory will be added to perl's library path when your module is loaded, so you can include additional modules there, either to include dependencies or just to divide module code into other perl modules.

Modules can be located in either of two directories, the system module path, or the user module path. By default the user module path is at `~/.owl/modules` but this can be overridden with command-line options.

= Building a BarnOwl Module =

Building a BarnOwl module is easy. The only file ''required'' is the `.pm` Therefore, a minimal module simply contains the directory tree mentioned above, and you can start using the BarnOwl APIs.

== Distributing a BarnOwl Module ==

`BarnOwl` includes a [http://search.cpan.org/~adamk/Module-Install-0.68/lib/Module/Install.pod Module::Install] plugin to make deploying modules as `PAR` files easier. Simply create a `Makefile.PL` in the top level of your module directory containing:

{{{
  #!/usr/bin/env perl
  use strict;
  use warnings;
  
  use inc::Module::Install;
  
  barnowl_module(MyModule);
  
  WriteAll;
}}}

You can then run `perl Makefile.PL` and `make MyModule.par` to automatically generate a `.par` file that you can deploy to other BarnOwl users.

Note that the first time you run `perl Makefile.PL` you will need to add BarnOwl's system library path to your `$PERL5LIB` On Athena, you would do this like:

{{{
  env PERL5LIB=/mit/barnowl/share/barnowl/lib perl Makefile.PL
  make MyModule.par
}}}

= Examples =

The BarnOwl Source includes four modules, for `Jabber`, `IRC`, `Twitter`, and `Facebook`, which are moderately complex examples of how to write a module that implements a new protocol for BarnOwl.

`nelhage` has written a number of small useful modules, that are also intended to be good examples for learning. They can be found in AFS at `/afs/athena.mit.edu/user/n/e/nelhage/Public/BarnOwl` or on the web at [http://web.mit.edu/nelhage/Public/BarnOwl http://web.mit.edu/nelhage/Public/BarnOwl]