-
Notifications
You must be signed in to change notification settings - Fork 30
/
getting-started.html
309 lines (272 loc) · 11.8 KB
/
getting-started.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<title>
Perl Training Australia -
Starting a module with Module::Starter
</title>
<link rel="shortcut icon" href="/favicon.ico" />
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1" />
</head>
<body>
<h1> Starting a module with Module::Starter </h1>
<p>
<a href="http://perltraining.com.au/tips/"><b>[ Perl tips index]</b></a>
<br />
<a href="http://perltraining.com.au/tips/cgi-bin/mailman/listinfo/perl-tips"><b>[ Subscribe to Perl tips ]</b></a>
</p>
<p>
Starting a new module can be a lot of work. A good module
should have a build system, documentation, a test suite, and
numerous other bits and pieces to assist in its easy packaging
and development. These are useful even if we never release our
module to CPAN.
</p>
<p>
Setting this up can be a lot of work, especially if you've
never done it before. While the <code>h2xs</code> tool that
comes with Perl will do some of this for you, it's showing its
age, and doesn't allow us to take advantage of recent tools.
We want to spend our time writing code, not trying to decode
our build system.
</p>
<p>
That's where <code>Module::Starter</code> comes in handy.
It provides a simple, command-line tool to create a skeleton
module quickly and easily.
</p>
<!-- END_SUMMARY -->
<h2>Using module-starter</h2>
<p>
Before we can build our module, we need to
install <code>Module::Starter</code> from the CPAN.
<code>Module::Starter</code> allows us to choose from a variety of
build frameworks, from the aging <code>ExtUtils::MakeMaker</code>
to <code>Module::Install</code> and <code>Module::Build</code>.
While <code>ExtUtils::MakeMaker</code> comes standard with Perl,
you may need to install the other build frameworks. At Perl
Training Australia we generally use <code>Module::Install</code>.
</p>
<p>
Creating a module with <code>Module::Starter</code> couldn't be easier. On
the command line we simply write:
</p>
<pre>
module-starter --module=My::Module --author="Jane Smith"
--email=jane.smith@example.com --builder=Module::Install</pre>
<p>
The module name, author, and e-mail switches are all required.
We've used the optional <code>--builder</code> switch to specify
we want to use <code>Module::Install</code> as our build-system,
instead of the default <code>ExtUtils::MakeMaker</code>.
</p>
<p>
Once this is done, you should have a <code>My-Module</code>
directory with a skeleton module inside.
</p>
<p>
</p>
<h2>A skeleton tour</h2>
<p>
If you've never created a module before, or you've been making
them by hand, then it's nice to take a look at what you get for
your <code>Module::Starter</code> skeleton.
</p>
<pre>
$ ls -la
total 8
drwxr-xr-x 4 pjf pjf 0 Jul 4 16:59 .
drwxr-xr-x 51 pjf pjf 0 Jul 4 16:59 ..
-rw-r--r-- 1 pjf pjf 96 Jul 4 16:59 .cvsignore
-rw-r--r-- 1 pjf pjf 109 Jul 4 16:59 Changes
-rw-r--r-- 1 pjf pjf 90 Jul 4 16:59 MANIFEST
-rw-r--r-- 1 pjf pjf 183 Jul 4 16:59 Makefile.PL
-rw-r--r-- 1 pjf pjf 1378 Jul 4 16:59 README
drwxr-xr-x 3 pjf pjf 0 Jul 4 16:59 lib
drwxr-xr-x 2 pjf pjf 0 Jul 4 16:59 t</pre>
<p>
Let's look at each of these files in turn:
</p>
<dl>
<dt><strong>.cvsignore</strong></dt>
<dd>
<p>
<code>Module::Starter</code> assumes you'll be using CVS for
revision control, and provides a <em>.cvsignore</em> file with
the names of files that are auto-generated and not to be tracked
with revision control. At Perl Training Australia we use git
for new projects, and so we rename this to <em>.gitignore</em>.
</p>
<p>
(As of version 1.52, this file is now called "ignores.txt", so you can use it however you like.)
</p>
</dd>
<dt><strong>Changes</strong></dt>
<dd>
<p>
This is a human-readable file tracking module revisions and changes.
If you're going to release your code to the CPAN, it's essential for
your users to know what has changed in each release. Even if you're
only using your code internally, this is a good place to document the
history of your project.
</p>
</dd>
<dt><strong>MANIFEST</strong></dt>
<dd>
<p>
The <em>MANIFEST</em> file tracks all the files that should be
packaged when you run a <code>make tardist</code> to distribute
your module. Normally it includes your source code, any file
needed for the build system, a <em>META.yml</em> that contains
module meta-data (usually auto-generated by your build system),
tests, documentation, and anything else that you want your
end-user to have.
</p>
</dd>
<dd>
<p>
If you don't want to manually worry about adding entries to the
<em>MANIFEST</em> file yourself, most build systems (including
<code>Module::Install</code>) allow you to write <code>make
manifest</code> to auto-generate it. For this to work, you'll
want to make a <em>MANIFEST.skip</em> file which contains
filenames and regular expressions that match files which should
be excluded from the <em>MANIFEST</em>.
</p>
</dd>
<dt><strong>Makefile.PL</strong></dt>
<dd>
<p>
This is the front-end onto our build system. When we wish
to build, test, or install our module, we'll always invoke
<em>Makefile.PL</em> first:
</p>
</dd>
<dd>
<pre>
perl Makefile.PL
make
make test
make install</pre>
</dd>
<dd>
<p>
Most build systems will provide a <code>make tardist</code> target
for building a tarball of all the files in our <em>MANIFEST</em>,
a <code>make disttest</code> for making sure our tests work
with only the <em>MANIFEST</em> listed files, and <code>make
clean</code> and <code>make distclean</code> targets for clearing
up auto-generated files, including those from the build system
itself if a <code>make distclean</code> is run.
</p>
</dd>
<dd>
<p>
You'll almost certainly wish to customise your
<em>Makefile.PL</em> a little, especially if your module
has dependencies. You'll want to consult your build
system documentation for what options you can uses. For
<code>Module::Install</code> this documentation can be found at
<a href="https://metacpan.org/pod/Module::Install">https://metacpan.org</a>.
</p>
</dd>
<dt><strong>README</strong></dt>
<dd>
<p>
The <em>README</em> file should contain basic information
for someone thinking of installing your module. Mentioning
dependencies, how to build, and how to find/report bugs are all
good things to mention in the <em>README</em> file. Some systems
(including the CPAN) will extract the <em>README</em> and make
it available separate from the main distribution.
</p>
</dd>
<dt><strong>lib/</strong></dt>
<dd>
<p>
The <em>lib/</em> directory will contain your skeleton
module, and is where you'll be doing much of your work.
<code>Module::Starter</code> will have already added some skeleton
documentation, a version number, and some skeleton functions.
</p>
</dd>
<dd>
<p>
You can add more modules to the <em>lib/</em> directory if
you wish. Splitting a very large module into smaller, logical
pieces can significantly improve maintainability.
</p>
</dd>
<dt><strong>t/</strong></dt>
<dd>
<p>
The <em>t/</em> directory contains all the tests that will be
executed when you run a <code>make test</code>. By default,
<code>Module::Starter</code> will provide some simple tests
to ensure that your module compiles, that you'll filled in
relevant sections of the boilerplate documentation, and that your
documentation covers all your subroutines and doesn't contain
any syntax errors.
</p>
</dd>
<dd>
<p>
If you're new to testing in Perl, then you should
start by reading the <code>Test::Tutorial</code> at
<a href="https://metacpan.org/pod/Test::Tutorial">https://metacpan.org</a>.
</p>
</dd>
<dd>
<p>
At Perl Training Australia, we usually add a test based on
<code>Test::Perl::Critic</code> <a href="https://metacpan.org/pod/Test::Perl::Critic">https://metacpan.org</a>
to encourage good coding practices, and <code>Test::Kwalitee</code>
<a href="https://metacpan.org/pod/Test::Kwalittee">https://metacpan.org</a> to catch common
mistakes that are made in distributions.
</p>
</dd>
<dd>
<p>
Ideally when developing your module, the more tests you have,
the better. If you already have a test suite and you're wondering
which parts of your code are not being tested, you can use the
excellent <code>Devel::Cover</code> tool from
<a href="https://metacpan.org/pod/Devel::Cover">https://metacpan.org</a>.
</p>
</dd>
</dl>
<p>
<a href="http://perltraining.com.au/tips/"><b>[ Perl tips index ] </b></a><br />
<a href="http://perltraining.com.au/cgi-bin/mailman/listinfo/perl-tips"><b>[ Subscribe to Perl tips ]</b></a>
</p>
<hr />
<p>
This Perl tip and associated text is copyright Perl Training
Australia. You may freely distribute this text so long as it is
distributed in full with this Copyright notice attached.
</p>
<p>
If you have any questions please don't hesitate to contact us:
</p>
<table>
<tbody>
<tr>
<td>Email:</td>
<td>contact@perltraining.com.au</td>
</tr>
<tr>
<td>Phone:</td>
<td>03 9354 6001 (Australia)</td>
</tr>
<tr>
<td>International:</td>
<td>+61 3 9354 6001</td>
</tr>
</tbody>
</table>
<p id="copyright">
Copyright 2001-2008 Perl Training Australia. Contact us at
<a href="mailto:contact@perltraining.com.au">contact@perltraining.com.au</a>
</p>
</body>
</html>