Commit | Line | Data |
479d2113 |
1 | package ExtUtils::MakeMaker::FAQ; |
2 | |
2530b651 |
3 | (our $VERSION) = sprintf "%03d", q$Revision: 1.6 $ =~ /Revision:\s+(\S+)/; |
479d2113 |
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 | =head2 Philosophy and History |
17 | |
18 | =over 4 |
19 | |
20 | =item Why not just use <insert other build config tool here>? |
21 | |
22 | Why did MakeMaker reinvent the build configuration wheel? Why not |
23 | just use autoconf or automake or ppm or Ant or ... |
24 | |
25 | There are many reasons, but the major one is cross-platform |
26 | compatibility. |
27 | |
28 | Perl is one of the most ported pieces of software ever. It works on |
29 | operating systems I've never even heard of (see perlport for details). |
30 | It needs a build tool that can work on all those platforms and with |
31 | any wacky C compilers they might have. |
32 | |
33 | No 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 | |
39 | Module::Build is a project by Ken Williams to supplant MakeMaker. |
40 | Its 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 | |
54 | Module::Build is the official heir apparent to MakeMaker and we |
55 | encourage people to work on M::B rather than spending time improving |
56 | MakeMaker. |
57 | |
58 | =back |
59 | |
2530b651 |
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 | |
66 | Often you want to manually set the $VERSION in the main module |
67 | distribution because this is the version that everybody sees on CPAN |
68 | and maybe you want to customize it a bit. But for all the other |
69 | modules in your dist, $VERSION is really just bookkeeping and all that's |
70 | important is it goes up every time the module is changed. Doing this |
71 | by hand is a pain and you often forget. |
72 | |
73 | Simplest way to do it automatically is to use your version control |
74 | system's revision number (you are using version control, right?). |
75 | |
76 | In 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 | |
80 | On your next check in, $Revision: 1.6 $ will magically be expanded to contain |
81 | the current revision #. |
82 | |
83 | $VERSION = sprintf "%d.%03d", q$Revision: 1.6 $ =~ /(\d+)/g; |
84 | |
85 | Every time the file is checked in the $Revision: 1.6 $ will be updated, |
86 | updating your $VERSION. |
87 | |
88 | In CVS version 1.9 is followed by 1.10. Since CPAN compares version |
89 | numbers numerically we use a sprintf() to convert 1.9 to 1.009 and |
90 | 1.10 to 1.010 which compare properly. |
91 | |
92 | If branches are involved (ie. $Revision: 1.5.3.4) its a little more |
93 | complicated. |
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 |
101 | =head2 XS |
102 | |
103 | =over 4 |
104 | |
dedf98bc |
105 | =item How to I prevent "object version X.XX does not match bootstrap parameter Y.YY" errors? |
106 | |
107 | XS code is very sensitive to the module version number and will |
108 | complain if the version number in your Perl module doesn't match. If |
109 | you change your module's version # without reruning Makefile.PL the old |
110 | version number will remain in the Makefile causing the XS code to be built |
111 | with the wrong number. |
112 | |
113 | To avoid this, you can force the Makefile to be rebuilt whenever you |
114 | change the module containing the version number by adding this to your |
115 | WriteMakefile() arguments. |
116 | |
117 | depend => { '$(FIRST_MAKEFILE)' => '$(VERSION_FROM)' } |
118 | |
119 | |
479d2113 |
120 | =item How do I make two or more XS files coexist in the same directory? |
121 | |
122 | Sometimes you need to have two and more XS files in the same package. |
123 | One way to go is to put them into separate directories, but sometimes |
124 | this is not the most suitable solution. The following technique allows |
125 | you to put two (and more) XS files in the same directory. |
126 | |
127 | Let's assume that we have a package C<Cool::Foo>, which includes |
128 | C<Cool::Foo> and C<Cool::Bar> modules each having a separate XS |
129 | file. 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 | |
140 | Notice the C<OBJECT> attribute. MakeMaker generates the following |
141 | variables 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 | |
151 | Therefore we can use the C<O_FILES> variable to tell MakeMaker to use |
152 | these objects into the shared library. |
153 | |
154 | That's pretty much it. Now write I<Foo.pm> and I<Foo.xs>, I<Bar.pm> |
155 | and I<Bar.xs>, where I<Foo.pm> bootstraps the shared library and |
156 | I<Bar.pm> simply loading I<Foo.pm>. |
157 | |
158 | The only issue left is to how to bootstrap I<Bar.xs>. This is done |
159 | from 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 | |
167 | If you have more than two files, this is the place where you should |
168 | boot extra XS files from. |
169 | |
170 | The 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 | |
226 | And 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 | |
238 | This tip has been brought to you by Nick Ing-Simmons and Stas Bekman. |
239 | |
240 | =back |
241 | |
242 | =head1 PATCHING |
243 | |
244 | If you have a question you'd like to see added to the FAQ (whether or |
245 | not you have the answer) please send it to makemaker@perl.org. |
246 | |
247 | =head1 AUTHOR |
248 | |
249 | The denizens of makemaker@perl.org. |
250 | |
251 | =head1 SEE ALSO |
252 | |
253 | L<ExtUtils::MakeMaker> |
254 | |
255 | =cut |