1ExtUtils::MakeMaker::FAUQs(e3r)Contributed Perl DocumentEaxttiUotnils::MakeMaker::FAQ(3)
2
3
4

NAME

6       ExtUtils::MakeMaker::FAQ - Frequently Asked Questions About MakeMaker
7

DESCRIPTION

9       FAQs, tricks and tips for ExtUtils::MakeMaker.
10
11   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
18           Otherwise, you can install it for your own use into your home
19           directory like so:
20
21               # Non-unix folks, replace ~ with /path/to/your/home/dir
22               perl Makefile.PL INSTALL_BASE=~
23
24           This will put modules into ~/lib/perl5, man pages into ~/man and
25           programs into ~/bin.
26
27           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
31               use lib "$ENV{HOME}/lib/perl5";
32
33           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
36               use lib "/path/to/your/home/dir/lib/perl5";
37
38       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
42           We highly recommend the install_base method, its the simplest and
43           most closely approximates the expected behavior of an installation
44           prefix.
45
46           1) Use INSTALL_BASE / "--install_base"
47
48           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
54               perl Makefile.PL INSTALL_BASE=/whatever
55               perl Build.PL    --install_base /whatever
56
57           This works most like other language's behavior when you specify a
58           prefix.  We recommend this method.
59
60           2) Use PREFIX / "--prefix"
61
62           Module::Build 0.28 added support for "--prefix" which works like
63           MakeMaker's PREFIX.
64
65               perl Makefile.PL PREFIX=/whatever
66               perl Build.PL    --prefix /whatever
67
68           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
73       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
78           For an individual module:
79
80                   perl Makefile.PL INSTALLMAN1DIR=none INSTALLMAN3DIR=none
81
82           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
86       How do I use a module without installing it?
87           Two ways.  One is to build the module normally...
88
89                   perl Makefile.PL
90                   make
91                   make test
92
93           ...and then use blib to point Perl at the built but uninstalled
94           module:
95
96                   perl -Mblib script.pl
97                   perl -Mblib -e '...'
98
99           The other is to install the module in a temporary location.
100
101                   perl Makefile.PL INSTALL_BASE=~/tmp
102                   make
103                   make test
104                   make install
105
106           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
111       How can I organize tests into subdirectories and have them run?
112           Let's take the following test directory structure:
113
114               t/foo/sometest.t
115               t/bar/othertest.t
116               t/bar/baz/anothertest.t
117
118           Now, inside of the "WriteMakeFile()" function in your Makefile.PL,
119           specify where your tests are located with the "test" directive:
120
121               test => {TESTS => 't/*.t t/*/*.t t/*/*/*.t'}
122
123           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
128           Note that you do not have to use wildcards. You can specify
129           explicitly which subdirectories to run tests in:
130
131               test => {TESTS => 't/*.t t/foo/*.t t/bar/baz/*.t'}
132
133       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
140           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
149       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
155               # 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
166               # common.pl:
167               sub get_version { '0.04' }
168               sub process { my $v = get_version(); s/__VERSION__/$v/g; }
169               1;
170
171               # 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
183           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
186           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
191   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
198           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
204   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
209           There are many reasons, but the major one is cross-platform
210           compatibility.
211
212           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
218           No such build tool exists.  Even make itself has wildly different
219           dialects.  So we have to build our own.
220
221       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
225           •       pure perl.  no make, no shell commands
226
227           •       easier to customize
228
229           •       cleaner internals
230
231           •       less cruft
232
233           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
241   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
250           Probably the easiest way to do this is using perl-reversion in
251           Perl::Version:
252
253             perl-reversion -bump
254
255           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
259           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
263           SVN uses a simple integer for $Revision$ so you can adapt it for
264           your $VERSION like so:
265
266               ($VERSION) = q$Revision$ =~ /(\d+)/;
267
268           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
272               $VERSION = sprintf "%d.%03d", q$Revision$ =~ /(\d+)\.(\d+)/g;
273
274           If branches are involved (ie. $Revision: 1.5.3.4$) it's a little
275           more complicated.
276
277               # 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
280           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
289       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
294           To shut off its generation, pass the "NO_META" flag to
295           "WriteMakefile()".
296
297       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
306           If you really want to do this, you can use
307           "ExtUtils::Manifest::manifind()" to read the MANIFEST and
308           File::Find to delete the files.  But you have to be careful.
309           Here's a script to do that.  Use at your own risk.  Have fun
310           blowing holes in your foot.
311
312               #!/usr/bin/perl -w
313
314               use strict;
315
316               use File::Spec;
317               use File::Find;
318               use ExtUtils::Manifest qw(maniread);
319
320               my %manifest = map  {( $_ => 1 )}
321                              grep { File::Spec->canonpath($_) }
322                                   keys %{ maniread() };
323
324               if( !keys %manifest ) {
325                   print "No files found in MANIFEST.  Stopping.\n";
326                   exit;
327               }
328
329               find({
330                     wanted   => sub {
331                         my $path = File::Spec->canonpath($_);
332
333                         return unless -f $path;
334                         return if exists $manifest{ $path };
335
336                         print "unlink $path\n";
337                         unlink $path;
338                     },
339                     no_chdir => 1
340                    },
341                    "."
342               );
343
344       Which tar should I use on Windows?
345           We recommend ptar from Archive::Tar not older than 1.66 with '-C'
346           option.
347
348       Which zip should I use on Windows for '[ndg]make zipdist'?
349           We recommend InfoZIP: <http://www.info-zip.org/Zip.html>
350
351   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
360           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
364               depend => { '$(FIRST_MAKEFILE)' => '$(VERSION_FROM)' }
365
366       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
371           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
376                   Er, that's it.
377
378           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
385           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
390                     use ExtUtils::MakeMaker;
391
392                     WriteMakefile(
393                         NAME              => 'Cool::Foo',
394                         VERSION_FROM      => 'Foo.pm',
395                         OBJECT              => q/$(O_FILES)/,
396                         # ... other attrs ...
397                     );
398
399                   Notice the "OBJECT" attribute. MakeMaker generates the
400                   following variables in Makefile:
401
402                     # 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
410                   Therefore we can use the "O_FILES" variable to tell
411                   MakeMaker to use these objects into the shared library.
412
413                   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
417                   The only issue left is to how to bootstrap Bar.xs. This is
418                   done from Foo.xs:
419
420                     MODULE = Cool::Foo PACKAGE = Cool::Foo
421
422                     BOOT:
423                     # boot the second XS file
424                     boot_Cool__Bar(aTHX_ cv);
425
426                   If you have more than two files, this is the place where
427                   you should boot extra XS files from.
428
429                   The following four files sum up all the details discussed
430                   so far.
431
432                     Foo.pm:
433                     -------
434                     package Cool::Foo;
435
436                     require DynaLoader;
437
438                     our @ISA = qw(DynaLoader);
439                     our $VERSION = '0.01';
440                     bootstrap Cool::Foo $VERSION;
441
442                     1;
443
444                     Bar.pm:
445                     -------
446                     package Cool::Bar;
447
448                     use Cool::Foo; # bootstraps Bar.xs
449
450                     1;
451
452                     Foo.xs:
453                     -------
454                     #include "EXTERN.h"
455                     #include "perl.h"
456                     #include "XSUB.h"
457
458                     MODULE = Cool::Foo  PACKAGE = Cool::Foo
459
460                     BOOT:
461                     # boot the second XS file
462                     boot_Cool__Bar(aTHX_ cv);
463
464                     MODULE = Cool::Foo  PACKAGE = Cool::Foo  PREFIX = cool_foo_
465
466                     void
467                     cool_foo_perl_rules()
468
469                         CODE:
470                         fprintf(stderr, "Cool::Foo says: Perl Rules\n");
471
472                     Bar.xs:
473                     -------
474                     #include "EXTERN.h"
475                     #include "perl.h"
476                     #include "XSUB.h"
477
478                     MODULE = Cool::Bar  PACKAGE = Cool::Bar PREFIX = cool_bar_
479
480                     void
481                     cool_bar_perl_rules()
482
483                         CODE:
484                         fprintf(stderr, "Cool::Bar says: Perl Rules\n");
485
486                   And of course a very basic test:
487
488                     t/cool.t:
489                     --------
490                     use Test;
491                     BEGIN { plan tests => 1 };
492                     use Cool::Foo;
493                     use Cool::Bar;
494                     Cool::Foo::perl_rules();
495                     Cool::Bar::perl_rules();
496                     ok 1;
497
498                   This tip has been brought to you by Nick Ing-Simmons and
499                   Stas Bekman.
500
501                   An alternative way to achieve this can be seen in
502                   Gtk2::CodeGen and Glib::CodeGen.
503

DESIGN

505   MakeMaker object hierarchy (simplified)
506       What most people need to know (superclasses on top.)
507
508               ExtUtils::MM_Any
509                       |
510               ExtUtils::MM_Unix
511                       |
512               ExtUtils::MM_{Current OS}
513                       |
514               ExtUtils::MakeMaker
515                       |
516                      MY
517
518       The object actually used is of the class MY which allows you to
519       override bits of MakeMaker inside your Makefile.PL by declaring
520       MY::foo() methods.
521
522   MakeMaker object hierarchy (real)
523       Here's how it really works:
524
525                                           ExtUtils::MM_Any
526                                                   |
527                                           ExtUtils::MM_Unix
528                                                   |
529           ExtUtils::Liblist::Kid          ExtUtils::MM_{Current OS} (if necessary)
530                 |                                          |
531           ExtUtils::Liblist     ExtUtils::MakeMaker        |
532                           |     |                          |
533                           |     |   |-----------------------
534                          ExtUtils::MM
535                          |          |
536               ExtUtils::MY         MM (created by ExtUtils::MM)
537               |                                   |
538               MY (created by ExtUtils::MY)        |
539                           .                       |
540                        (mixin)                    |
541                           .                       |
542                      PACK### (created each call to ExtUtils::MakeMaker->new)
543
544       NOTE: Yes, this is a mess.  See
545       <http://archive.develooper.com/makemaker@perl.org/msg00134.html> for
546       some history.
547
548       NOTE: When ExtUtils::MM is loaded it chooses a superclass for MM from
549       amongst the ExtUtils::MM_* modules based on the current operating
550       system.
551
552       NOTE: ExtUtils::MM_{Current OS} represents one of the ExtUtils::MM_*
553       modules except ExtUtils::MM_Any chosen based on your operating system.
554
555       NOTE: The main object used by MakeMaker is a PACK### object, *not*
556       ExtUtils::MakeMaker.  It is, effectively, a subclass of MY,
557       ExtUtils::MakeMaker, ExtUtils::Liblist and ExtUtils::MM_{Current OS}
558
559       NOTE: The methods in MY are simply copied into PACK### rather than MY
560       being a superclass of PACK###.  I don't remember the rationale.
561
562       NOTE: ExtUtils::Liblist should be removed from the inheritance hiearchy
563       and simply be called as functions.
564
565       NOTE: Modules like File::Spec and Exporter have been omitted for
566       clarity.
567
568   The MM_* hierarchy
569                                       MM_Win95   MM_NW5
570                                            \      /
571        MM_BeOS  MM_Cygwin  MM_OS2  MM_VMS  MM_Win32  MM_DOS  MM_UWIN
572              \        |      |         |        /      /      /
573               ------------------------------------------------
574                                  |       |
575                               MM_Unix    |
576                                     |    |
577                                     MM_Any
578
579       NOTE: Each direct MM_Unix subclass is also an MM_Any subclass.  This is
580       a temporary hack because MM_Unix overrides some MM_Any methods with
581       Unix specific code.  It allows the non-Unix modules to see the original
582       MM_Any implementations.
583
584       NOTE: Modules like File::Spec and Exporter have been omitted for
585       clarity.
586

PATCHING

588       If you have a question you'd like to see added to the FAQ (whether or
589       not you have the answer) please either:
590
591       • make a pull request on the MakeMaker github repository
592
593       • raise a issue on the MakeMaker github repository
594
595       • file an RT ticket
596
597       • email makemaker@perl.org
598

AUTHOR

600       The denizens of makemaker@perl.org.
601

SEE ALSO

603       ExtUtils::MakeMaker
604
605
606
607perl v5.34.0                      2022-01-21       ExtUtils::MakeMaker::FAQ(3)
Impressum