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.
76 For an individual module:
78 perl Makefile.PL INSTALLMAN1DIR=none INSTALLMAN3DIR=none
80 If you want to suppress man page installation for all modules you
82 have to reconfigure Perl and tell it 'none' when it asks where to
83 install man pages.
84 How do I use a module without installing it?
86 Two ways. One is to build the module normally...
87 perl Makefile.PL
89 make
90 make test
91 ...and then use blib to point Perl at the built but uninstalled
93 module:
94 perl -Mblib script.pl
96 perl -Mblib -e '...'
97 The other is to install the module in a temporary location.
99 perl Makefile.PL INSTALL_BASE=~/tmp
101 make
102 make test
103 make install
104 And then set PERL5LIB to ~/tmp/lib/perl5. This works well when you
106 have multiple modules to work with. It also ensures that the
107 module goes through its full installation process which may modify
108 it. Again, local::lib may assist you here.
109 How can I organize tests into subdirectories and have them run?
111 Let's take the following test directory structure:
112 t/foo/sometest.t
114 t/bar/othertest.t
115 t/bar/baz/anothertest.t
116 Now, inside of the "WriteMakeFile()" function in your Makefile.PL,
118 specify where your tests are located with the "test" directive:
119 test => {TESTS => 't/*.t t/*/*.t t/*/*/*.t'}
121 The first entry in the string will run all tests in the top-level
123 t/ directory. The second will run all test files located in any
124 subdirectory under t/. The third, runs all test files within any
125 subdirectory within any other subdirectory located under t/.
126 Note that you do not have to use wildcards. You can specify
128 explicitly which subdirectories to run tests in:
129 test => {TESTS => 't/*.t t/foo/*.t t/bar/baz/*.t'}
131 PREFIX vs INSTALL_BASE from Module::Build::Cookbook
133 The behavior of PREFIX is complicated and depends closely on how
134 your Perl is configured. The resulting installation locations will
135 vary from machine to machine and even different installations of
136 Perl on the same machine. Because of this, its difficult to
137 document where prefix will place your modules.
138 In contrast, INSTALL_BASE has predictable, easy to explain
140 installation locations. Now that Module::Build and MakeMaker both
141 have INSTALL_BASE there is little reason to use PREFIX other than
142 to preserve your existing installation locations. If you are
143 starting a fresh Perl installation we encourage you to use
144 INSTALL_BASE. If you have an existing installation installed via
145 PREFIX, consider moving it to an installation structure matching
146 INSTALL_BASE and using that instead.
147 Generating *.pm files with substitutions eg of $VERSION
149 If you want to configure your module files for local conditions, or
150 to automatically insert a version number, you can use EUMM's
151 "PL_FILES" capability, where it will automatically run each *.PL it
152 finds to generate its basename. For instance:
153 # Makefile.PL:
155 require 'common.pl';
156 my $version = get_version();
157 my @pms = qw(Foo.pm);
158 WriteMakefile(
159 NAME => 'Foo',
160 VERSION => $version,
161 PM => { map { ($_ => "\$(INST_LIB)/$_") } @pms },
162 clean => { FILES => join ' ', @pms },
163 );
164 # common.pl:
166 sub get_version { '0.04' }
167 sub process { my $v = get_version(); s/__VERSION__/$v/g; }
168 1;
169 # Foo.pm.PL:
171 require 'common.pl';
172 $_ = join '', <DATA>;
173 process();
174 my $file = shift;
175 open my $fh, '>', $file or die "$file: $!";
176 print $fh $_;
177 __DATA__
178 package Foo;
179 our $VERSION = '__VERSION__';
180 1;
181 You may notice that "PL_FILES" is not specified above, since the
183 default of mapping each .PL file to its basename works well.
184 If the generated module were architecture-specific, you could
186 replace "$(INST_LIB)" above with "$(INST_ARCHLIB)", although if you
187 locate modules under lib, that would involve ensuring any "lib/" in
188 front of the module location were removed.
189 Common errors and problems
191 "No rule to make target `/usr/lib/perl5/CORE/config.h', needed by
192 `Makefile'"
193 Just what it says, you're missing that file. MakeMaker uses it to
194 determine if perl has been rebuilt since the Makefile was made.
195 It's a bit of a bug that it halts installation.
196 Some operating systems don't ship the CORE directory with their
198 base perl install. To solve the problem, you likely need to
199 install a perl development package such as perl-devel (CentOS,
200 Fedora and other Redhat systems) or perl (Ubuntu and other Debian
201 systems).
202 Philosophy and History
204 Why not just use <insert other build config tool here>?
205 Why did MakeMaker reinvent the build configuration wheel? Why not
206 just use autoconf or automake or ppm or Ant or ...
207 There are many reasons, but the major one is cross-platform
209 compatibility.
210 Perl is one of the most ported pieces of software ever. It works
212 on operating systems I've never even heard of (see perlport for
213 details). It needs a build tool that can work on all those
214 platforms and with any wacky C compilers and linkers they might
215 have.
216 No such build tool exists. Even make itself has wildly different
218 dialects. So we have to build our own.
219 What is Module::Build and how does it relate to MakeMaker?
221 Module::Build is a project by Ken Williams to supplant MakeMaker.
222 Its primary advantages are:
223 · pure perl. no make, no shell commands
225 · easier to customize
227 · cleaner internals
229 · less cruft
231 Module::Build was long the official heir apparent to MakeMaker.
233 The rate of both its development and adoption has slowed in recent
234 years, though, and it is unclear what the future holds for it.
235 That said, Module::Build set the stage for something to become the
236 heir to MakeMaker. MakeMaker's maintainers have long said that it
237 is a dead end and should be kept functioning, while being cautious
238 about extending with new features.
239 Module Writing
241 How do I keep my $VERSION up to date without resetting it manually?
242 Often you want to manually set the $VERSION in the main module
243 distribution because this is the version that everybody sees on
244 CPAN and maybe you want to customize it a bit. But for all the
245 other modules in your dist, $VERSION is really just bookkeeping and
246 all that's important is it goes up every time the module is
247 changed. Doing this by hand is a pain and you often forget.
248 Probably the easiest way to do this is using perl-reversion in
250 Perl::Version:
251 perl-reversion -bump
253 If your version control system supports revision numbers (git
255 doesn't easily), the simplest way to do it automatically is to use
256 its revision number (you are using version control, right?).
257 In CVS, RCS and SVN you use $Revision$ (see the documentation of
259 your version control system for details). Every time the file is
260 checked in the $Revision$ will be updated, updating your $VERSION.
261 SVN uses a simple integer for $Revision$ so you can adapt it for
263 your $VERSION like so:
264 ($VERSION) = q$Revision$ =~ /(\d+)/;
266 In CVS and RCS version 1.9 is followed by 1.10. Since CPAN
268 compares version numbers numerically we use a sprintf() to convert
269 1.9 to 1.009 and 1.10 to 1.010 which compare properly.
270 $VERSION = sprintf "%d.%03d", q$Revision$ =~ /(\d+)\.(\d+)/g;
272 If branches are involved (ie. $Revision: 1.5.3.4$) it's a little
274 more complicated.
275 # must be all on one line or MakeMaker will get confused.
277 $VERSION = do { my @r = (q$Revision$ =~ /\d+/g); sprintf "%d."."%03d" x $#r, @r };
278 In SVN, $Revision$ should be the same for every file in the project
280 so they would all have the same $VERSION. CVS and RCS have a
281 different $Revision$ per file so each file will have a different
282 $VERSION. Distributed version control systems, such as SVK, may
283 have a different $Revision$ based on who checks out the file,
284 leading to a different $VERSION on each machine! Finally, some
285 distributed version control systems, such as darcs, have no concept
286 of revision number at all.
287 What's this META.yml thing and how did it get in my MANIFEST?!
289 META.yml is a module meta-data file pioneered by Module::Build and
290 automatically generated as part of the 'distdir' target (and thus
291 'dist'). See "Module Meta-Data" in ExtUtils::MakeMaker.
292 To shut off its generation, pass the "NO_META" flag to
294 "WriteMakefile()".
295 How do I delete everything not in my MANIFEST?
297 Some folks are surprised that "make distclean" does not delete
298 everything not listed in their MANIFEST (thus making a clean
299 distribution) but only tells them what they need to delete. This
300 is done because it is considered too dangerous. While developing
301 your module you might write a new file, not add it to the MANIFEST,
302 then run a "distclean" and be sad because your new work was
303 deleted.
304 If you really want to do this, you can use
306 "ExtUtils::Manifest::manifind()" to read the MANIFEST and
307 File::Find to delete the files. But you have to be careful.
308 Here's a script to do that. Use at your own risk. Have fun
309 blowing holes in your foot.
310 #!/usr/bin/perl -w
312 use strict;
314 use File::Spec;
316 use File::Find;
317 use ExtUtils::Manifest qw(maniread);
318 my %manifest = map {( $_ => 1 )}
320 grep { File::Spec->canonpath($_) }
321 keys %{ maniread() };
322 if( !keys %manifest ) {
324 print "No files found in MANIFEST. Stopping.\n";
325 exit;
326 }
327 find({
329 wanted => sub {
330 my $path = File::Spec->canonpath($_);
331 return unless -f $path;
333 return if exists $manifest{ $path };
334 print "unlink $path\n";
336 unlink $path;
337 },
338 no_chdir => 1
339 },
340 "."
341 );
342 Which tar should I use on Windows?
344 We recommend ptar from Archive::Tar not older than 1.66 with '-C'
345 option.
346 Which zip should I use on Windows for '[ndg]make zipdist'?
348 We recommend InfoZIP: <http://www.info-zip.org/Zip.html>
349 XS
351 How do I prevent "object version X.XX does not match bootstrap
352 parameter Y.YY" errors?
353 XS code is very sensitive to the module version number and will
354 complain if the version number in your Perl module doesn't match.
355 If you change your module's version # without rerunning Makefile.PL
356 the old version number will remain in the Makefile, causing the XS
357 code to be built with the wrong number.
358 To avoid this, you can force the Makefile to be rebuilt whenever
360 you change the module containing the version number by adding this
361 to your WriteMakefile() arguments.
362 depend => { '$(FIRST_MAKEFILE)' => '$(VERSION_FROM)' }
364 How do I make two or more XS files coexist in the same directory?
366 Sometimes you need to have two and more XS files in the same
367 package. There are three ways: "XSMULTI", separate directories,
368 and bootstrapping one XS from another.
369 XSMULTI Structure your modules so they are all located under lib,
371 such that "Foo::Bar" is in lib/Foo/Bar.pm and
372 lib/Foo/Bar.xs, etc. Have your top-level "WriteMakefile"
373 set the variable "XSMULTI" to a true value.
374 Er, that's it.
376 Separate directories
378 Put each XS files into separate directories, each with
379 their own Makefile.PL. Make sure each of those Makefile.PLs
380 has the correct "CFLAGS", "INC", "LIBS" etc. You will need
381 to make sure the top-level Makefile.PL refers to each of
382 these using "DIR".
383 Bootstrapping
385 Let's assume that we have a package "Cool::Foo", which
386 includes "Cool::Foo" and "Cool::Bar" modules each having a
387 separate XS file. First we use the following Makefile.PL:
388 use ExtUtils::MakeMaker;
390 WriteMakefile(
392 NAME => 'Cool::Foo',
393 VERSION_FROM => 'Foo.pm',
394 OBJECT => q/$(O_FILES)/,
395 # ... other attrs ...
396 );
397 Notice the "OBJECT" attribute. MakeMaker generates the
399 following variables in Makefile:
400 # Handy lists of source code files:
402 XS_FILES= Bar.xs \
403 Foo.xs
404 C_FILES = Bar.c \
405 Foo.c
406 O_FILES = Bar.o \
407 Foo.o
408 Therefore we can use the "O_FILES" variable to tell
410 MakeMaker to use these objects into the shared library.
411 That's pretty much it. Now write Foo.pm and Foo.xs, Bar.pm
413 and Bar.xs, where Foo.pm bootstraps the shared library and
414 Bar.pm simply loading Foo.pm.
415 The only issue left is to how to bootstrap Bar.xs. This is
417 done from Foo.xs:
418 MODULE = Cool::Foo PACKAGE = Cool::Foo
420 BOOT:
422 # boot the second XS file
423 boot_Cool__Bar(aTHX_ cv);
424 If you have more than two files, this is the place where
426 you should boot extra XS files from.
427 The following four files sum up all the details discussed
429 so far.
430 Foo.pm:
432 -------
433 package Cool::Foo;
434 require DynaLoader;
436 our @ISA = qw(DynaLoader);
438 our $VERSION = '0.01';
439 bootstrap Cool::Foo $VERSION;
440 1;
442 Bar.pm:
444 -------
445 package Cool::Bar;
446 use Cool::Foo; # bootstraps Bar.xs
448 1;
450 Foo.xs:
452 -------
453 #include "EXTERN.h"
454 #include "perl.h"
455 #include "XSUB.h"
456 MODULE = Cool::Foo PACKAGE = Cool::Foo
458 BOOT:
460 # boot the second XS file
461 boot_Cool__Bar(aTHX_ cv);
462 MODULE = Cool::Foo PACKAGE = Cool::Foo PREFIX = cool_foo_
464 void
466 cool_foo_perl_rules()
467 CODE:
469 fprintf(stderr, "Cool::Foo says: Perl Rules\n");
470 Bar.xs:
472 -------
473 #include "EXTERN.h"
474 #include "perl.h"
475 #include "XSUB.h"
476 MODULE = Cool::Bar PACKAGE = Cool::Bar PREFIX = cool_bar_
478 void
480 cool_bar_perl_rules()
481 CODE:
483 fprintf(stderr, "Cool::Bar says: Perl Rules\n");
484 And of course a very basic test:
486 t/cool.t:
488 --------
489 use Test;
490 BEGIN { plan 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.28.0 2018-03-19 ExtUtils::MakeMaker::FAQ(3)