Commit | Line | Data |
---|---|---|
86530b38 AT |
1 | package ExtUtils::MakeMaker::FAQ; |
2 | ||
3 | (our $VERSION) = sprintf "%03d", q$Revision: 1.10 $ =~ /Revision:\s+(\S+)/; | |
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 | ||
16 | ||
17 | =head2 Module Installation | |
18 | ||
19 | =over 4 | |
20 | ||
21 | =item How do I keep from installing man pages? | |
22 | ||
23 | Recent versions of MakeMaker will only install man pages on Unix like | |
24 | operating systems. | |
25 | ||
26 | For an individual module: | |
27 | ||
28 | perl Makefile.PL INSTALLMAN1DIR=none INSTALLMAN3DIR=none | |
29 | ||
30 | If you want to suppress man page installation for all modules you have | |
31 | to reconfigure Perl and tell it 'none' when it asks where to install | |
32 | man pages. | |
33 | ||
34 | ||
35 | =item How do I use a module without installing it? | |
36 | ||
37 | Two 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 | |
43 | blib/lib and blib/arch directories. | |
44 | ||
45 | The other is to install the module in a temporary location. | |
46 | ||
47 | perl Makefile.PL PREFIX=/tmp LIB=/tmp/lib/perl | |
48 | ||
49 | And then set PERL5LIB to /tmp/lib/perl. This works well when you have | |
50 | multiple modules to work with. It also ensures that the module goes | |
51 | through its full installation process which may modify it. | |
52 | ||
53 | =back | |
54 | ||
55 | ||
56 | =head2 Philosophy and History | |
57 | ||
58 | =over 4 | |
59 | ||
60 | =item Why not just use <insert other build config tool here>? | |
61 | ||
62 | Why did MakeMaker reinvent the build configuration wheel? Why not | |
63 | just use autoconf or automake or ppm or Ant or ... | |
64 | ||
65 | There are many reasons, but the major one is cross-platform | |
66 | compatibility. | |
67 | ||
68 | Perl is one of the most ported pieces of software ever. It works on | |
69 | operating systems I've never even heard of (see perlport for details). | |
70 | It needs a build tool that can work on all those platforms and with | |
71 | any wacky C compilers and linkers they might have. | |
72 | ||
73 | No such build tool exists. Even make itself has wildly different | |
74 | dialects. So we have to build our own. | |
75 | ||
76 | ||
77 | =item What is Module::Build and how does it relate to MakeMaker? | |
78 | ||
79 | Module::Build is a project by Ken Williams to supplant MakeMaker. | |
80 | Its 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 | ||
94 | Module::Build is the official heir apparent to MakeMaker and we | |
95 | encourage people to work on M::B rather than spending time adding features | |
96 | to MakeMaker. | |
97 | ||
98 | =back | |
99 | ||
100 | ||
101 | =head2 Module Writing | |
102 | ||
103 | =over 4 | |
104 | ||
105 | =item How do I keep my $VERSION up to date without resetting it manually? | |
106 | ||
107 | Often you want to manually set the $VERSION in the main module | |
108 | distribution because this is the version that everybody sees on CPAN | |
109 | and maybe you want to customize it a bit. But for all the other | |
110 | modules in your dist, $VERSION is really just bookkeeping and all that's | |
111 | important is it goes up every time the module is changed. Doing this | |
112 | by hand is a pain and you often forget. | |
113 | ||
114 | Simplest way to do it automatically is to use your version control | |
115 | system's revision number (you are using version control, right?). | |
116 | ||
117 | In CVS and RCS you use $Z<>Revision$ writing it like so: | |
118 | ||
119 | $VERSION = sprintf "%d.%03d", q$Revision: 1.10 $ =~ /(\d+)/g; | |
120 | ||
121 | Every time the file is checked in the $Z<>Revision$ will be updated, | |
122 | updating your $VERSION. | |
123 | ||
124 | In CVS version 1.9 is followed by 1.10. Since CPAN compares version | |
125 | numbers numerically we use a sprintf() to convert 1.9 to 1.009 and | |
126 | 1.10 to 1.010 which compare properly. | |
127 | ||
128 | If branches are involved (ie. $Z<>Revision: 1.5.3.4) its a little more | |
129 | complicated. | |
130 | ||
131 | # must be all on one line or MakeMaker will get confused. | |
132 | $VERSION = do { my @r = (q$Revision: 1.10 $ =~ /\d+/g); sprintf "%d."."%03d" x $#r, @r }; | |
133 | ||
134 | =item What's this F<META.yml> thing and how did it get in my F<MANIFEST>?! | |
135 | ||
136 | F<META.yml> is a module meta-data file pioneered by Module::Build and | |
137 | automatically generated as part of the 'distdir' target (and thus | |
138 | 'dist'). See L<ExtUtils::MakeMaker/"Module Meta-Data">. | |
139 | ||
140 | To shut off its generation, pass the C<NO_META> flag to C<WriteMakefile()>. | |
141 | ||
142 | =back | |
143 | ||
144 | =head2 XS | |
145 | ||
146 | =over 4 | |
147 | ||
148 | =item How to I prevent "object version X.XX does not match bootstrap parameter Y.YY" errors? | |
149 | ||
150 | XS code is very sensitive to the module version number and will | |
151 | complain if the version number in your Perl module doesn't match. If | |
152 | you change your module's version # without reruning Makefile.PL the old | |
153 | version number will remain in the Makefile causing the XS code to be built | |
154 | with the wrong number. | |
155 | ||
156 | To avoid this, you can force the Makefile to be rebuilt whenever you | |
157 | change the module containing the version number by adding this to your | |
158 | WriteMakefile() arguments. | |
159 | ||
160 | depend => { '$(FIRST_MAKEFILE)' => '$(VERSION_FROM)' } | |
161 | ||
162 | ||
163 | =item How do I make two or more XS files coexist in the same directory? | |
164 | ||
165 | Sometimes you need to have two and more XS files in the same package. | |
166 | One way to go is to put them into separate directories, but sometimes | |
167 | this is not the most suitable solution. The following technique allows | |
168 | you to put two (and more) XS files in the same directory. | |
169 | ||
170 | Let's assume that we have a package C<Cool::Foo>, which includes | |
171 | C<Cool::Foo> and C<Cool::Bar> modules each having a separate XS | |
172 | file. 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 | ||
183 | Notice the C<OBJECT> attribute. MakeMaker generates the following | |
184 | variables 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 | ||
194 | Therefore we can use the C<O_FILES> variable to tell MakeMaker to use | |
195 | these objects into the shared library. | |
196 | ||
197 | That's pretty much it. Now write I<Foo.pm> and I<Foo.xs>, I<Bar.pm> | |
198 | and I<Bar.xs>, where I<Foo.pm> bootstraps the shared library and | |
199 | I<Bar.pm> simply loading I<Foo.pm>. | |
200 | ||
201 | The only issue left is to how to bootstrap I<Bar.xs>. This is done | |
202 | from 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 | ||
210 | If you have more than two files, this is the place where you should | |
211 | boot extra XS files from. | |
212 | ||
213 | The 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 | ||
269 | And 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 | ||
281 | This tip has been brought to you by Nick Ing-Simmons and Stas Bekman. | |
282 | ||
283 | =back | |
284 | ||
285 | =head1 PATCHING | |
286 | ||
287 | If you have a question you'd like to see added to the FAQ (whether or | |
288 | not you have the answer) please send it to makemaker@perl.org. | |
289 | ||
290 | =head1 AUTHOR | |
291 | ||
292 | The denizens of makemaker@perl.org. | |
293 | ||
294 | =head1 SEE ALSO | |
295 | ||
296 | L<ExtUtils::MakeMaker> | |
297 | ||
298 | =cut |