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