lib/ExtUtils/MakeMaker/FAQ.pod

   1 package ExtUtils::MakeMaker::FAQ;
   2
   3 (our $VERSION) = sprintf "%03d", q$Revision: 1.7 $ =~ /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 =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
  60 =head2 Module Writing
  61
  62 =over 4
  63
  64 =item
  65
  66 How do I keep my $VERSION up to date without resetting it manually?
  67
  68 Often you want to manually set the $VERSION in the main module
  69 distribution because this is the version that everybody sees on CPAN
  70 and maybe you want to customize it a bit.  But for all the other
  71 modules in your dist, $VERSION is really just bookkeeping and all that's
  72 important is it goes up every time the module is changed.  Doing this
  73 by hand is a pain and you often forget.
  74
  75 Simplest way to do it automatically is to use your version control
  76 system's revision number (you are using version control, right?).
  77
  78 In CVS and RCS you use $Z<>Revision$ writing it like so:
  79
  80     $VERSION = sprintf "%d.%03d", q$Revision$ =~ /(\d+)/g;
  81
  82 On your next check in, $Z<>Revision$ will magically be expanded to contain
  83 the current revision #.
  84
  85     $VERSION = sprintf "%d.%03d", q$Revision: 1.7 $ =~ /(\d+)/g;
  86
  87 Every time the file is checked in the $Z<>Revision$ will be updated,
  88 updating your $VERSION.
  89
  90 In CVS version 1.9 is followed by 1.10.  Since CPAN compares version
  91 numbers numerically we use a sprintf() to convert 1.9 to 1.009 and
  92 1.10 to 1.010 which compare properly.
  93
  94 If branches are involved (ie. $Z<>Revision: 1.5.3.4) its a little more
  95 complicated.
  96
  97     # must be all on one line or MakeMaker will get confused.
  98     $VERSION = do { my @r = (q$Revision$ =~ /\d+/g); sprintf "%d."."%03d" x $#r, @r };
  99
 100 =item
 101
 102 What's this F<META.yml> thing and how did it get in my F<MANIFEST>?!
 103
 104 F<META.yml> is a module meta-data file pioneered by Module::Build and
 105 automatically generated as part of the 'distdir' target (and thus
 106 'dist').  See L<ExtUtils::MakeMaker/"Module Meta-Data">.
 107
 108 To shut off its generation, pass the C<NO_META> flag to C<WriteMakefile()>.
 109
 110 =back
 111
 112 =head2 XS
 113
 114 =over 4
 115
 116 =item
 117
 118 How to I prevent "object version X.XX does not match bootstrap parameter Y.YY"
 119 errors?
 120
 121 XS code is very sensitive to the module version number and will
 122 complain if the version number in your Perl module doesn't match.  If
 123 you change your module's version # without reruning Makefile.PL the old
 124 version number will remain in the Makefile causing the XS code to be built
 125 with the wrong number.
 126
 127 To avoid this, you can force the Makefile to be rebuilt whenever you
 128 change the module containing the version number by adding this to your
 129 WriteMakefile() arguments.
 130
 131     depend => { '$(FIRST_MAKEFILE)' => '$(VERSION_FROM)' }
 132
 133
 134 =item
 135
 136 How do I make two or more XS files coexist in the same directory?
 137
 138 Sometimes you need to have two and more XS files in the same package.
 139 One way to go is to put them into separate directories, but sometimes
 140 this is not the most suitable solution. The following technique allows
 141 you to put two (and more) XS files in the same directory.
 142
 143 Let's assume that we have a package C<Cool::Foo>, which includes
 144 C<Cool::Foo> and C<Cool::Bar> modules each having a separate XS
 145 file. First we use the following I<Makefile.PL>:
 146
 147   use ExtUtils::MakeMaker;
 148
 149   WriteMakefile(
 150       NAME              => 'Cool::Foo',
 151       VERSION_FROM      => 'Foo.pm',
 152       OBJECT              => q/$(O_FILES)/,
 153       # ... other attrs ...
 154   );
 155
 156 Notice the C<OBJECT> attribute. MakeMaker generates the following
 157 variables in I<Makefile>:
 158
 159   # Handy lists of source code files:
 160   XS_FILES= Bar.xs \
 161         Foo.xs
 162   C_FILES = Bar.c \
 163         Foo.c
 164   O_FILES = Bar.o \
 165         Foo.o
 166
 167 Therefore we can use the C<O_FILES> variable to tell MakeMaker to use
 168 these objects into the shared library.
 169
 170 That's pretty much it. Now write I<Foo.pm> and I<Foo.xs>, I<Bar.pm>
 171 and I<Bar.xs>, where I<Foo.pm> bootstraps the shared library and
 172 I<Bar.pm> simply loading I<Foo.pm>.
 173
 174 The only issue left is to how to bootstrap I<Bar.xs>. This is done
 175 from I<Foo.xs>:
 176
 177   MODULE = Cool::Foo PACKAGE = Cool::Foo
 178
 179   BOOT:
 180   # boot the second XS file
 181   boot_Cool__Bar(aTHX_ cv);
 182
 183 If you have more than two files, this is the place where you should
 184 boot extra XS files from.
 185
 186 The following four files sum up all the details discussed so far.
 187
 188   Foo.pm:
 189   -------
 190   package Cool::Foo;
 191
 192   require DynaLoader;
 193
 194   our @ISA = qw(DynaLoader);
 195   our $VERSION = '0.01';
 196   bootstrap Cool::Foo $VERSION;
 197
 198   1;
 199
 200   Bar.pm:
 201   -------
 202   package Cool::Bar;
 203
 204   use Cool::Foo; # bootstraps Bar.xs
 205
 206   1;
 207
 208   Foo.xs:
 209   -------
 210   #include "EXTERN.h"
 211   #include "perl.h"
 212   #include "XSUB.h"
 213
 214   MODULE = Cool::Foo  PACKAGE = Cool::Foo
 215
 216   BOOT:
 217   # boot the second XS file
 218   boot_Cool__Bar(aTHX_ cv);
 219
 220   MODULE = Cool::Foo  PACKAGE = Cool::Foo  PREFIX = cool_foo_
 221
 222   void
 223   cool_foo_perl_rules()
 224
 225       CODE:
 226       fprintf(stderr, "Cool::Foo says: Perl Rules\n");
 227
 228   Bar.xs:
 229   -------
 230   #include "EXTERN.h"
 231   #include "perl.h"
 232   #include "XSUB.h"
 233
 234   MODULE = Cool::Bar  PACKAGE = Cool::Bar PREFIX = cool_bar_
 235
 236   void
 237   cool_bar_perl_rules()
 238
 239       CODE:
 240       fprintf(stderr, "Cool::Bar says: Perl Rules\n");
 241
 242 And of course a very basic test:
 243
 244   test.pl:
 245   --------
 246   use Test;
 247   BEGIN { plan tests => 1 };
 248   use Cool::Foo;
 249   use Cool::Bar;
 250   Cool::Foo::perl_rules();
 251   Cool::Bar::perl_rules();
 252   ok 1;
 253
 254 This tip has been brought to you by Nick Ing-Simmons and Stas Bekman.
 255
 256 =back
 257
 258 =head1 PATCHING
 259
 260 If you have a question you'd like to see added to the FAQ (whether or
 261 not you have the answer) please send it to makemaker@perl.org.
 262
 263 =head1 AUTHOR
 264
 265 The denizens of makemaker@perl.org.
 266
 267 =head1 SEE ALSO
 268
 269 L<ExtUtils::MakeMaker>
 270
 271 =cut