pod/perlnewmod.pod

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