Debian Codegraph @

upstream/fedora-44/man1/perlnewmod.1

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