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