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