| 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 makemaker@perl.org. |
| 291 | |
| 292 | =head1 AUTHOR |
| 293 | |
| 294 | The denizens of makemaker@perl.org. |
| 295 | |
| 296 | =head1 SEE ALSO |
| 297 | |
| 298 | L<ExtUtils::MakeMaker> |
| 299 | |
| 300 | =cut |