Commit | Line | Data |
479d2113 |
1 | package ExtUtils::MakeMaker::FAQ; |
2 | |
7292dc67 |
3 | use vars qw($VERSION); |
2977d345 |
4 | $VERSION = '1.11_01'; |
479d2113 |
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 | |
03c94fc2 |
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 | |
5dca256e |
48 | perl Makefile.PL PREFIX=~/tmp LIB=~/tmp/lib/perl |
03c94fc2 |
49 | |
5dca256e |
50 | And then set PERL5LIB to F<~/tmp/lib/perl>. This works well when you have |
03c94fc2 |
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 | |
479d2113 |
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 |
03c94fc2 |
72 | any wacky C compilers and linkers they might have. |
479d2113 |
73 | |
03c94fc2 |
74 | No such build tool exists. Even make itself has wildly different |
75 | dialects. So we have to build our own. |
479d2113 |
76 | |
77 | |
03c94fc2 |
78 | =item What is Module::Build and how does it relate to MakeMaker? |
479d2113 |
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 |
03c94fc2 |
96 | encourage people to work on M::B rather than spending time adding features |
97 | to MakeMaker. |
479d2113 |
98 | |
99 | =back |
100 | |
03c94fc2 |
101 | |
2530b651 |
102 | =head2 Module Writing |
103 | |
104 | =over 4 |
105 | |
e3aa3ecb |
106 | =item How do I keep my $VERSION up to date without resetting it manually? |
2530b651 |
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 | |
7292dc67 |
118 | In CVS, RCS and SVN you use $Revision$ (see the documentation of your |
2977d345 |
119 | version control system for details). Every time the file is checked |
120 | in the $Revision$ will be updated, updating your $VERSION. |
2530b651 |
121 | |
2977d345 |
122 | SVN uses a simple integer for $Revision$ so you can adapt it for your |
123 | $VERSION like so: |
2530b651 |
124 | |
2977d345 |
125 | $VERSION = (q$Revision$) =~ /(\d+)/g; |
2530b651 |
126 | |
2977d345 |
127 | In CVS and RCS version 1.9 is followed by 1.10. Since CPAN compares |
128 | version numbers numerically we use a sprintf() to convert 1.9 to 1.009 |
129 | and 1.10 to 1.010 which compare properly. |
130 | |
131 | $VERSION = sprintf "%d.%03d", q$Revision$ =~ /(\d+)\.(\d+)/g; |
2530b651 |
132 | |
7292dc67 |
133 | If branches are involved (ie. $Revision: 1.5.3.4$) its a little more |
2530b651 |
134 | complicated. |
135 | |
136 | # must be all on one line or MakeMaker will get confused. |
7292dc67 |
137 | $VERSION = do { my @r = (q$Revision$ =~ /\d+/g); sprintf "%d."."%03d" x $#r, @r }; |
2530b651 |
138 | |
2977d345 |
139 | In SVN, $Revision$ should be the same for every file in the project so |
140 | they would all have the same $VERSION. CVS and RCS have a different |
141 | $Revision$ per file so each file will have a differnt $VERSION. |
142 | Distributed version control systems, such as SVK, may have a different |
143 | $Revision$ based on who checks out the file leading to a different $VERSION |
144 | on each machine! Finally, some distributed version control systems, such |
145 | as darcs, have no concept of revision number at all. |
146 | |
147 | |
e3aa3ecb |
148 | =item What's this F<META.yml> thing and how did it get in my F<MANIFEST>?! |
c2990482 |
149 | |
150 | F<META.yml> is a module meta-data file pioneered by Module::Build and |
151 | automatically generated as part of the 'distdir' target (and thus |
152 | 'dist'). See L<ExtUtils::MakeMaker/"Module Meta-Data">. |
153 | |
154 | To shut off its generation, pass the C<NO_META> flag to C<WriteMakefile()>. |
2530b651 |
155 | |
156 | =back |
157 | |
479d2113 |
158 | =head2 XS |
159 | |
160 | =over 4 |
161 | |
e3aa3ecb |
162 | =item How to I prevent "object version X.XX does not match bootstrap parameter Y.YY" errors? |
dedf98bc |
163 | |
164 | XS code is very sensitive to the module version number and will |
165 | complain if the version number in your Perl module doesn't match. If |
c2878c71 |
166 | you change your module's version # without rerunning Makefile.PL the old |
dedf98bc |
167 | version number will remain in the Makefile causing the XS code to be built |
168 | with the wrong number. |
169 | |
170 | To avoid this, you can force the Makefile to be rebuilt whenever you |
171 | change the module containing the version number by adding this to your |
172 | WriteMakefile() arguments. |
173 | |
174 | depend => { '$(FIRST_MAKEFILE)' => '$(VERSION_FROM)' } |
175 | |
176 | |
e3aa3ecb |
177 | =item How do I make two or more XS files coexist in the same directory? |
479d2113 |
178 | |
179 | Sometimes you need to have two and more XS files in the same package. |
180 | One way to go is to put them into separate directories, but sometimes |
181 | this is not the most suitable solution. The following technique allows |
182 | you to put two (and more) XS files in the same directory. |
183 | |
184 | Let's assume that we have a package C<Cool::Foo>, which includes |
185 | C<Cool::Foo> and C<Cool::Bar> modules each having a separate XS |
186 | file. First we use the following I<Makefile.PL>: |
187 | |
188 | use ExtUtils::MakeMaker; |
189 | |
190 | WriteMakefile( |
191 | NAME => 'Cool::Foo', |
192 | VERSION_FROM => 'Foo.pm', |
193 | OBJECT => q/$(O_FILES)/, |
194 | # ... other attrs ... |
195 | ); |
196 | |
197 | Notice the C<OBJECT> attribute. MakeMaker generates the following |
198 | variables in I<Makefile>: |
199 | |
200 | # Handy lists of source code files: |
201 | XS_FILES= Bar.xs \ |
202 | Foo.xs |
203 | C_FILES = Bar.c \ |
204 | Foo.c |
205 | O_FILES = Bar.o \ |
206 | Foo.o |
207 | |
208 | Therefore we can use the C<O_FILES> variable to tell MakeMaker to use |
209 | these objects into the shared library. |
210 | |
211 | That's pretty much it. Now write I<Foo.pm> and I<Foo.xs>, I<Bar.pm> |
212 | and I<Bar.xs>, where I<Foo.pm> bootstraps the shared library and |
213 | I<Bar.pm> simply loading I<Foo.pm>. |
214 | |
215 | The only issue left is to how to bootstrap I<Bar.xs>. This is done |
216 | from I<Foo.xs>: |
217 | |
218 | MODULE = Cool::Foo PACKAGE = Cool::Foo |
219 | |
220 | BOOT: |
221 | # boot the second XS file |
222 | boot_Cool__Bar(aTHX_ cv); |
223 | |
224 | If you have more than two files, this is the place where you should |
225 | boot extra XS files from. |
226 | |
227 | The following four files sum up all the details discussed so far. |
228 | |
229 | Foo.pm: |
230 | ------- |
231 | package Cool::Foo; |
232 | |
233 | require DynaLoader; |
234 | |
235 | our @ISA = qw(DynaLoader); |
236 | our $VERSION = '0.01'; |
237 | bootstrap Cool::Foo $VERSION; |
238 | |
239 | 1; |
240 | |
241 | Bar.pm: |
242 | ------- |
243 | package Cool::Bar; |
244 | |
245 | use Cool::Foo; # bootstraps Bar.xs |
246 | |
247 | 1; |
248 | |
249 | Foo.xs: |
250 | ------- |
251 | #include "EXTERN.h" |
252 | #include "perl.h" |
253 | #include "XSUB.h" |
254 | |
255 | MODULE = Cool::Foo PACKAGE = Cool::Foo |
256 | |
257 | BOOT: |
258 | # boot the second XS file |
259 | boot_Cool__Bar(aTHX_ cv); |
260 | |
261 | MODULE = Cool::Foo PACKAGE = Cool::Foo PREFIX = cool_foo_ |
262 | |
263 | void |
264 | cool_foo_perl_rules() |
265 | |
266 | CODE: |
267 | fprintf(stderr, "Cool::Foo says: Perl Rules\n"); |
268 | |
269 | Bar.xs: |
270 | ------- |
271 | #include "EXTERN.h" |
272 | #include "perl.h" |
273 | #include "XSUB.h" |
274 | |
275 | MODULE = Cool::Bar PACKAGE = Cool::Bar PREFIX = cool_bar_ |
276 | |
277 | void |
278 | cool_bar_perl_rules() |
279 | |
280 | CODE: |
281 | fprintf(stderr, "Cool::Bar says: Perl Rules\n"); |
282 | |
283 | And of course a very basic test: |
284 | |
285 | test.pl: |
286 | -------- |
287 | use Test; |
288 | BEGIN { plan tests => 1 }; |
289 | use Cool::Foo; |
290 | use Cool::Bar; |
291 | Cool::Foo::perl_rules(); |
292 | Cool::Bar::perl_rules(); |
293 | ok 1; |
294 | |
295 | This tip has been brought to you by Nick Ing-Simmons and Stas Bekman. |
296 | |
297 | =back |
298 | |
299 | =head1 PATCHING |
300 | |
301 | If you have a question you'd like to see added to the FAQ (whether or |
302 | not you have the answer) please send it to makemaker@perl.org. |
303 | |
304 | =head1 AUTHOR |
305 | |
306 | The denizens of makemaker@perl.org. |
307 | |
308 | =head1 SEE ALSO |
309 | |
310 | L<ExtUtils::MakeMaker> |
311 | |
312 | =cut |