lib/ExtUtils/MakeMaker/FAQ.pod

   1 package ExtUtils::MakeMaker::FAQ;
   2
   3 our $VERSION = '0.02';
   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 XS
  61
  62 =over 4
  63
  64 =item How do I make two or more XS files coexist in the same directory?
  65
  66 Sometimes you need to have two and more XS files in the same package.
  67 One way to go is to put them into separate directories, but sometimes
  68 this is not the most suitable solution. The following technique allows
  69 you to put two (and more) XS files in the same directory.
  70
  71 Let's assume that we have a package C<Cool::Foo>, which includes
  72 C<Cool::Foo> and C<Cool::Bar> modules each having a separate XS
  73 file. First we use the following I<Makefile.PL>:
  74
  75   use ExtUtils::MakeMaker;
  76
  77   WriteMakefile(
  78       NAME              => 'Cool::Foo',
  79       VERSION_FROM      => 'Foo.pm',
  80       OBJECT              => q/$(O_FILES)/,
  81       # ... other attrs ...
  82   );
  83
  84 Notice the C<OBJECT> attribute. MakeMaker generates the following
  85 variables in I<Makefile>:
  86
  87   # Handy lists of source code files:
  88   XS_FILES= Bar.xs \
  89         Foo.xs
  90   C_FILES = Bar.c \
  91         Foo.c
  92   O_FILES = Bar.o \
  93         Foo.o
  94
  95 Therefore we can use the C<O_FILES> variable to tell MakeMaker to use
  96 these objects into the shared library.
  97
  98 That's pretty much it. Now write I<Foo.pm> and I<Foo.xs>, I<Bar.pm>
  99 and I<Bar.xs>, where I<Foo.pm> bootstraps the shared library and
 100 I<Bar.pm> simply loading I<Foo.pm>.
 101
 102 The only issue left is to how to bootstrap I<Bar.xs>. This is done
 103 from I<Foo.xs>:
 104
 105   MODULE = Cool::Foo PACKAGE = Cool::Foo
 106
 107   BOOT:
 108   # boot the second XS file
 109   boot_Cool__Bar(aTHX_ cv);
 110
 111 If you have more than two files, this is the place where you should
 112 boot extra XS files from.
 113
 114 The following four files sum up all the details discussed so far.
 115
 116   Foo.pm:
 117   -------
 118   package Cool::Foo;
 119
 120   require DynaLoader;
 121
 122   our @ISA = qw(DynaLoader);
 123   our $VERSION = '0.01';
 124   bootstrap Cool::Foo $VERSION;
 125
 126   1;
 127
 128   Bar.pm:
 129   -------
 130   package Cool::Bar;
 131
 132   use Cool::Foo; # bootstraps Bar.xs
 133
 134   1;
 135
 136   Foo.xs:
 137   -------
 138   #include "EXTERN.h"
 139   #include "perl.h"
 140   #include "XSUB.h"
 141
 142   MODULE = Cool::Foo  PACKAGE = Cool::Foo
 143
 144   BOOT:
 145   # boot the second XS file
 146   boot_Cool__Bar(aTHX_ cv);
 147
 148   MODULE = Cool::Foo  PACKAGE = Cool::Foo  PREFIX = cool_foo_
 149
 150   void
 151   cool_foo_perl_rules()
 152
 153       CODE:
 154       fprintf(stderr, "Cool::Foo says: Perl Rules\n");
 155
 156   Bar.xs:
 157   -------
 158   #include "EXTERN.h"
 159   #include "perl.h"
 160   #include "XSUB.h"
 161
 162   MODULE = Cool::Bar  PACKAGE = Cool::Bar PREFIX = cool_bar_
 163
 164   void
 165   cool_bar_perl_rules()
 166
 167       CODE:
 168       fprintf(stderr, "Cool::Bar says: Perl Rules\n");
 169
 170 And of course a very basic test:
 171
 172   test.pl:
 173   --------
 174   use Test;
 175   BEGIN { plan tests => 1 };
 176   use Cool::Foo;
 177   use Cool::Bar;
 178   Cool::Foo::perl_rules();
 179   Cool::Bar::perl_rules();
 180   ok 1;
 181
 182 This tip has been brought to you by Nick Ing-Simmons and Stas Bekman.
 183
 184 =back
 185
 186 =head1 PATCHING
 187
 188 If you have a question you'd like to see added to the FAQ (whether or
 189 not you have the answer) please send it to makemaker@perl.org.
 190
 191 =head1 AUTHOR
 192
 193 The denizens of makemaker@perl.org.
 194
 195 =head1 SEE ALSO
 196
 197 L<ExtUtils::MakeMaker>
 198
 199 =cut