1 package ExtUtils::MakeMaker::FAQ;
11 ExtUtils::MakeMaker::FAQ - Frequently Asked Questions About MakeMaker
15 FAQs, tricks and tips for C<ExtUtils::MakeMaker>.
18 =head2 Module Installation
22 =item How do I install a module into my home directory?
24 If you're not the Perl administrator you probably don't have
25 permission to install a module to its default location. Then you
26 should install it for your own use into your home directory like so:
28 # Non-unix folks, replace ~ with /path/to/your/home/dir
29 perl Makefile.PL INSTALL_BASE=~
31 This will put modules into F<~/lib/perl5>, man pages into F<~/man> and
32 programs into F<~/bin>.
34 To ensure your Perl programs can see these newly installed modules,
35 set your C<PERL5LIB> environment variable to F<~/lib/perl5> or tell
36 each of your programs to look in that directory with the following:
38 use lib "$ENV{HOME}/lib/perl5";
40 or if $ENV{HOME} isn't set and you don't want to set it for some
41 reason, do it the long way.
43 use lib "/path/to/your/home/dir/lib/perl5";
46 =item How do I get MakeMaker and Module::Build to install to the same place?
48 Module::Build, as of 0.28, supports two ways to install to the same
49 location as MakeMaker.
51 1) Use INSTALL_BASE / C<--install_base>
53 MakeMaker (as of 6.31) and Module::Build (as of 0.28) both can install
54 to the same locations using the "install_base" concept. See
55 L<ExtUtils::MakeMaker/INSTALL_BASE> for details. To get MM and MB to
56 install to the same location simply set INSTALL_BASE in MM and
57 C<--install_base> in MB to the same location.
59 perl Makefile.PL INSTALL_BASE=/whatever
60 perl Build.PL --install_base /whatever
62 2) Use PREFIX / C<--prefix>
64 Module::Build 0.28 added support for C<--prefix> which works like
67 perl Makefile.PL PREFIX=/whatever
68 perl Build.PL --prefix /whatever
71 =item How do I keep from installing man pages?
73 Recent versions of MakeMaker will only install man pages on Unix like
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 have
81 to reconfigure Perl and tell it 'none' when it asks where to install
85 =item How do I use a module without installing it?
87 Two ways. One is to build the module normally...
93 ...and then set the PERL5LIB environment variable to point at the
94 blib/lib and blib/arch directories.
96 The other is to install the module in a temporary location.
98 perl Makefile.PL INSTALL_BASE=~/tmp
103 And then set PERL5LIB to F<~/tmp/lib/perl5>. This works well when you
104 have multiple modules to work with. It also ensures that the module
105 goes through its full installation process which may modify it.
110 =head2 Philosophy and History
114 =item Why not just use <insert other build config tool here>?
116 Why did MakeMaker reinvent the build configuration wheel? Why not
117 just use autoconf or automake or ppm or Ant or ...
119 There are many reasons, but the major one is cross-platform
122 Perl is one of the most ported pieces of software ever. It works on
123 operating systems I've never even heard of (see perlport for details).
124 It needs a build tool that can work on all those platforms and with
125 any wacky C compilers and linkers they might have.
127 No such build tool exists. Even make itself has wildly different
128 dialects. So we have to build our own.
131 =item What is Module::Build and how does it relate to MakeMaker?
133 Module::Build is a project by Ken Williams to supplant MakeMaker.
134 Its primary advantages are:
138 =item * pure perl. no make, no shell commands
140 =item * easier to customize
142 =item * cleaner internals
148 Module::Build is the official heir apparent to MakeMaker and we
149 encourage people to work on M::B rather than spending time adding features
155 =head2 Module Writing
159 =item How do I keep my $VERSION up to date without resetting it manually?
161 Often you want to manually set the $VERSION in the main module
162 distribution because this is the version that everybody sees on CPAN
163 and maybe you want to customize it a bit. But for all the other
164 modules in your dist, $VERSION is really just bookkeeping and all that's
165 important is it goes up every time the module is changed. Doing this
166 by hand is a pain and you often forget.
168 Simplest way to do it automatically is to use your version control
169 system's revision number (you are using version control, right?).
171 In CVS, RCS and SVN you use $Revision$ (see the documentation of your
172 version control system for details). Every time the file is checked
173 in the $Revision$ will be updated, updating your $VERSION.
175 SVN uses a simple integer for $Revision$ so you can adapt it for your
178 $VERSION = (q$Revision$) =~ /(\d+)/g;
180 In CVS and RCS version 1.9 is followed by 1.10. Since CPAN compares
181 version numbers numerically we use a sprintf() to convert 1.9 to 1.009
182 and 1.10 to 1.010 which compare properly.
184 $VERSION = sprintf "%d.%03d", q$Revision$ =~ /(\d+)\.(\d+)/g;
186 If branches are involved (ie. $Revision: 1.5.3.4$) its a little more
189 # must be all on one line or MakeMaker will get confused.
190 $VERSION = do { my @r = (q$Revision$ =~ /\d+/g); sprintf "%d."."%03d" x $#r, @r };
192 In SVN, $Revision$ should be the same for every file in the project so
193 they would all have the same $VERSION. CVS and RCS have a different
194 $Revision$ per file so each file will have a differnt $VERSION.
195 Distributed version control systems, such as SVK, may have a different
196 $Revision$ based on who checks out the file leading to a different $VERSION
197 on each machine! Finally, some distributed version control systems, such
198 as darcs, have no concept of revision number at all.
201 =item What's this F<META.yml> thing and how did it get in my F<MANIFEST>?!
203 F<META.yml> is a module meta-data file pioneered by Module::Build and
204 automatically generated as part of the 'distdir' target (and thus
205 'dist'). See L<ExtUtils::MakeMaker/"Module Meta-Data">.
207 To shut off its generation, pass the C<NO_META> flag to C<WriteMakefile()>.
210 =item How do I delete everything not in my F<MANIFEST>?
212 Some folks are surpried that C<make distclean> does not delete
213 everything not listed in their MANIFEST (thus making a clean
214 distribution) but only tells them what they need to delete. This is
215 done because it is considered too dangerous. While developing your
216 module you might write a new file, not add it to the MANIFEST, then
217 run a C<distclean> and be sad because your new work was deleted.
219 If you really want to do this, you can use
220 C<ExtUtils::Manifest::manifind()> to read the MANIFEST and File::Find
221 to delete the files. But you have to be careful. Here's a script to
222 do that. Use at your own risk. Have fun blowing holes in your foot.
230 use ExtUtils::Manifest qw(maniread);
232 my %manifest = map {( $_ => 1 )}
233 grep { File::Spec->canonpath($_) }
234 keys %{ maniread() };
236 if( !keys %manifest ) {
237 print "No files found in MANIFEST. Stopping.\n";
243 my $path = File::Spec->canonpath($_);
245 return unless -f $path;
246 return if exists $manifest{ $path };
248 print "unlink $path\n";
263 =item How to I prevent "object version X.XX does not match bootstrap parameter Y.YY" errors?
265 XS code is very sensitive to the module version number and will
266 complain if the version number in your Perl module doesn't match. If
267 you change your module's version # without rerunning Makefile.PL the old
268 version number will remain in the Makefile causing the XS code to be built
269 with the wrong number.
271 To avoid this, you can force the Makefile to be rebuilt whenever you
272 change the module containing the version number by adding this to your
273 WriteMakefile() arguments.
275 depend => { '$(FIRST_MAKEFILE)' => '$(VERSION_FROM)' }
278 =item How do I make two or more XS files coexist in the same directory?
280 Sometimes you need to have two and more XS files in the same package.
281 One way to go is to put them into separate directories, but sometimes
282 this is not the most suitable solution. The following technique allows
283 you to put two (and more) XS files in the same directory.
285 Let's assume that we have a package C<Cool::Foo>, which includes
286 C<Cool::Foo> and C<Cool::Bar> modules each having a separate XS
287 file. First we use the following I<Makefile.PL>:
289 use ExtUtils::MakeMaker;
293 VERSION_FROM => 'Foo.pm',
294 OBJECT => q/$(O_FILES)/,
295 # ... other attrs ...
298 Notice the C<OBJECT> attribute. MakeMaker generates the following
299 variables in I<Makefile>:
301 # Handy lists of source code files:
309 Therefore we can use the C<O_FILES> variable to tell MakeMaker to use
310 these objects into the shared library.
312 That's pretty much it. Now write I<Foo.pm> and I<Foo.xs>, I<Bar.pm>
313 and I<Bar.xs>, where I<Foo.pm> bootstraps the shared library and
314 I<Bar.pm> simply loading I<Foo.pm>.
316 The only issue left is to how to bootstrap I<Bar.xs>. This is done
319 MODULE = Cool::Foo PACKAGE = Cool::Foo
322 # boot the second XS file
323 boot_Cool__Bar(aTHX_ cv);
325 If you have more than two files, this is the place where you should
326 boot extra XS files from.
328 The following four files sum up all the details discussed so far.
336 our @ISA = qw(DynaLoader);
337 our $VERSION = '0.01';
338 bootstrap Cool::Foo $VERSION;
346 use Cool::Foo; # bootstraps Bar.xs
356 MODULE = Cool::Foo PACKAGE = Cool::Foo
359 # boot the second XS file
360 boot_Cool__Bar(aTHX_ cv);
362 MODULE = Cool::Foo PACKAGE = Cool::Foo PREFIX = cool_foo_
365 cool_foo_perl_rules()
368 fprintf(stderr, "Cool::Foo says: Perl Rules\n");
376 MODULE = Cool::Bar PACKAGE = Cool::Bar PREFIX = cool_bar_
379 cool_bar_perl_rules()
382 fprintf(stderr, "Cool::Bar says: Perl Rules\n");
384 And of course a very basic test:
389 BEGIN { plan tests => 1 };
392 Cool::Foo::perl_rules();
393 Cool::Bar::perl_rules();
396 This tip has been brought to you by Nick Ing-Simmons and Stas Bekman.
402 If you have a question you'd like to see added to the FAQ (whether or
403 not you have the answer) please send it to makemaker@perl.org.
407 The denizens of makemaker@perl.org.
411 L<ExtUtils::MakeMaker>