Debian Codegraph @

upstream/mageia-cauldron/man3pm/ExtUtils::MakeMaker::Tutorial.3pm

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 "ExtUtils::MakeMaker::Tutorial 3pm"
61 .TH ExtUtils::MakeMaker::Tutorial 3pm 2025-06-24 "perl v5.42.0" "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 ExtUtils::MakeMaker::Tutorial \- Writing a module with MakeMaker
68 .SH SYNOPSIS
69 .IX Header "SYNOPSIS"
70 .Vb 1
71 \& use ExtUtils::MakeMaker;
72 \&
73 \& WriteMakefile(
74 \& NAME => \*(AqYour::Module\*(Aq,
75 \& VERSION_FROM => \*(Aqlib/Your/Module.pm\*(Aq
76 \& );
77 .Ve
78 .SH DESCRIPTION
79 .IX Header "DESCRIPTION"
80 This is a short tutorial on writing a simple module with MakeMaker.
81 It\*(Aqs really not that hard.
82 .SS "The Mantra"
83 .IX Subsection "The Mantra"
84 MakeMaker modules are installed using this simple mantra
85 .PP
86 .Vb 4
87 \& perl Makefile.PL
88 \& make
89 \& make test
90 \& make install
91 .Ve
92 .PP
93 There are lots more commands and options, but the above will do it.
94 .SS "The Layout"
95 .IX Subsection "The Layout"
96 The basic files in a module look something like this.
97 .PP
98 .Vb 3
99 \& Makefile.PL
100 \& MANIFEST
101 \& lib/Your/Module.pm
102 .Ve
103 .PP
104 That\*(Aqs all that\*(Aqs strictly necessary. There\*(Aqs additional files you might
105 want:
106 .PP
107 .Vb 8
108 \& lib/Your/Other/Module.pm
109 \& t/some_test.t
110 \& t/some_other_test.t
111 \& Changes
112 \& README
113 \& INSTALL
114 \& MANIFEST.SKIP
115 \& bin/some_program
116 .Ve
117 .IP Makefile.PL 4
118 .IX Item "Makefile.PL"
119 When you run Makefile.PL, it makes a Makefile. That\*(Aqs the whole point of
120 MakeMaker. The Makefile.PL is a simple program which loads
121 ExtUtils::MakeMaker and runs the \fBWriteMakefile()\fR function to generate a
122 Makefile.
123 .Sp
124 Here\*(Aqs an example of what you need for a simple module:
125 .Sp
126 .Vb 1
127 \& use ExtUtils::MakeMaker;
128 \&
129 \& WriteMakefile(
130 \& NAME => \*(AqYour::Module\*(Aq,
131 \& VERSION_FROM => \*(Aqlib/Your/Module.pm\*(Aq
132 \& );
133 .Ve
134 .Sp
135 NAME is the top\-level namespace of your module. VERSION_FROM is the file
136 which contains the \f(CW$VERSION\fR variable for the entire distribution. Typically
137 this is the same as your top\-level module.
138 .IP MANIFEST 4
139 .IX Item "MANIFEST"
140 A simple listing of all the files in your distribution.
141 .Sp
142 .Vb 3
143 \& Makefile.PL
144 \& MANIFEST
145 \& lib/Your/Module.pm
146 .Ve
147 .Sp
148 File paths in a MANIFEST always use Unix conventions (ie. /) even if you\*(Aqre
149 not on Unix.
150 .Sp
151 You can write this by hand or generate it with \*(Aqmake manifest\*(Aq.
152 .Sp
153 See ExtUtils::Manifest for more details.
154 .IP lib/ 4
155 .IX Item "lib/"
156 This is the directory where the .pm and .pod files you wish to have
157 installed go. They are laid out according to namespace. So Foo::Bar
158 is \fIlib/Foo/Bar.pm\fR.
159 .IP t/ 4
160 .IX Item "t/"
161 Tests for your modules go here. Each test filename ends with a .t.
162 So \fIt/foo.t\fR \*(Aqmake test\*(Aq will run these tests.
163 .Sp
164 Typically, the \fIt/\fR test directory is flat, with all test files located
165 directly within it. However, you can nest tests within subdirectories, for
166 example:
167 .Sp
168 .Vb 1
169 \& t/foo/subdir_test.t
170 .Ve
171 .Sp
172 To do this, you need to inform \f(CWWriteMakefile()\fR in your \fIMakefile.PL\fR file
173 in the following fashion:
174 .Sp
175 .Vb 1
176 \& test => {TESTS => \*(Aqt/*.t t/*/*.t\*(Aq}
177 .Ve
178 .Sp
179 That will run all tests in \fIt/\fR, as well as all tests in all subdirectories
180 that reside under \fIt/\fR. You can nest as deeply as makes sense for your project.
181 Simply add another entry in the test location string. For example, to test:
182 .Sp
183 .Vb 1
184 \& t/foo/bar/subdir_test.t
185 .Ve
186 .Sp
187 You would use the following \f(CW\*(C`test\*(C'\fR directive:
188 .Sp
189 .Vb 1
190 \& test => {TESTS => \*(Aqt/*.t t/*/*/*.t\*(Aq}
191 .Ve
192 .Sp
193 Note that in the above example, tests in the first subdirectory will not be
194 run. To run all tests in the intermediary subdirectory preceding the one
195 the test files are in, you need to explicitly note it:
196 .Sp
197 .Vb 1
198 \& test => {TESTS => \*(Aqt/*.t t/*/*.t t/*/*/*.t\*(Aq}
199 .Ve
200 .Sp
201 You don\*(Aqt need to specify wildcards if you only want to test within specific
202 subdirectories. The following example will only run tests in \fIt/foo\fR:
203 .Sp
204 .Vb 1
205 \& test => {TESTS => \*(Aqt/foo/*.t\*(Aq}
206 .Ve
207 .Sp
208 Tests are run from the top level of your distribution. So inside a test
209 you would refer to ./lib to enter the lib directory, for example.
210 .IP Changes 4
211 .IX Item "Changes"
212 A log of changes you\*(Aqve made to this module. The layout is free\-form.
213 Here\*(Aqs an example:
214 .Sp
215 .Vb 3
216 \& 1.01 Fri Apr 11 00:21:25 PDT 2003
217 \& \- thing() does some stuff now
218 \& \- fixed the wiggy bug in withit()
219 \&
220 \& 1.00 Mon Apr 7 00:57:15 PDT 2003
221 \& \- "Rain of Frogs" now supported
222 .Ve
223 .IP README 4
224 .IX Item "README"
225 A short description of your module, what it does, why someone would use it
226 and its limitations. CPAN automatically pulls your README file out of
227 the archive and makes it available to CPAN users, it is the first thing
228 they will read to decide if your module is right for them.
229 .IP INSTALL 4
230 .IX Item "INSTALL"
231 Instructions on how to install your module along with any dependencies.
232 Suggested information to include here:
233 .Sp
234 .Vb 3
235 \& any extra modules required for use
236 \& the minimum version of Perl required
237 \& if only works on certain operating systems
238 .Ve
239 .IP MANIFEST.SKIP 4
240 .IX Item "MANIFEST.SKIP"
241 A file full of regular expressions to exclude when using \*(Aqmake
242 manifest\*(Aq to generate the MANIFEST. These regular expressions
243 are checked against each file path found in the distribution (so
244 you\*(Aqre matching against "t/foo.t" not "foo.t").
245 .Sp
246 Here\*(Aqs a sample:
247 .Sp
248 .Vb 3
249 \& ~$ # ignore emacs and vim backup files
250 \& .bak$ # ignore manual backups
251 \& \e# # ignore CVS old revision files and emacs temp files
252 .Ve
253 .Sp
254 Since # can be used for comments, # must be escaped.
255 .Sp
256 MakeMaker comes with a default MANIFEST.SKIP to avoid things like
257 version control directories and backup files. Specifying your own
258 will override this default.
259 .IP bin/ 4
260 .IX Item "bin/"
261 .SH "SEE ALSO"
262 .IX Header "SEE ALSO"
263 perlmodstyle gives stylistic help writing a module.
264 .PP
265 perlnewmod gives more information about how to write a module.
266 .PP
267 There are modules to help you through the process of writing a module:
268 ExtUtils::ModuleMaker, Module::Starter, Minilla::Tutorial,
269 Dist::Milla::Tutorial, Dist::Zilla::Starter