This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Sync with the latest MakeMaker snapshot.
[perl5.git] / lib / ExtUtils / MakeMaker / FAQ.pod
CommitLineData
479d2113
MS
1package ExtUtils::MakeMaker::FAQ;
2
03c94fc2 3(our $VERSION) = sprintf "%03d", q$Revision: 1.10 $ =~ /Revision:\s+(\S+)/;
479d2113
MS
4
51;
6__END__
7
8=head1 NAME
9
10ExtUtils::MakeMaker::FAQ - Frequently Asked Questions About MakeMaker
11
12=head1 DESCRIPTION
13
14FAQs, tricks and tips for C<ExtUtils::MakeMaker>.
15
03c94fc2
RGS
16
17=head2 Module Installation
18
19=over 4
20
21=item How do I keep from installing man pages?
22
23Recent versions of MakeMaker will only install man pages on Unix like
24operating systems.
25
26For an individual module:
27
28 perl Makefile.PL INSTALLMAN1DIR=none INSTALLMAN3DIR=none
29
30If you want to suppress man page installation for all modules you have
31to reconfigure Perl and tell it 'none' when it asks where to install
32man pages.
33
34
35=item How do I use a module without installing it?
36
37Two ways. One is to build the module normally...
38
39 perl Makefile.PL
40 make
41
42...and then set the PERL5LIB environment variable to point at the
43blib/lib and blib/arch directories.
44
45The other is to install the module in a temporary location.
46
47 perl Makefile.PL PREFIX=/tmp LIB=/tmp/lib/perl
48
49And then set PERL5LIB to /tmp/lib/perl. This works well when you have
50multiple modules to work with. It also ensures that the module goes
51through its full installation process which may modify it.
52
53=back
54
55
479d2113
MS
56=head2 Philosophy and History
57
58=over 4
59
60=item Why not just use <insert other build config tool here>?
61
62Why did MakeMaker reinvent the build configuration wheel? Why not
63just use autoconf or automake or ppm or Ant or ...
64
65There are many reasons, but the major one is cross-platform
66compatibility.
67
68Perl is one of the most ported pieces of software ever. It works on
69operating systems I've never even heard of (see perlport for details).
70It needs a build tool that can work on all those platforms and with
03c94fc2 71any wacky C compilers and linkers they might have.
479d2113 72
03c94fc2
RGS
73No such build tool exists. Even make itself has wildly different
74dialects. So we have to build our own.
479d2113
MS
75
76
03c94fc2 77=item What is Module::Build and how does it relate to MakeMaker?
479d2113
MS
78
79Module::Build is a project by Ken Williams to supplant MakeMaker.
80Its primary advantages are:
81
82=over 8
83
84=item * pure perl. no make, no shell commands
85
86=item * easier to customize
87
88=item * cleaner internals
89
90=item * less cruft
91
92=back
93
94Module::Build is the official heir apparent to MakeMaker and we
03c94fc2
RGS
95encourage people to work on M::B rather than spending time adding features
96to MakeMaker.
479d2113
MS
97
98=back
99
03c94fc2 100
2530b651
MS
101=head2 Module Writing
102
103=over 4
104
e3aa3ecb 105=item How do I keep my $VERSION up to date without resetting it manually?
2530b651
MS
106
107Often you want to manually set the $VERSION in the main module
108distribution because this is the version that everybody sees on CPAN
109and maybe you want to customize it a bit. But for all the other
110modules in your dist, $VERSION is really just bookkeeping and all that's
111important is it goes up every time the module is changed. Doing this
112by hand is a pain and you often forget.
113
114Simplest way to do it automatically is to use your version control
115system's revision number (you are using version control, right?).
116
c2990482 117In CVS and RCS you use $Z<>Revision$ writing it like so:
2530b651 118
03c94fc2 119 $VERSION = sprintf "%d.%03d", q$Revision: 1.10 $ =~ /(\d+)/g;
2530b651 120
c2990482 121Every time the file is checked in the $Z<>Revision$ will be updated,
2530b651
MS
122updating your $VERSION.
123
124In CVS version 1.9 is followed by 1.10. Since CPAN compares version
125numbers numerically we use a sprintf() to convert 1.9 to 1.009 and
1261.10 to 1.010 which compare properly.
127
c2990482 128If branches are involved (ie. $Z<>Revision: 1.5.3.4) its a little more
2530b651
MS
129complicated.
130
131 # must be all on one line or MakeMaker will get confused.
03c94fc2 132 $VERSION = do { my @r = (q$Revision: 1.10 $ =~ /\d+/g); sprintf "%d."."%03d" x $#r, @r };
2530b651 133
e3aa3ecb 134=item What's this F<META.yml> thing and how did it get in my F<MANIFEST>?!
c2990482
MS
135
136F<META.yml> is a module meta-data file pioneered by Module::Build and
137automatically generated as part of the 'distdir' target (and thus
138'dist'). See L<ExtUtils::MakeMaker/"Module Meta-Data">.
139
140To shut off its generation, pass the C<NO_META> flag to C<WriteMakefile()>.
2530b651
MS
141
142=back
143
479d2113
MS
144=head2 XS
145
146=over 4
147
e3aa3ecb 148=item How to I prevent "object version X.XX does not match bootstrap parameter Y.YY" errors?
dedf98bc
MS
149
150XS code is very sensitive to the module version number and will
151complain if the version number in your Perl module doesn't match. If
152you change your module's version # without reruning Makefile.PL the old
153version number will remain in the Makefile causing the XS code to be built
154with the wrong number.
155
156To avoid this, you can force the Makefile to be rebuilt whenever you
157change the module containing the version number by adding this to your
158WriteMakefile() arguments.
159
160 depend => { '$(FIRST_MAKEFILE)' => '$(VERSION_FROM)' }
161
162
e3aa3ecb 163=item How do I make two or more XS files coexist in the same directory?
479d2113
MS
164
165Sometimes you need to have two and more XS files in the same package.
166One way to go is to put them into separate directories, but sometimes
167this is not the most suitable solution. The following technique allows
168you to put two (and more) XS files in the same directory.
169
170Let's assume that we have a package C<Cool::Foo>, which includes
171C<Cool::Foo> and C<Cool::Bar> modules each having a separate XS
172file. First we use the following I<Makefile.PL>:
173
174 use ExtUtils::MakeMaker;
175
176 WriteMakefile(
177 NAME => 'Cool::Foo',
178 VERSION_FROM => 'Foo.pm',
179 OBJECT => q/$(O_FILES)/,
180 # ... other attrs ...
181 );
182
183Notice the C<OBJECT> attribute. MakeMaker generates the following
184variables in I<Makefile>:
185
186 # Handy lists of source code files:
187 XS_FILES= Bar.xs \
188 Foo.xs
189 C_FILES = Bar.c \
190 Foo.c
191 O_FILES = Bar.o \
192 Foo.o
193
194Therefore we can use the C<O_FILES> variable to tell MakeMaker to use
195these objects into the shared library.
196
197That's pretty much it. Now write I<Foo.pm> and I<Foo.xs>, I<Bar.pm>
198and I<Bar.xs>, where I<Foo.pm> bootstraps the shared library and
199I<Bar.pm> simply loading I<Foo.pm>.
200
201The only issue left is to how to bootstrap I<Bar.xs>. This is done
202from I<Foo.xs>:
203
204 MODULE = Cool::Foo PACKAGE = Cool::Foo
205
206 BOOT:
207 # boot the second XS file
208 boot_Cool__Bar(aTHX_ cv);
209
210If you have more than two files, this is the place where you should
211boot extra XS files from.
212
213The following four files sum up all the details discussed so far.
214
215 Foo.pm:
216 -------
217 package Cool::Foo;
218
219 require DynaLoader;
220
221 our @ISA = qw(DynaLoader);
222 our $VERSION = '0.01';
223 bootstrap Cool::Foo $VERSION;
224
225 1;
226
227 Bar.pm:
228 -------
229 package Cool::Bar;
230
231 use Cool::Foo; # bootstraps Bar.xs
232
233 1;
234
235 Foo.xs:
236 -------
237 #include "EXTERN.h"
238 #include "perl.h"
239 #include "XSUB.h"
240
241 MODULE = Cool::Foo PACKAGE = Cool::Foo
242
243 BOOT:
244 # boot the second XS file
245 boot_Cool__Bar(aTHX_ cv);
246
247 MODULE = Cool::Foo PACKAGE = Cool::Foo PREFIX = cool_foo_
248
249 void
250 cool_foo_perl_rules()
251
252 CODE:
253 fprintf(stderr, "Cool::Foo says: Perl Rules\n");
254
255 Bar.xs:
256 -------
257 #include "EXTERN.h"
258 #include "perl.h"
259 #include "XSUB.h"
260
261 MODULE = Cool::Bar PACKAGE = Cool::Bar PREFIX = cool_bar_
262
263 void
264 cool_bar_perl_rules()
265
266 CODE:
267 fprintf(stderr, "Cool::Bar says: Perl Rules\n");
268
269And of course a very basic test:
270
271 test.pl:
272 --------
273 use Test;
274 BEGIN { plan tests => 1 };
275 use Cool::Foo;
276 use Cool::Bar;
277 Cool::Foo::perl_rules();
278 Cool::Bar::perl_rules();
279 ok 1;
280
281This tip has been brought to you by Nick Ing-Simmons and Stas Bekman.
282
283=back
284
285=head1 PATCHING
286
287If you have a question you'd like to see added to the FAQ (whether or
288not you have the answer) please send it to makemaker@perl.org.
289
290=head1 AUTHOR
291
292The denizens of makemaker@perl.org.
293
294=head1 SEE ALSO
295
296L<ExtUtils::MakeMaker>
297
298=cut