Debian Codegraph @

upstream/mageia-cauldron/man3pm/ExtUtils::MakeMaker::FAQ.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::FAQ 3pm"
61 .TH ExtUtils::MakeMaker::FAQ 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::FAQ \- Frequently Asked Questions About MakeMaker
68 .SH DESCRIPTION
69 .IX Header "DESCRIPTION"
70 FAQs, tricks and tips for ExtUtils::MakeMaker.
71 .SS "Module Installation"
72 .IX Subsection "Module Installation"
73 .IP "How do I install a module into my home directory?" 4
74 .IX Item "How do I install a module into my home directory?"
75 If you\*(Aqre not the Perl administrator you probably don\*(Aqt have
76 permission to install a module to its default location. Ways of handling
77 this with a \fBlot\fR less manual effort on your part are perlbrew
78 and local::lib.
79 .Sp
80 Otherwise, you can install it for your own use into your home directory
81 like so:
82 .Sp
83 .Vb 2
84 \& # Non\-unix folks, replace ~ with /path/to/your/home/dir
85 \& perl Makefile.PL INSTALL_BASE=~
86 .Ve
87 .Sp
88 This will put modules into \fI~/lib/perl5\fR, man pages into \fI~/man\fR and
89 programs into \fI~/bin\fR.
90 .Sp
91 To ensure your Perl programs can see these newly installed modules,
92 set your \f(CW\*(C`PERL5LIB\*(C'\fR environment variable to \fI~/lib/perl5\fR or tell
93 each of your programs to look in that directory with the following:
94 .Sp
95 .Vb 1
96 \& use lib "$ENV{HOME}/lib/perl5";
97 .Ve
98 .Sp
99 or if \f(CW$ENV\fR{HOME} isn\*(Aqt set and you don\*(Aqt want to set it for some
100 reason, do it the long way.
101 .Sp
102 .Vb 1
103 \& use lib "/path/to/your/home/dir/lib/perl5";
104 .Ve
105 .IP "How do I get MakeMaker and Module::Build to install to the same place?" 4
106 .IX Item "How do I get MakeMaker and Module::Build to install to the same place?"
107 Module::Build, as of 0.28, supports two ways to install to the same
108 location as MakeMaker.
109 .Sp
110 We highly recommend the install_base method, its the simplest and most
111 closely approximates the expected behavior of an installation prefix.
112 .Sp
113 1) Use INSTALL_BASE / \f(CW\*(C`\-\-install_base\*(C'\fR
114 .Sp
115 MakeMaker (as of 6.31) and Module::Build (as of 0.28) both can install
116 to the same locations using the "install_base" concept. See
117 "INSTALL_BASE" in ExtUtils::MakeMaker for details. To get MM and MB to
118 install to the same location simply set INSTALL_BASE in MM and
119 \&\f(CW\*(C`\-\-install_base\*(C'\fR in MB to the same location.
120 .Sp
121 .Vb 2
122 \& perl Makefile.PL INSTALL_BASE=/whatever
123 \& perl Build.PL \-\-install_base /whatever
124 .Ve
125 .Sp
126 This works most like other language\*(Aqs behavior when you specify a
127 prefix. We recommend this method.
128 .Sp
129 2) Use PREFIX / \f(CW\*(C`\-\-prefix\*(C'\fR
130 .Sp
131 Module::Build 0.28 added support for \f(CW\*(C`\-\-prefix\*(C'\fR which works like
132 MakeMaker\*(Aqs PREFIX.
133 .Sp
134 .Vb 2
135 \& perl Makefile.PL PREFIX=/whatever
136 \& perl Build.PL \-\-prefix /whatever
137 .Ve
138 .Sp
139 We highly discourage this method. It should only be used if you know
140 what you\*(Aqre doing and specifically need the PREFIX behavior. The
141 PREFIX algorithm is complicated and focused on matching the system
142 installation.
143 .IP "How do I keep from installing man pages?" 4
144 .IX Item "How do I keep from installing man pages?"
145 Recent versions of MakeMaker will only install man pages on Unix\-like
146 operating systems by default. To generate manpages on non\-Unix operating
147 systems, make the "manifypods" target.
148 .Sp
149 For an individual module:
150 .Sp
151 .Vb 1
152 \& perl Makefile.PL INSTALLMAN1DIR=none INSTALLMAN3DIR=none
153 .Ve
154 .Sp
155 If you want to suppress man page installation for all modules you have
156 to reconfigure Perl and tell it \*(Aqnone\*(Aq when it asks where to install
157 man pages.
158 .IP "How do I use a module without installing it?" 4
159 .IX Item "How do I use a module without installing it?"
160 Two ways. One is to build the module normally...
161 .Sp
162 .Vb 3
163 \& perl Makefile.PL
164 \& make
165 \& make test
166 .Ve
167 .Sp
168 \&...and then use blib to point Perl at the built but uninstalled module:
169 .Sp
170 .Vb 2
171 \& perl \-Mblib script.pl
172 \& perl \-Mblib \-e \*(Aq...\*(Aq
173 .Ve
174 .Sp
175 The other is to install the module in a temporary location.
176 .Sp
177 .Vb 4
178 \& perl Makefile.PL INSTALL_BASE=~/tmp
179 \& make
180 \& make test
181 \& make install
182 .Ve
183 .Sp
184 And then set PERL5LIB to \fI~/tmp/lib/perl5\fR. This works well when you
185 have multiple modules to work with. It also ensures that the module
186 goes through its full installation process which may modify it.
187 Again, local::lib may assist you here.
188 .IP "How can I organize tests into subdirectories and have them run?" 4
189 .IX Item "How can I organize tests into subdirectories and have them run?"
190 Let\*(Aqs take the following test directory structure:
191 .Sp
192 .Vb 3
193 \& t/foo/sometest.t
194 \& t/bar/othertest.t
195 \& t/bar/baz/anothertest.t
196 .Ve
197 .Sp
198 Now, inside of the \f(CWWriteMakefile()\fR function in your \fIMakefile.PL\fR, specify
199 where your tests are located with the \f(CW\*(C`test\*(C'\fR directive:
200 .Sp
201 .Vb 1
202 \& test => {TESTS => \*(Aqt/*.t t/*/*.t t/*/*/*.t\*(Aq}
203 .Ve
204 .Sp
205 The first entry in the string will run all tests in the top\-level \fIt/\fR
206 directory. The second will run all test files located in any subdirectory under
207 \&\fIt/\fR. The third, runs all test files within any subdirectory within any other
208 subdirectory located under \fIt/\fR.
209 .Sp
210 Note that you do not have to use wildcards. You can specify explicitly which
211 subdirectories to run tests in:
212 .Sp
213 .Vb 1
214 \& test => {TESTS => \*(Aqt/*.t t/foo/*.t t/bar/baz/*.t\*(Aq}
215 .Ve
216 .IP "PREFIX vs INSTALL_BASE from Module::Build::Cookbook" 4
217 .IX Item "PREFIX vs INSTALL_BASE from Module::Build::Cookbook"
218 The behavior of PREFIX is complicated and depends closely on how your
219 Perl is configured. The resulting installation locations will vary
220 from machine to machine and even different installations of Perl on the
221 same machine. Because of this, its difficult to document where prefix
222 will place your modules.
223 .Sp
224 In contrast, INSTALL_BASE has predictable, easy to explain installation
225 locations. Now that Module::Build and MakeMaker both have INSTALL_BASE
226 there is little reason to use PREFIX other than to preserve your existing
227 installation locations. If you are starting a fresh Perl installation we
228 encourage you to use INSTALL_BASE. If you have an existing installation
229 installed via PREFIX, consider moving it to an installation structure
230 matching INSTALL_BASE and using that instead.
231 .ie n .IP "Generating *.pm files with substitutions eg of $VERSION" 4
232 .el .IP "Generating *.pm files with substitutions eg of \f(CW$VERSION\fR" 4
233 .IX Item "Generating *.pm files with substitutions eg of $VERSION"
234 If you want to configure your module files for local conditions, or to
235 automatically insert a version number, you can use EUMM\*(Aqs \f(CW\*(C`PL_FILES\*(C'\fR
236 capability, where it will automatically run each \fI*.PL\fR it finds to
237 generate its basename. For instance:
238 .Sp
239 .Vb 10
240 \& # Makefile.PL:
241 \& require \*(Aqcommon.pl\*(Aq;
242 \& my $version = get_version();
243 \& my @pms = qw(Foo.pm);
244 \& WriteMakefile(
245 \& NAME => \*(AqFoo\*(Aq,
246 \& VERSION => $version,
247 \& PM => { map { ($_ => "\e$(INST_LIB)/$_") } @pms },
248 \& clean => { FILES => join \*(Aq \*(Aq, @pms },
249 \& );
250 \&
251 \& # common.pl:
252 \& sub get_version { \*(Aq0.04\*(Aq }
253 \& sub process { my $v = get_version(); s/_\|_VERSION_\|_/$v/g; }
254 \& 1;
255 \&
256 \& # Foo.pm.PL:
257 \& require \*(Aqcommon.pl\*(Aq;
258 \& $_ = join \*(Aq\*(Aq, <DATA>;
259 \& process();
260 \& my $file = shift;
261 \& open my $fh, \*(Aq>\*(Aq, $file or die "$file: $!";
262 \& print $fh $_;
263 \& _\|_DATA_\|_
264 \& package Foo;
265 \& our $VERSION = \*(Aq_\|_VERSION_\|_\*(Aq;
266 \& 1;
267 .Ve
268 .Sp
269 You may notice that \f(CW\*(C`PL_FILES\*(C'\fR is not specified above, since the default
270 of mapping each .PL file to its basename works well.
271 .Sp
272 If the generated module were architecture\-specific, you could replace
273 \&\f(CW\*(C`$(INST_LIB)\*(C'\fR above with \f(CW\*(C`$(INST_ARCHLIB)\*(C'\fR, although if you locate
274 modules under \fIlib\fR, that would involve ensuring any \f(CW\*(C`lib/\*(C'\fR in front
275 of the module location were removed.
276 .SS "Common errors and problems"
277 .IX Subsection "Common errors and problems"
278 .IP """No rule to make target \`/usr/lib/perl5/CORE/config.h\*(Aq, needed by \`Makefile\*(Aq""" 4
279 .IX Item """No rule to make target `/usr/lib/perl5/CORE/config.h', needed by `Makefile'"""
280 Just what it says, you\*(Aqre missing that file. MakeMaker uses it to
281 determine if perl has been rebuilt since the Makefile was made. It\*(Aqs
282 a bit of a bug that it halts installation.
283 .Sp
284 Some operating systems don\*(Aqt ship the CORE directory with their base
285 perl install. To solve the problem, you likely need to install a perl
286 development package such as perl\-devel (CentOS, Fedora and other
287 Redhat systems) or perl (Ubuntu and other Debian systems).
288 .SS "Philosophy and History"
289 .IX Subsection "Philosophy and History"
290 .IP "Why not just use <insert other build config tool here>?" 4
291 .IX Item "Why not just use <insert other build config tool here>?"
292 Why did MakeMaker reinvent the build configuration wheel? Why not
293 just use autoconf or automake or ppm or Ant or ...
294 .Sp
295 There are many reasons, but the major one is cross\-platform
296 compatibility.
297 .Sp
298 Perl is one of the most ported pieces of software ever. It works on
299 operating systems I\*(Aqve never even heard of (see perlport for details).
300 It needs a build tool that can work on all those platforms and with
301 any wacky C compilers and linkers they might have.
302 .Sp
303 No such build tool exists. Even make itself has wildly different
304 dialects. So we have to build our own.
305 .IP "What is Module::Build and how does it relate to MakeMaker?" 4
306 .IX Item "What is Module::Build and how does it relate to MakeMaker?"
307 Module::Build is a project by Ken Williams to supplant MakeMaker.
308 Its primary advantages are:
309 .RS 4
310 .IP \(bu 8
311 pure perl. no make, no shell commands
312 .IP \(bu 8
313 easier to customize
314 .IP \(bu 8
315 cleaner internals
316 .IP \(bu 8
317 less cruft
318 .RE
319 .RS 4
320 .Sp
321 Module::Build was long the official heir apparent to MakeMaker. The
322 rate of both its development and adoption has slowed in recent years,
323 though, and it is unclear what the future holds for it. That said,
324 Module::Build set the stage for \fIsomething\fR to become the heir to
325 MakeMaker. MakeMaker\*(Aqs maintainers have long said that it is a dead
326 end and should be kept functioning, while being cautious about extending
327 with new features.
328 .RE
329 .SS "Module Writing"
330 .IX Subsection "Module Writing"
331 .ie n .IP "How do I keep my $VERSION up to date without resetting it manually?" 4
332 .el .IP "How do I keep my \f(CW$VERSION\fR up to date without resetting it manually?" 4
333 .IX Item "How do I keep my $VERSION up to date without resetting it manually?"
334 Often you want to manually set the \f(CW$VERSION\fR in the main module
335 distribution because this is the version that everybody sees on CPAN
336 and maybe you want to customize it a bit. But for all the other
337 modules in your dist, \f(CW$VERSION\fR is really just bookkeeping and all that\*(Aqs
338 important is it goes up every time the module is changed. Doing this
339 by hand is a pain and you often forget.
340 .Sp
341 Probably the easiest way to do this is using \fIperl\-reversion\fR in
342 Perl::Version:
343 .Sp
344 .Vb 1
345 \& perl\-reversion \-bump
346 .Ve
347 .Sp
348 If your version control system supports revision numbers (git doesn\*(Aqt
349 easily), the simplest way to do it automatically is to use its revision
350 number (you are using version control, right?).
351 .Sp
352 In CVS, RCS and SVN you use \f(CW$Revision\fR$ (see the documentation of your
353 version control system for details). Every time the file is checked
354 in the \f(CW$Revision\fR$ will be updated, updating your \f(CW$VERSION\fR.
355 .Sp
356 SVN uses a simple integer for \f(CW$Revision\fR$ so you can adapt it for your
357 \&\f(CW$VERSION\fR like so:
358 .Sp
359 .Vb 1
360 \& ($VERSION) = q$Revision$ =~ /(\ed+)/;
361 .Ve
362 .Sp
363 In CVS and RCS version 1.9 is followed by 1.10. Since CPAN compares
364 version numbers numerically we use a \fBsprintf()\fR to convert 1.9 to 1.009
365 and 1.10 to 1.010 which compare properly.
366 .Sp
367 .Vb 1
368 \& $VERSION = sprintf "%d.%03d", q$Revision$ =~ /(\ed+)\e.(\ed+)/g;
369 .Ve
370 .Sp
371 If branches are involved (ie. \f(CW$Revision:\fR 1.5.3.4$) it\*(Aqs a little more
372 complicated.
373 .Sp
374 .Vb 2
375 \& # must be all on one line or MakeMaker will get confused.
376 \& $VERSION = do { my @r = (q$Revision$ =~ /\ed+/g); sprintf "%d."."%03d" x $#r, @r };
377 .Ve
378 .Sp
379 In SVN, \f(CW$Revision\fR$ should be the same for every file in the project so
380 they would all have the same \f(CW$VERSION\fR. CVS and RCS have a different
381 \&\f(CW$Revision\fR$ per file so each file will have a different \f(CW$VERSION\fR.
382 Distributed version control systems, such as SVK, may have a different
383 \&\f(CW$Revision\fR$ based on who checks out the file, leading to a different \f(CW$VERSION\fR
384 on each machine! Finally, some distributed version control systems, such
385 as darcs, have no concept of revision number at all.
386 .IP "What\*(Aqs this \fIMETA.yml\fR thing and how did it get in my \fIMANIFEST\fR?!" 4
387 .IX Item "What's this META.yml thing and how did it get in my MANIFEST?!"
388 \&\fIMETA.yml\fR is a module meta\-data file pioneered by Module::Build and
389 automatically generated as part of the \*(Aqdistdir\*(Aq target (and thus
390 \&\*(Aqdist\*(Aq). See "Module Meta\-Data" in ExtUtils::MakeMaker.
391 .Sp
392 To shut off its generation, pass the \f(CW\*(C`NO_META\*(C'\fR flag to \f(CWWriteMakefile()\fR.
393 .IP "How do I delete everything not in my \fIMANIFEST\fR?" 4
394 .IX Item "How do I delete everything not in my MANIFEST?"
395 Some folks are surprised that \f(CW\*(C`make distclean\*(C'\fR does not delete
396 everything not listed in their MANIFEST (thus making a clean
397 distribution) but only tells them what they need to delete. This is
398 done because it is considered too dangerous. While developing your
399 module you might write a new file, not add it to the MANIFEST, then
400 run a \f(CW\*(C`distclean\*(C'\fR and be sad because your new work was deleted.
401 .Sp
402 If you really want to do this, you can use
403 \&\f(CWExtUtils::Manifest::manifind()\fR to read the MANIFEST and File::Find
404 to delete the files. But you have to be careful. Here\*(Aqs a script to
405 do that. Use at your own risk. Have fun blowing holes in your foot.
406 .Sp
407 .Vb 1
408 \& #!/usr/bin/perl \-w
409 \&
410 \& use strict;
411 \&
412 \& use File::Spec;
413 \& use File::Find;
414 \& use ExtUtils::Manifest qw(maniread);
415 \&
416 \& my %manifest = map {( $_ => 1 )}
417 \& grep { File::Spec\->canonpath($_) }
418 \& keys %{ maniread() };
419 \&
420 \& if( !keys %manifest ) {
421 \& print "No files found in MANIFEST. Stopping.\en";
422 \& exit;
423 \& }
424 \&
425 \& find({
426 \& wanted => sub {
427 \& my $path = File::Spec\->canonpath($_);
428 \&
429 \& return unless \-f $path;
430 \& return if exists $manifest{ $path };
431 \&
432 \& print "unlink $path\en";
433 \& unlink $path;
434 \& },
435 \& no_chdir => 1
436 \& },
437 \& "."
438 \& );
439 .Ve
440 .IP "Which tar should I use on Windows?" 4
441 .IX Item "Which tar should I use on Windows?"
442 We recommend ptar from Archive::Tar not older than 1.66 with \*(Aq\-C\*(Aq option.
443 .IP "Which zip should I use on Windows for \*(Aq[ndg]make zipdist\*(Aq?" 4
444 .IX Item "Which zip should I use on Windows for '[ndg]make zipdist'?"
445 We recommend InfoZIP: <http://www.info\-zip.org/Zip.html>
446 .SS XS
447 .IX Subsection "XS"
448 .IP "How do I prevent ""object version X.XX does not match bootstrap parameter Y.YY"" errors?" 4
449 .IX Item "How do I prevent ""object version X.XX does not match bootstrap parameter Y.YY"" errors?"
450 XS code is very sensitive to the module version number and will
451 complain if the version number in your Perl module doesn\*(Aqt match. If
452 you change your module\*(Aqs version # without rerunning Makefile.PL the old
453 version number will remain in the Makefile, causing the XS code to be built
454 with the wrong number.
455 .Sp
456 To avoid this, you can force the Makefile to be rebuilt whenever you
457 change the module containing the version number by adding this to your
458 \&\fBWriteMakefile()\fR arguments.
459 .Sp
460 .Vb 1
461 \& depend => { \*(Aq$(FIRST_MAKEFILE)\*(Aq => \*(Aq$(VERSION_FROM)\*(Aq }
462 .Ve
463 .IP "How do I make two or more XS files coexist in the same directory?" 4
464 .IX Item "How do I make two or more XS files coexist in the same directory?"
465 Sometimes you need to have two and more XS files in the same package.
466 There are three ways: \f(CW\*(C`XSMULTI\*(C'\fR, separate directories, and bootstrapping
467 one XS from another.
468 .RS 4
469 .IP XSMULTI 8
470 .IX Item "XSMULTI"
471 Structure your modules so they are all located under \fIlib\fR, such that
472 \&\f(CW\*(C`Foo::Bar\*(C'\fR is in \fIlib/Foo/Bar.pm\fR and \fIlib/Foo/Bar.xs\fR, etc. Have your
473 top\-level \f(CW\*(C`WriteMakefile\*(C'\fR set the variable \f(CW\*(C`XSMULTI\*(C'\fR to a true value.
474 .Sp
475 Er, that\*(Aqs it.
476 .IP "Separate directories" 8
477 .IX Item "Separate directories"
478 Put each XS files into separate directories, each with their own
479 \&\fIMakefile.PL\fR. Make sure each of those \fIMakefile.PL\fRs has the correct
480 \&\f(CW\*(C`CFLAGS\*(C'\fR, \f(CW\*(C`INC\*(C'\fR, \f(CW\*(C`LIBS\*(C'\fR etc. You will need to make sure the top\-level
481 \&\fIMakefile.PL\fR refers to each of these using \f(CW\*(C`DIR\*(C'\fR.
482 .IP Bootstrapping 8
483 .IX Item "Bootstrapping"
484 Let\*(Aqs assume that we have a package \f(CW\*(C`Cool::Foo\*(C'\fR, which includes
485 \&\f(CW\*(C`Cool::Foo\*(C'\fR and \f(CW\*(C`Cool::Bar\*(C'\fR modules each having a separate XS
486 file. First we use the following \fIMakefile.PL\fR:
487 .Sp
488 .Vb 1
489 \& use ExtUtils::MakeMaker;
490 \&
491 \& WriteMakefile(
492 \& NAME => \*(AqCool::Foo\*(Aq,
493 \& VERSION_FROM => \*(AqFoo.pm\*(Aq,
494 \& OBJECT => q/$(O_FILES)/,
495 \& # ... other attrs ...
496 \& );
497 .Ve
498 .Sp
499 Notice the \f(CW\*(C`OBJECT\*(C'\fR attribute. MakeMaker generates the following
500 variables in \fIMakefile\fR:
501 .Sp
502 .Vb 7
503 \& # Handy lists of source code files:
504 \& XS_FILES= Bar.xs \e
505 \& Foo.xs
506 \& C_FILES = Bar.c \e
507 \& Foo.c
508 \& O_FILES = Bar.o \e
509 \& Foo.o
510 .Ve
511 .Sp
512 Therefore we can use the \f(CW\*(C`O_FILES\*(C'\fR variable to tell MakeMaker to use
513 these objects into the shared library.
514 .Sp
515 That\*(Aqs pretty much it. Now write \fIFoo.pm\fR and \fIFoo.xs\fR, \fIBar.pm\fR
516 and \fIBar.xs\fR, where \fIFoo.pm\fR bootstraps the shared library and
517 \&\fIBar.pm\fR simply loading \fIFoo.pm\fR.
518 .Sp
519 The only issue left is to how to bootstrap \fIBar.xs\fR. This is done
520 from \fIFoo.xs\fR:
521 .Sp
522 .Vb 1
523 \& MODULE = Cool::Foo PACKAGE = Cool::Foo
524 \&
525 \& BOOT:
526 \& # boot the second XS file
527 \& boot_Cool_\|_Bar(aTHX_ cv);
528 .Ve
529 .Sp
530 If you have more than two files, this is the place where you should
531 boot extra XS files from.
532 .Sp
533 The following four files sum up all the details discussed so far.
534 .Sp
535 .Vb 3
536 \& Foo.pm:
537 \& \-\-\-\-\-\-\-
538 \& package Cool::Foo;
539 \&
540 \& require DynaLoader;
541 \&
542 \& our @ISA = qw(DynaLoader);
543 \& our $VERSION = \*(Aq0.01\*(Aq;
544 \& bootstrap Cool::Foo $VERSION;
545 \&
546 \& 1;
547 \&
548 \& Bar.pm:
549 \& \-\-\-\-\-\-\-
550 \& package Cool::Bar;
551 \&
552 \& use Cool::Foo; # bootstraps Bar.xs
553 \&
554 \& 1;
555 \&
556 \& Foo.xs:
557 \& \-\-\-\-\-\-\-
558 \& #include "EXTERN.h"
559 \& #include "perl.h"
560 \& #include "XSUB.h"
561 \&
562 \& MODULE = Cool::Foo PACKAGE = Cool::Foo
563 \&
564 \& BOOT:
565 \& # boot the second XS file
566 \& boot_Cool_\|_Bar(aTHX_ cv);
567 \&
568 \& MODULE = Cool::Foo PACKAGE = Cool::Foo PREFIX = cool_foo_
569 \&
570 \& void
571 \& cool_foo_perl_rules()
572 \&
573 \& CODE:
574 \& fprintf(stderr, "Cool::Foo says: Perl Rules\en");
575 \&
576 \& Bar.xs:
577 \& \-\-\-\-\-\-\-
578 \& #include "EXTERN.h"
579 \& #include "perl.h"
580 \& #include "XSUB.h"
581 \&
582 \& MODULE = Cool::Bar PACKAGE = Cool::Bar PREFIX = cool_bar_
583 \&
584 \& void
585 \& cool_bar_perl_rules()
586 \&
587 \& CODE:
588 \& fprintf(stderr, "Cool::Bar says: Perl Rules\en");
589 .Ve
590 .Sp
591 And of course a very basic test:
592 .Sp
593 .Vb 8
594 \& t/cool.t:
595 \& \-\-\-\-\-\-\-\-
596 \& use Test::More tests => 1;
597 \& use Cool::Foo;
598 \& use Cool::Bar;
599 \& Cool::Foo::perl_rules();
600 \& Cool::Bar::perl_rules();
601 \& ok 1;
602 .Ve
603 .Sp
604 This tip has been brought to you by Nick Ing\-Simmons and Stas Bekman.
605 .Sp
606 An alternative way to achieve this can be seen in Gtk2::CodeGen
607 and Glib::CodeGen.
608 .RE
609 .RS 4
610 .RE
611 .SH DESIGN
612 .IX Header "DESIGN"
613 .SS "MakeMaker object hierarchy (simplified)"
614 .IX Subsection "MakeMaker object hierarchy (simplified)"
615 What most people need to know (superclasses on top.)
616 .PP
617 .Vb 9
618 \& ExtUtils::MM_Any
619 \& |
620 \& ExtUtils::MM_Unix
621 \& |
622 \& ExtUtils::MM_{Current OS}
623 \& |
624 \& ExtUtils::MakeMaker
625 \& |
626 \& MY
627 .Ve
628 .PP
629 The object actually used is of the class MY which allows you to
630 override bits of MakeMaker inside your Makefile.PL by declaring
631 \&\fBMY::foo()\fR methods.
632 .SS "MakeMaker object hierarchy (real)"
633 .IX Subsection "MakeMaker object hierarchy (real)"
634 Here\*(Aqs how it really works:
635 .PP
636 .Vb 10
637 \& ExtUtils::MM_Any
638 \& |
639 \& ExtUtils::MM_Unix
640 \& |
641 \& ExtUtils::Liblist::Kid ExtUtils::MM_{Current OS} (if necessary)
642 \& | |
643 \& ExtUtils::Liblist ExtUtils::MakeMaker |
644 \& | | |
645 \& | | |\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
646 \& ExtUtils::MM
647 \& | |
648 \& ExtUtils::MY MM (created by ExtUtils::MM)
649 \& | |
650 \& MY (created by ExtUtils::MY) |
651 \& . |
652 \& (mixin) |
653 \& . |
654 \& PACK### (created each call to ExtUtils::MakeMaker\->new)
655 .Ve
656 .PP
657 NOTE: Yes, this is a mess. See
658 <http://archive.develooper.com/[email protected]/msg00134.html>
659 for some history.
660 .PP
661 NOTE: When ExtUtils::MM is loaded it chooses a superclass for MM from
662 amongst the ExtUtils::MM_* modules based on the current operating
663 system.
664 .PP
665 NOTE: ExtUtils::MM_{Current OS} represents one of the ExtUtils::MM_*
666 modules except ExtUtils::MM_Any chosen based on your operating system.
667 .PP
668 NOTE: The main object used by MakeMaker is a PACK### object, *not*
669 ExtUtils::MakeMaker. It is, effectively, a subclass of MY,
670 ExtUtils::MakeMaker, ExtUtils::Liblist and ExtUtils::MM_{Current OS}
671 .PP
672 NOTE: The methods in MY are simply copied into PACK### rather
673 than MY being a superclass of PACK###. I don\*(Aqt remember the rationale.
674 .PP
675 NOTE: ExtUtils::Liblist should be removed from the inheritance hiearchy
676 and simply be called as functions.
677 .PP
678 NOTE: Modules like File::Spec and Exporter have been omitted for clarity.
679 .SS "The MM_* hierarchy"
680 .IX Subsection "The MM_* hierarchy"
681 .Vb 9
682 \& MM_Win95 MM_NW5
683 \& \e /
684 \& MM_BeOS MM_Cygwin MM_OS2 MM_VMS MM_Win32 MM_DOS MM_UWIN
685 \& \e | | | / / /
686 \& \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
687 \& | |
688 \& MM_Unix |
689 \& | |
690 \& MM_Any
691 .Ve
692 .PP
693 NOTE: Each direct MM_Unix subclass is also an
694 MM_Any subclass. This
695 is a temporary hack because MM_Unix overrides some MM_Any methods with
696 Unix specific code. It allows the non\-Unix modules to see the
697 original MM_Any implementations.
698 .PP
699 NOTE: Modules like File::Spec and Exporter have been omitted for clarity.
700 .SH PATCHING
701 .IX Header "PATCHING"
702 If you have a question you\*(Aqd like to see added to the FAQ (whether or
703 not you have the answer) please either:
704 .IP \(bu 2
705 make a pull request on the MakeMaker github repository
706 .IP \(bu 2
707 raise a issue on the MakeMaker github repository
708 .IP \(bu 2
709 file an RT ticket
710 .IP \(bu 2
711 email [email protected]
712 .SH AUTHOR
713 .IX Header "AUTHOR"
714 The denizens of [email protected].
715 .SH "SEE ALSO"
716 .IX Header "SEE ALSO"
717 ExtUtils::MakeMaker