lib/ExtUtils/MakeMaker/FAQ.pod

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