Changes between Initial Version and Version 1 of CreatingAModule


Ignore:
Timestamp:
Dec 1, 2009, 10:49:48 AM (12 years ago)
Author:
nelhage@mit.edu
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • CreatingAModule

    v1 v1  
     1
     2= BarnOwl Modules =
     3
     4BarnOwl 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:
     5
     6 * As a directory tree: You can install the `MyModule` module with a directory named `MyModule` containing the file `lib/BarnOwl/Module/MyModule.pm`
     7 * As a [http://par.perl.org/wiki/Main_Page PAR package] containing `lib/BarnOwl/Module/MyModule.pm`
     8
     9In 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.
     10
     11Modules 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.
     12
     13= Building a BarnOwl Module =
     14
     15Building 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.
     16
     17== Distributing a BarnOwl Module ==
     18
     19`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:
     20
     21{{{
     22  #!/usr/bin/env perl
     23  use strict;
     24  use warnings;
     25 
     26  use inc::Module::Install;
     27 
     28  barnowl_module(MyModule);
     29 
     30  WriteAll;
     31}}}
     32
     33You can then run `perl Makefile.PL` and `make MyModule.par` to automatically generate a `.par` file that you can deploy to other BarnOwl users.
     34
     35Note 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:
     36
     37{{{
     38  env PERL5LIB=/mit/barnowl/share/barnowl/lib perl Makefile.PL
     39  make MyModule.par
     40}}}
     41
     42= Examples =
     43
     44The BarnOwl Source includes two modules, for `Jabber` and `IRC` which are moderately complex examples of how to write a module that implements a new protocol for BarnOwl.
     45
     46`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]