1=head1 NAME 2 3perlnewmod - preparing a new module for distribution 4 5=head1 DESCRIPTION 6 7This document gives you some suggestions about how to go about writing 8Perl modules, preparing them for distribution, and making them available 9via CPAN. 10 11One of the things that makes Perl really powerful is the fact that Perl 12hackers tend to want to share the solutions to problems they've faced, 13so you and I don't have to battle with the same problem again. 14 15The main way they do this is by abstracting the solution into a Perl 16module. If you don't know what one of these is, the rest of this 17document isn't going to be much use to you. You're also missing out on 18an awful lot of useful code; consider having a look at L<perlmod>, 19L<perlmodlib> and L<perlmodinstall> before coming back here. 20 21When you've found that there isn't a module available for what you're 22trying to do, and you've had to write the code yourself, consider 23packaging up the solution into a module and uploading it to CPAN so that 24others can benefit. 25 26=head2 Warning 27 28We're going to primarily concentrate on Perl-only modules here, rather 29than XS modules. XS modules serve a rather different purpose, and 30you should consider different things before distributing them - the 31popularity of the library you are gluing, the portability to other 32operating systems, and so on. However, the notes on preparing the Perl 33side of the module and packaging and distributing it will apply equally 34well to an XS module as a pure-Perl one. 35 36=head2 What should I make into a module? 37 38You should make a module out of any code that you think is going to be 39useful to others. Anything that's likely to fill a hole in the communal 40library and which someone else can slot directly into their program. Any 41part of your code which you can isolate and extract and plug into 42something else is a likely candidate. 43 44Let's take an example. Suppose you're reading in data from a local 45format into a hash-of-hashes in Perl, turning that into a tree, walking 46the tree and then piping each node to an Acme Transmogrifier Server. 47 48Now, quite a few people have the Acme Transmogrifier, and you've had to 49write something to talk the protocol from scratch - you'd almost 50certainly want to make that into a module. The level at which you pitch 51it is up to you: you might want protocol-level modules analogous to 52L<Net::SMTP|Net::SMTP> which then talk to higher level modules analogous 53to L<Mail::Send|Mail::Send>. The choice is yours, but you do want to get 54a module out for that server protocol. 55 56Nobody else on the planet is going to talk your local data format, so we 57can ignore that. But what about the thing in the middle? Building tree 58structures from Perl variables and then traversing them is a nice, 59general problem, and if nobody's already written a module that does 60that, you might want to modularise that code too. 61 62So hopefully you've now got a few ideas about what's good to modularise. 63Let's now see how it's done. 64 65=head2 Step-by-step: Preparing the ground 66 67Before we even start scraping out the code, there are a few things we'll 68want to do in advance. 69 70=over 3 71 72=item Look around 73 74Dig into a bunch of modules to see how they're written. I'd suggest 75starting with L<Text::Tabs|Text::Tabs>, since it's in the standard 76library and is nice and simple, and then looking at something like 77L<Time::Zone|Time::Zone>, L<File::Copy|File::Copy> and then some of the 78C<Mail::*> modules if you're planning on writing object oriented code. 79 80These should give you an overall feel for how modules are laid out and 81written. 82 83=item Check it's new 84 85There are a lot of modules on CPAN, and it's easy to miss one that's 86similar to what you're planning on contributing. Have a good plough 87through the modules list and the F<by-module> directories, and make sure 88you're not the one reinventing the wheel! 89 90=item Discuss the need 91 92You might love it. You might feel that everyone else needs it. But there 93might not actually be any real demand for it out there. If you're unsure 94about the demand your module will have, consider sending out feelers 95on the C<comp.lang.perl.modules> newsgroup, or as a last resort, ask the 96modules list at C<modules@perl.org>. Remember that this is a closed list 97with a very long turn-around time - be prepared to wait a good while for 98a response from them. 99 100=item Choose a name 101 102Perl modules included on CPAN have a naming hierarchy you should try to 103fit in with. See L<perlmodlib> for more details on how this works, and 104browse around CPAN and the modules list to get a feel of it. At the very 105least, remember this: modules should be title capitalised, (This::Thing) 106fit in with a category, and explain their purpose succinctly. 107 108=item Check again 109 110While you're doing that, make really sure you haven't missed a module 111similar to the one you're about to write. 112 113When you've got your name sorted out and you're sure that your module is 114wanted and not currently available, it's time to start coding. 115 116=back 117 118=head2 Step-by-step: Making the module 119 120=over 3 121 122=item Start with F<h2xs> 123 124Originally a utility to convert C header files into XS modules, 125L<h2xs|h2xs> has become a useful utility for churning out skeletons for 126Perl-only modules as well. If you don't want to use the 127L<Autoloader|Autoloader> which splits up big modules into smaller 128subroutine-sized chunks, you'll say something like this: 129 130 h2xs -AX -n Net::Acme 131 132The C<-A> omits the Autoloader code, C<-X> omits XS elements, and C<-n> 133specifies the name of the module. 134 135=item Use L<strict|strict> and L<warnings|warnings> 136 137A module's code has to be warning and strict-clean, since you can't 138guarantee the conditions that it'll be used under. Besides, you wouldn't 139want to distribute code that wasn't warning or strict-clean anyway, 140right? 141 142=item Use L<Carp|Carp> 143 144The L<Carp|Carp> module allows you to present your error messages from 145the caller's perspective; this gives you a way to signal a problem with 146the caller and not your module. For instance, if you say this: 147 148 warn "No hostname given"; 149 150the user will see something like this: 151 152 No hostname given at /usr/local/lib/perl5/site_perl/5.6.0/Net/Acme.pm 153 line 123. 154 155which looks like your module is doing something wrong. Instead, you want 156to put the blame on the user, and say this: 157 158 No hostname given at bad_code, line 10. 159 160You do this by using L<Carp|Carp> and replacing your C<warn>s with 161C<carp>s. If you need to C<die>, say C<croak> instead. However, keep 162C<warn> and C<die> in place for your sanity checks - where it really is 163your module at fault. 164 165=item Use L<Exporter|Exporter> - wisely! 166 167C<h2xs> provides stubs for L<Exporter|Exporter>, which gives you a 168standard way of exporting symbols and subroutines from your module into 169the caller's namespace. For instance, saying C<use Net::Acme qw(&frob)> 170would import the C<frob> subroutine. 171 172The package variable C<@EXPORT> will determine which symbols will get 173exported when the caller simply says C<use Net::Acme> - you will hardly 174ever want to put anything in there. C<@EXPORT_OK>, on the other hand, 175specifies which symbols you're willing to export. If you do want to 176export a bunch of symbols, use the C<%EXPORT_TAGS> and define a standard 177export set - look at L<Exporter> for more details. 178 179=item Use L<plain old documentation|perlpod> 180 181The work isn't over until the paperwork is done, and you're going to 182need to put in some time writing some documentation for your module. 183C<h2xs> will provide a stub for you to fill in; if you're not sure about 184the format, look at L<perlpod> for an introduction. Provide a good 185synopsis of how your module is used in code, a description, and then 186notes on the syntax and function of the individual subroutines or 187methods. Use Perl comments for developer notes and POD for end-user 188notes. 189 190=item Write tests 191 192You're encouraged to create self-tests for your module to ensure it's 193working as intended on the myriad platforms Perl supports; if you upload 194your module to CPAN, a host of testers will build your module and send 195you the results of the tests. Again, C<h2xs> provides a test framework 196which you can extend - you should do something more than just checking 197your module will compile. 198 199=item Write the README 200 201If you're uploading to CPAN, the automated gremlins will extract the 202README file and place that in your CPAN directory. It'll also appear in 203the main F<by-module> and F<by-category> directories if you make it onto 204the modules list. It's a good idea to put here what the module actually 205does in detail, and the user-visible changes since the last release. 206 207=back 208 209=head2 Step-by-step: Distributing your module 210 211=over 3 212 213=item Get a CPAN user ID 214 215Every developer publishing modules on CPAN needs a CPAN ID. See the 216instructions at C<http://www.cpan.org/modules/04pause.html> (or 217equivalent on your nearest mirror) to find out how to do this. 218 219=item C<perl Makefile.PL; make test; make dist> 220 221Once again, C<h2xs> has done all the work for you. It produces the 222standard C<Makefile.PL> you'll have seen when you downloaded and 223installs modules, and this produces a Makefile with a C<dist> target. 224 225Once you've ensured that your module passes its own tests - always a 226good thing to make sure - you can C<make dist>, and the Makefile will 227hopefully produce you a nice tarball of your module, ready for upload. 228 229=item Upload the tarball 230 231The email you got when you received your CPAN ID will tell you how to 232log in to PAUSE, the Perl Authors Upload SErver. From the menus there, 233you can upload your module to CPAN. 234 235=item Announce to the modules list 236 237Once uploaded, it'll sit unnoticed in your author directory. If you want 238it connected to the rest of the CPAN, you'll need to tell the modules 239list about it. The best way to do this is to email them a line in the 240style of the modules list, like this: 241 242 Net::Acme bdpOP Interface to Acme Frobnicator servers FOOBAR 243 ^ ^^^^^ ^ ^ 244 | ||||| Module description Your ID 245 | ||||| 246 | ||||\-Public Licence: (p)standard Perl, (g)GPL, (b)BSD, 247 | |||| (l)LGPL, (a)rtistic, (o)ther 248 | |||| 249 | |||\- Interface: (O)OP, (r)eferences, (h)ybrid, (f)unctions 250 | ||| 251 | ||\-- Language: (p)ure Perl, C(+)+, (h)ybrid, (C), (o)ther 252 | || 253 Module |\--- Support: (d)eveloper, (m)ailing list, (u)senet, (n)one 254 Name | 255 \---- Development: (i)dea, (c)onstructions, (a)lpha, (b)eta, 256 (R)eleased, (M)ature, (S)tandard 257 258plus a description of the module and why you think it should be 259included. If you hear nothing back, that means your module will 260probably appear on the modules list at the next update. Don't try 261subscribing to C<modules@perl.org>; it's not another mailing list. Just 262have patience. 263 264=item Announce to clpa 265 266If you have a burning desire to tell the world about your release, post 267an announcement to the moderated C<comp.lang.perl.announce> newsgroup. 268 269=item Fix bugs! 270 271Once you start accumulating users, they'll send you bug reports. If 272you're lucky, they'll even send you patches. Welcome to the joys of 273maintaining a software project... 274 275=back 276 277=head1 AUTHOR 278 279Simon Cozens, C<simon@cpan.org> 280 281=head1 SEE ALSO 282 283L<perlmod>, L<perlmodlib>, L<perlmodinstall>, L<h2xs>, L<strict>, 284L<Carp>, L<Exporter>, L<perlpod>, L<Test>, L<ExtUtils::MakeMaker>, 285http://www.cpan.org/ , Ken Williams' tutorial on building your own 286module at http://mathforum.org/~ken/perl_modules.html 287