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