This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Stateful PerlIO implemented [Was: [perl #22261] Was: Unrecognised BOM...]
[perl5.git] / lib / ExtUtils / MakeMaker / FAQ.pod
CommitLineData
479d2113
MS
1package ExtUtils::MakeMaker::FAQ;
2
3our $VERSION = '0.02';
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
60=head2 XS
61
62=over 4
63
dedf98bc
MS
64=item How to I prevent "object version X.XX does not match bootstrap parameter Y.YY" errors?
65
66XS code is very sensitive to the module version number and will
67complain if the version number in your Perl module doesn't match. If
68you change your module's version # without reruning Makefile.PL the old
69version number will remain in the Makefile causing the XS code to be built
70with the wrong number.
71
72To avoid this, you can force the Makefile to be rebuilt whenever you
73change the module containing the version number by adding this to your
74WriteMakefile() arguments.
75
76 depend => { '$(FIRST_MAKEFILE)' => '$(VERSION_FROM)' }
77
78
479d2113
MS
79=item How do I make two or more XS files coexist in the same directory?
80
81Sometimes you need to have two and more XS files in the same package.
82One way to go is to put them into separate directories, but sometimes
83this is not the most suitable solution. The following technique allows
84you to put two (and more) XS files in the same directory.
85
86Let's assume that we have a package C<Cool::Foo>, which includes
87C<Cool::Foo> and C<Cool::Bar> modules each having a separate XS
88file. First we use the following I<Makefile.PL>:
89
90 use ExtUtils::MakeMaker;
91
92 WriteMakefile(
93 NAME => 'Cool::Foo',
94 VERSION_FROM => 'Foo.pm',
95 OBJECT => q/$(O_FILES)/,
96 # ... other attrs ...
97 );
98
99Notice the C<OBJECT> attribute. MakeMaker generates the following
100variables in I<Makefile>:
101
102 # Handy lists of source code files:
103 XS_FILES= Bar.xs \
104 Foo.xs
105 C_FILES = Bar.c \
106 Foo.c
107 O_FILES = Bar.o \
108 Foo.o
109
110Therefore we can use the C<O_FILES> variable to tell MakeMaker to use
111these objects into the shared library.
112
113That's pretty much it. Now write I<Foo.pm> and I<Foo.xs>, I<Bar.pm>
114and I<Bar.xs>, where I<Foo.pm> bootstraps the shared library and
115I<Bar.pm> simply loading I<Foo.pm>.
116
117The only issue left is to how to bootstrap I<Bar.xs>. This is done
118from I<Foo.xs>:
119
120 MODULE = Cool::Foo PACKAGE = Cool::Foo
121
122 BOOT:
123 # boot the second XS file
124 boot_Cool__Bar(aTHX_ cv);
125
126If you have more than two files, this is the place where you should
127boot extra XS files from.
128
129The following four files sum up all the details discussed so far.
130
131 Foo.pm:
132 -------
133 package Cool::Foo;
134
135 require DynaLoader;
136
137 our @ISA = qw(DynaLoader);
138 our $VERSION = '0.01';
139 bootstrap Cool::Foo $VERSION;
140
141 1;
142
143 Bar.pm:
144 -------
145 package Cool::Bar;
146
147 use Cool::Foo; # bootstraps Bar.xs
148
149 1;
150
151 Foo.xs:
152 -------
153 #include "EXTERN.h"
154 #include "perl.h"
155 #include "XSUB.h"
156
157 MODULE = Cool::Foo PACKAGE = Cool::Foo
158
159 BOOT:
160 # boot the second XS file
161 boot_Cool__Bar(aTHX_ cv);
162
163 MODULE = Cool::Foo PACKAGE = Cool::Foo PREFIX = cool_foo_
164
165 void
166 cool_foo_perl_rules()
167
168 CODE:
169 fprintf(stderr, "Cool::Foo says: Perl Rules\n");
170
171 Bar.xs:
172 -------
173 #include "EXTERN.h"
174 #include "perl.h"
175 #include "XSUB.h"
176
177 MODULE = Cool::Bar PACKAGE = Cool::Bar PREFIX = cool_bar_
178
179 void
180 cool_bar_perl_rules()
181
182 CODE:
183 fprintf(stderr, "Cool::Bar says: Perl Rules\n");
184
185And of course a very basic test:
186
187 test.pl:
188 --------
189 use Test;
190 BEGIN { plan tests => 1 };
191 use Cool::Foo;
192 use Cool::Bar;
193 Cool::Foo::perl_rules();
194 Cool::Bar::perl_rules();
195 ok 1;
196
197This tip has been brought to you by Nick Ing-Simmons and Stas Bekman.
198
199=back
200
201=head1 PATCHING
202
203If you have a question you'd like to see added to the FAQ (whether or
204not you have the answer) please send it to makemaker@perl.org.
205
206=head1 AUTHOR
207
208The denizens of makemaker@perl.org.
209
210=head1 SEE ALSO
211
212L<ExtUtils::MakeMaker>
213
214=cut