Debian Codegraph @

upstream/debian-unstable/man3/ExtUtils::MakeMaker::FAQ.3perl

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