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