Commit | Line | Data |
479d2113 |
1 | package ExtUtils::MakeMaker::FAQ; |
2 | |
a592ba15 |
3 | our $VERSION = '1.12'; |
479d2113 |
4 | |
5 | 1; |
6 | __END__ |
7 | |
8 | =head1 NAME |
9 | |
10 | ExtUtils::MakeMaker::FAQ - Frequently Asked Questions About MakeMaker |
11 | |
12 | =head1 DESCRIPTION |
13 | |
14 | FAQs, tricks and tips for C<ExtUtils::MakeMaker>. |
15 | |
03c94fc2 |
16 | |
17 | =head2 Module Installation |
18 | |
19 | =over 4 |
20 | |
58d32538 |
21 | =item How do I install a module into my home directory? |
22 | |
23 | If you're not the Perl administrator you probably don't have |
24 | permission to install a module to its default location. Then you |
25 | should install it for your own use into your home directory like so: |
26 | |
1e65eb70 |
27 | # Non-unix folks, replace ~ with /path/to/your/home/dir |
58d32538 |
28 | perl Makefile.PL INSTALL_BASE=~ |
29 | |
30 | This will put modules into F<~/lib/perl5>, man pages into F<~/man> and |
31 | programs into F<~/bin>. |
32 | |
33 | To ensure your Perl programs can see these newly installed modules, |
34 | set your C<PERL5LIB> environment variable to F<~/lib/perl5> or tell |
35 | each of your programs to look in that directory with the following: |
36 | |
37 | use lib "$ENV{HOME}/lib/perl5"; |
38 | |
1e65eb70 |
39 | or if $ENV{HOME} isn't set and you don't want to set it for some |
40 | reason, do it the long way. |
41 | |
42 | use lib "/path/to/your/home/dir/lib/perl5"; |
43 | |
58d32538 |
44 | |
45 | =item How do I get MakeMaker and Module::Build to install to the same place? |
46 | |
47 | Module::Build, as of 0.28, supports two ways to install to the same |
48 | location as MakeMaker. |
49 | |
50 | 1) Use INSTALL_BASE / C<--install_base> |
51 | |
52 | MakeMaker (as of 6.31) and Module::Build (as of 0.28) both can install |
53 | to the same locations using the "install_base" concept. See |
54 | L<ExtUtils::MakeMaker/INSTALL_BASE> for details. To get MM and MB to |
55 | install to the same location simply set INSTALL_BASE in MM and |
56 | C<--install_base> in MB to the same location. |
57 | |
58 | perl Makefile.PL INSTALL_BASE=/whatever |
59 | perl Build.PL --install_base /whatever |
60 | |
61 | 2) Use PREFIX / C<--prefix> |
62 | |
63 | Module::Build 0.28 added support for C<--prefix> which works like |
64 | MakeMaker's PREFIX. |
65 | |
66 | perl Makefile.PL PREFIX=/whatever |
67 | perl Build.PL --prefix /whatever |
68 | |
69 | |
03c94fc2 |
70 | =item How do I keep from installing man pages? |
71 | |
72 | Recent versions of MakeMaker will only install man pages on Unix like |
73 | operating systems. |
74 | |
75 | For an individual module: |
76 | |
77 | perl Makefile.PL INSTALLMAN1DIR=none INSTALLMAN3DIR=none |
78 | |
79 | If you want to suppress man page installation for all modules you have |
80 | to reconfigure Perl and tell it 'none' when it asks where to install |
81 | man pages. |
82 | |
83 | |
84 | =item How do I use a module without installing it? |
85 | |
86 | Two ways. One is to build the module normally... |
87 | |
88 | perl Makefile.PL |
89 | make |
58d32538 |
90 | make test |
03c94fc2 |
91 | |
92 | ...and then set the PERL5LIB environment variable to point at the |
93 | blib/lib and blib/arch directories. |
94 | |
95 | The other is to install the module in a temporary location. |
96 | |
58d32538 |
97 | perl Makefile.PL INSTALL_BASE=~/tmp |
98 | make |
99 | make test |
100 | make install |
03c94fc2 |
101 | |
58d32538 |
102 | And then set PERL5LIB to F<~/tmp/lib/perl5>. This works well when you |
103 | have multiple modules to work with. It also ensures that the module |
104 | goes through its full installation process which may modify it. |
03c94fc2 |
105 | |
277189c8 |
106 | =item PREFIX vs INSTALL_BASE from Module::Build::Cookbook |
107 | |
108 | The behavior of PREFIX is complicated and depends closely on how your |
109 | Perl is configured. The resulting installation locations will vary from |
110 | machine to machine and even different installations of Perl on the same machine. |
111 | Because of this, its difficult to document where prefix will place your modules. |
112 | |
113 | In contrast, INSTALL_BASE has predictable, easy to explain installation locations. |
114 | Now that Module::Build and MakeMaker both have INSTALL_BASE there is little reason |
115 | to use PREFIX other than to preserve your existing installation locations. If you |
116 | are starting a fresh Perl installation we encourage you to use INSTALL_BASE. If |
117 | you have an existing installation installed via PREFIX, consider moving it to an |
118 | installation structure matching INSTALL_BASE and using that instead. |
119 | |
03c94fc2 |
120 | =back |
121 | |
122 | |
479d2113 |
123 | =head2 Philosophy and History |
124 | |
125 | =over 4 |
126 | |
127 | =item Why not just use <insert other build config tool here>? |
128 | |
129 | Why did MakeMaker reinvent the build configuration wheel? Why not |
130 | just use autoconf or automake or ppm or Ant or ... |
131 | |
132 | There are many reasons, but the major one is cross-platform |
133 | compatibility. |
134 | |
135 | Perl is one of the most ported pieces of software ever. It works on |
136 | operating systems I've never even heard of (see perlport for details). |
137 | It needs a build tool that can work on all those platforms and with |
03c94fc2 |
138 | any wacky C compilers and linkers they might have. |
479d2113 |
139 | |
03c94fc2 |
140 | No such build tool exists. Even make itself has wildly different |
141 | dialects. So we have to build our own. |
479d2113 |
142 | |
143 | |
03c94fc2 |
144 | =item What is Module::Build and how does it relate to MakeMaker? |
479d2113 |
145 | |
146 | Module::Build is a project by Ken Williams to supplant MakeMaker. |
147 | Its primary advantages are: |
148 | |
149 | =over 8 |
150 | |
151 | =item * pure perl. no make, no shell commands |
152 | |
153 | =item * easier to customize |
154 | |
155 | =item * cleaner internals |
156 | |
157 | =item * less cruft |
158 | |
159 | =back |
160 | |
161 | Module::Build is the official heir apparent to MakeMaker and we |
03c94fc2 |
162 | encourage people to work on M::B rather than spending time adding features |
163 | to MakeMaker. |
479d2113 |
164 | |
165 | =back |
166 | |
03c94fc2 |
167 | |
2530b651 |
168 | =head2 Module Writing |
169 | |
170 | =over 4 |
171 | |
e3aa3ecb |
172 | =item How do I keep my $VERSION up to date without resetting it manually? |
2530b651 |
173 | |
174 | Often you want to manually set the $VERSION in the main module |
175 | distribution because this is the version that everybody sees on CPAN |
176 | and maybe you want to customize it a bit. But for all the other |
177 | modules in your dist, $VERSION is really just bookkeeping and all that's |
178 | important is it goes up every time the module is changed. Doing this |
179 | by hand is a pain and you often forget. |
180 | |
181 | Simplest way to do it automatically is to use your version control |
182 | system's revision number (you are using version control, right?). |
183 | |
7292dc67 |
184 | In CVS, RCS and SVN you use $Revision$ (see the documentation of your |
2977d345 |
185 | version control system for details). Every time the file is checked |
186 | in the $Revision$ will be updated, updating your $VERSION. |
2530b651 |
187 | |
2977d345 |
188 | SVN uses a simple integer for $Revision$ so you can adapt it for your |
189 | $VERSION like so: |
2530b651 |
190 | |
277189c8 |
191 | ($VERSION) = q$Revision$ =~ /(\d+)/; |
2530b651 |
192 | |
2977d345 |
193 | In CVS and RCS version 1.9 is followed by 1.10. Since CPAN compares |
194 | version numbers numerically we use a sprintf() to convert 1.9 to 1.009 |
195 | and 1.10 to 1.010 which compare properly. |
196 | |
197 | $VERSION = sprintf "%d.%03d", q$Revision$ =~ /(\d+)\.(\d+)/g; |
2530b651 |
198 | |
7292dc67 |
199 | If branches are involved (ie. $Revision: 1.5.3.4$) its a little more |
2530b651 |
200 | complicated. |
201 | |
202 | # must be all on one line or MakeMaker will get confused. |
7292dc67 |
203 | $VERSION = do { my @r = (q$Revision$ =~ /\d+/g); sprintf "%d."."%03d" x $#r, @r }; |
2530b651 |
204 | |
2977d345 |
205 | In SVN, $Revision$ should be the same for every file in the project so |
206 | they would all have the same $VERSION. CVS and RCS have a different |
207 | $Revision$ per file so each file will have a differnt $VERSION. |
208 | Distributed version control systems, such as SVK, may have a different |
209 | $Revision$ based on who checks out the file leading to a different $VERSION |
210 | on each machine! Finally, some distributed version control systems, such |
211 | as darcs, have no concept of revision number at all. |
212 | |
213 | |
e3aa3ecb |
214 | =item What's this F<META.yml> thing and how did it get in my F<MANIFEST>?! |
c2990482 |
215 | |
216 | F<META.yml> is a module meta-data file pioneered by Module::Build and |
217 | automatically generated as part of the 'distdir' target (and thus |
218 | 'dist'). See L<ExtUtils::MakeMaker/"Module Meta-Data">. |
219 | |
220 | To shut off its generation, pass the C<NO_META> flag to C<WriteMakefile()>. |
2530b651 |
221 | |
58d32538 |
222 | |
223 | =item How do I delete everything not in my F<MANIFEST>? |
224 | |
225 | Some folks are surpried that C<make distclean> does not delete |
226 | everything not listed in their MANIFEST (thus making a clean |
227 | distribution) but only tells them what they need to delete. This is |
228 | done because it is considered too dangerous. While developing your |
229 | module you might write a new file, not add it to the MANIFEST, then |
230 | run a C<distclean> and be sad because your new work was deleted. |
231 | |
232 | If you really want to do this, you can use |
233 | C<ExtUtils::Manifest::manifind()> to read the MANIFEST and File::Find |
234 | to delete the files. But you have to be careful. Here's a script to |
235 | do that. Use at your own risk. Have fun blowing holes in your foot. |
236 | |
237 | #!/usr/bin/perl -w |
238 | |
239 | use strict; |
240 | |
241 | use File::Spec; |
242 | use File::Find; |
243 | use ExtUtils::Manifest qw(maniread); |
244 | |
245 | my %manifest = map {( $_ => 1 )} |
246 | grep { File::Spec->canonpath($_) } |
247 | keys %{ maniread() }; |
248 | |
249 | if( !keys %manifest ) { |
250 | print "No files found in MANIFEST. Stopping.\n"; |
251 | exit; |
252 | } |
253 | |
254 | find({ |
255 | wanted => sub { |
256 | my $path = File::Spec->canonpath($_); |
257 | |
258 | return unless -f $path; |
259 | return if exists $manifest{ $path }; |
260 | |
261 | print "unlink $path\n"; |
262 | unlink $path; |
263 | }, |
264 | no_chdir => 1 |
265 | }, |
266 | "." |
267 | ); |
268 | |
269 | |
5bdf71cc |
270 | =item Which zip should I use on Windows for '[nd]make zipdist'? |
271 | |
272 | We recommend InfoZIP: L<http://www.info-zip.org/Zip.html> |
273 | |
274 | |
2530b651 |
275 | =back |
276 | |
479d2113 |
277 | =head2 XS |
278 | |
279 | =over 4 |
280 | |
e3aa3ecb |
281 | =item How to I prevent "object version X.XX does not match bootstrap parameter Y.YY" errors? |
dedf98bc |
282 | |
283 | XS code is very sensitive to the module version number and will |
284 | complain if the version number in your Perl module doesn't match. If |
c2878c71 |
285 | you change your module's version # without rerunning Makefile.PL the old |
dedf98bc |
286 | version number will remain in the Makefile causing the XS code to be built |
287 | with the wrong number. |
288 | |
289 | To avoid this, you can force the Makefile to be rebuilt whenever you |
290 | change the module containing the version number by adding this to your |
291 | WriteMakefile() arguments. |
292 | |
293 | depend => { '$(FIRST_MAKEFILE)' => '$(VERSION_FROM)' } |
294 | |
295 | |
e3aa3ecb |
296 | =item How do I make two or more XS files coexist in the same directory? |
479d2113 |
297 | |
298 | Sometimes you need to have two and more XS files in the same package. |
299 | One way to go is to put them into separate directories, but sometimes |
300 | this is not the most suitable solution. The following technique allows |
301 | you to put two (and more) XS files in the same directory. |
302 | |
303 | Let's assume that we have a package C<Cool::Foo>, which includes |
304 | C<Cool::Foo> and C<Cool::Bar> modules each having a separate XS |
305 | file. First we use the following I<Makefile.PL>: |
306 | |
307 | use ExtUtils::MakeMaker; |
308 | |
309 | WriteMakefile( |
310 | NAME => 'Cool::Foo', |
311 | VERSION_FROM => 'Foo.pm', |
312 | OBJECT => q/$(O_FILES)/, |
313 | # ... other attrs ... |
314 | ); |
315 | |
316 | Notice the C<OBJECT> attribute. MakeMaker generates the following |
317 | variables in I<Makefile>: |
318 | |
319 | # Handy lists of source code files: |
320 | XS_FILES= Bar.xs \ |
321 | Foo.xs |
322 | C_FILES = Bar.c \ |
323 | Foo.c |
324 | O_FILES = Bar.o \ |
325 | Foo.o |
326 | |
327 | Therefore we can use the C<O_FILES> variable to tell MakeMaker to use |
328 | these objects into the shared library. |
329 | |
330 | That's pretty much it. Now write I<Foo.pm> and I<Foo.xs>, I<Bar.pm> |
331 | and I<Bar.xs>, where I<Foo.pm> bootstraps the shared library and |
332 | I<Bar.pm> simply loading I<Foo.pm>. |
333 | |
334 | The only issue left is to how to bootstrap I<Bar.xs>. This is done |
335 | from I<Foo.xs>: |
336 | |
337 | MODULE = Cool::Foo PACKAGE = Cool::Foo |
338 | |
339 | BOOT: |
340 | # boot the second XS file |
341 | boot_Cool__Bar(aTHX_ cv); |
342 | |
343 | If you have more than two files, this is the place where you should |
344 | boot extra XS files from. |
345 | |
346 | The following four files sum up all the details discussed so far. |
347 | |
348 | Foo.pm: |
349 | ------- |
350 | package Cool::Foo; |
351 | |
352 | require DynaLoader; |
353 | |
354 | our @ISA = qw(DynaLoader); |
355 | our $VERSION = '0.01'; |
356 | bootstrap Cool::Foo $VERSION; |
357 | |
358 | 1; |
359 | |
360 | Bar.pm: |
361 | ------- |
362 | package Cool::Bar; |
363 | |
364 | use Cool::Foo; # bootstraps Bar.xs |
365 | |
366 | 1; |
367 | |
368 | Foo.xs: |
369 | ------- |
370 | #include "EXTERN.h" |
371 | #include "perl.h" |
372 | #include "XSUB.h" |
373 | |
374 | MODULE = Cool::Foo PACKAGE = Cool::Foo |
375 | |
376 | BOOT: |
377 | # boot the second XS file |
378 | boot_Cool__Bar(aTHX_ cv); |
379 | |
380 | MODULE = Cool::Foo PACKAGE = Cool::Foo PREFIX = cool_foo_ |
381 | |
382 | void |
383 | cool_foo_perl_rules() |
384 | |
385 | CODE: |
386 | fprintf(stderr, "Cool::Foo says: Perl Rules\n"); |
387 | |
388 | Bar.xs: |
389 | ------- |
390 | #include "EXTERN.h" |
391 | #include "perl.h" |
392 | #include "XSUB.h" |
393 | |
394 | MODULE = Cool::Bar PACKAGE = Cool::Bar PREFIX = cool_bar_ |
395 | |
396 | void |
397 | cool_bar_perl_rules() |
398 | |
399 | CODE: |
400 | fprintf(stderr, "Cool::Bar says: Perl Rules\n"); |
401 | |
402 | And of course a very basic test: |
403 | |
58d32538 |
404 | t/cool.t: |
479d2113 |
405 | -------- |
406 | use Test; |
407 | BEGIN { plan tests => 1 }; |
408 | use Cool::Foo; |
409 | use Cool::Bar; |
410 | Cool::Foo::perl_rules(); |
411 | Cool::Bar::perl_rules(); |
412 | ok 1; |
413 | |
414 | This tip has been brought to you by Nick Ing-Simmons and Stas Bekman. |
415 | |
416 | =back |
417 | |
418 | =head1 PATCHING |
419 | |
420 | If you have a question you'd like to see added to the FAQ (whether or |
421 | not you have the answer) please send it to makemaker@perl.org. |
422 | |
423 | =head1 AUTHOR |
424 | |
425 | The denizens of makemaker@perl.org. |
426 | |
427 | =head1 SEE ALSO |
428 | |
429 | L<ExtUtils::MakeMaker> |
430 | |
431 | =cut |