So You want to write a Perl 6 module?

As the module database grows bigger and stronger, who wouldn’t like to see his/her work there? Here’s a bunch of notes to get You started. Please note it’s rather a piece of advice, not the standard of any sort. There is no standard about preparing modules, yet when it fullfils the below conventions it’ll have a bigger chance of working everywhere without problems. They’re based on the proto PIONEER document, but remember, there’s no standard. It’s just a convention, You can accept it or ignore it.

To create a Perl 6 module, collect the .pm files and put them all inside the lib/ directory of Your project.

“That’s all?” You’ll ask. “No metainfo files, no dist.ini, no Configure, Makefile, anything?”. No. They’re all optional. The simple lib/ directory is enough for Your module to be easily compiled and installed by a module management tool. From now on, everything is optional. Hell, even lib/ is optional, if You just want to install some executables.

But You’ll usually need more. Tests! Everyone likes tests. You definitely want to ensure that Your module actually works. You don’t? Come on, I know You do.

So here’s another simple thing: just put all the tests in a t/ directory, and they will all be checked before the module is installed. Again, no Makefile or anything is required.

Same goes for executables. If You actually write a complete application, or just want a helper script as a bonus, put it in the bin/ directory and it will also get automagically installed. Easy peasy.

So basically You’ll end up with something like this:

• README – not going to be installed, but it’s good to have one
• lib/Acme/Nothing.pm – an actual module to be compiled and installed
• t/00-basic.t – tests to be run before installation
• bin/do_nothing – will be compiled, installed and available as a ‘do_nothing’ executable

And You’re done! Go and upload Your new, shiny module to Github and poke one of the proto maintainers to put it on the modules list.

But what if You actually want that Makefile? Of course You can create one, and it will be used by a module installer to ‘make’, ‘make test’ and ‘make install’ Your module. You can also include Configure.pl script (Perl 6 is preffered here), and it will be run before compilation. If You don’t really want to write Your own makefile, that problem is also solved alredy. Ufo will automagically build a perfect Makefile for You, able to compile, test, even install. If You won’t ship any Makefile with Your project, a module installer is likely to generate it with ufo anyway, so it won’t have to do everything by itself.

One last thing. Dependencies. Hell and blessing at the same time. To ensure Your dependencies will be installed before Your module is, add the deps.proto (proto.deps is also used sometimes) file in a toplevel directory, with each required module name in a new line.

So, to sum it up:

1. Dependencies listed in deps.proto will be installed if they aren’t
2. Files in lib/ and bin/ will get compiled
3. Tests in t/ will be run
4. Everything from lib/ and bin/ will be installed

As a bonus, You can add a logotype/ directory with logo_32x32.png file. On http://modules.perl6.org/ You can see how it will appear in the modules database.

It’s nice to see how the existing modules look like. Math::Model and Yapsi are good examples.

Remember, these aren’t the rules, and there is no standard. It’s just nice to have it simple and not to overcomplicate too much.

That’s all for today. Happy hacking! Fun, fame, and ladies’ hearts await!

---