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!

About these ads

3 Comments on “So You want to write a Perl 6 module?”

  1. John says:

    Love the simplicity and practicality of this setup. Beautiful. Thanks for the article.

    One thing though: since proto is supposed to be replaced by pls, maybe the deps.proto file should be named something else?

    • ttjjss says:

      I’m glad you liked it.
      Maybe it will be replaced one day, maybe something like DEPENDENCIES? We will see.
      But remember, it’s not a standard : ) If you used any other deps file in Your modules, it will probably be tolerated by proto/pls/neutro/whatever. It’s just like everyone got used to deps.proto.

  2. you indeed have the expertise in this field. I salute you,


Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

Follow

Get every new post delivered to your Inbox.