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