mingw/html/lib/ExtUtils/MakeMaker/FAQ.html

   1 <?xml version="1.0" ?>
   2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
   3 <html xmlns="http://www.w3.org/1999/xhtml">
   4 <head>
   5 <title>ExtUtils::MakeMaker::FAQ - Frequently Asked Questions About MakeMaker</title>
   6 <meta http-equiv="content-type" content="text/html; charset=utf-8" />
   7 <link rev="made" href="mailto:" />
   8 </head>
   9
  10 <body style="background-color: white">
  11 <table border="0" width="100%" cellspacing="0" cellpadding="3">
  12 <tr><td class="block" style="background-color: #cccccc" valign="middle">
  13 <big><strong><span class="block">&nbsp;ExtUtils::MakeMaker::FAQ - Frequently Asked Questions About MakeMaker</span></strong></big>
  14 </td></tr>
  15 </table>
  16
  17 <p><a name="__index__"></a></p>
  18 <!-- INDEX BEGIN -->
  19
  20 <ul>
  21
  22         <li><a href="#name">NAME</a></li>
  23         <li><a href="#description">DESCRIPTION</a></li>
  24         <ul>
  25
  26                 <li><a href="#module_installation">Module Installation</a></li>
  27                 <li><a href="#philosophy_and_history">Philosophy and History</a></li>
  28                 <li><a href="#module_writing">Module Writing</a></li>
  29                 <li><a href="#xs">XS</a></li>
  30         </ul>
  31
  32         <li><a href="#patching">PATCHING</a></li>
  33         <li><a href="#author">AUTHOR</a></li>
  34         <li><a href="#see_also">SEE ALSO</a></li>
  35 </ul>
  36 <!-- INDEX END -->
  37
  38 <hr />
  39 <p>
  40 </p>
  41 <h1><a name="name">NAME</a></h1>
  42 <p>ExtUtils::MakeMaker::FAQ - Frequently Asked Questions About MakeMaker</p>
  43 <p>
  44 </p>
  45 <hr />
  46 <h1><a name="description">DESCRIPTION</a></h1>
  47 <p>FAQs, tricks and tips for <code>ExtUtils::MakeMaker</code>.</p>
  48 <p>
  49 </p>
  50 <h2><a name="module_installation">Module Installation</a></h2>
  51 <dl>
  52 <dt><strong><a name="item_how_do_i_keep_from_installing_man_pages_3f">How do I keep from installing man pages?</a></strong>
  53
  54 <dd>
  55 <p>Recent versions of MakeMaker will only install man pages on Unix like
  56 operating systems.</p>
  57 </dd>
  58 <dd>
  59 <p>For an individual module:</p>
  60 </dd>
  61 <dd>
  62 <pre>
  63         perl Makefile.PL INSTALLMAN1DIR=none INSTALLMAN3DIR=none</pre>
  64 </dd>
  65 <dd>
  66 <p>If you want to suppress man page installation for all modules you have
  67 to reconfigure Perl and tell it 'none' when it asks where to install
  68 man pages.</p>
  69 </dd>
  70 </li>
  71 <dt><strong><a name="item_how_do_i_use_a_module_without_installing_it_3f">How do I use a module without installing it?</a></strong>
  72
  73 <dd>
  74 <p>Two ways.  One is to build the module normally...</p>
  75 </dd>
  76 <dd>
  77 <pre>
  78         perl Makefile.PL
  79         make</pre>
  80 </dd>
  81 <dd>
  82 <p>...and then set the PERL5LIB environment variable to point at the
  83 blib/lib and blib/arch directories.</p>
  84 </dd>
  85 <dd>
  86 <p>The other is to install the module in a temporary location.</p>
  87 </dd>
  88 <dd>
  89 <pre>
  90         perl Makefile.PL PREFIX=~/tmp LIB=~/tmp/lib/perl</pre>
  91 </dd>
  92 <dd>
  93 <p>And then set PERL5LIB to <em>~/tmp/lib/perl</em>.  This works well when you have
  94 multiple modules to work with.  It also ensures that the module goes
  95 through its full installation process which may modify it.</p>
  96 </dd>
  97 </li>
  98 </dl>
  99 <p>
 100 </p>
 101 <h2><a name="philosophy_and_history">Philosophy and History</a></h2>
 102 <dl>
 103 <dt><strong><a name="item_why_not_just_use__3cinsert_other_build_config_tool">Why not just use &lt;insert other build config tool here&gt;?</a></strong>
 104
 105 <dd>
 106 <p>Why did MakeMaker reinvent the build configuration wheel?  Why not
 107 just use autoconf or automake or ppm or Ant or ...</p>
 108 </dd>
 109 <dd>
 110 <p>There are many reasons, but the major one is cross-platform
 111 compatibility.</p>
 112 </dd>
 113 <dd>
 114 <p>Perl is one of the most ported pieces of software ever.  It works on
 115 operating systems I've never even heard of (see perlport for details).
 116 It needs a build tool that can work on all those platforms and with
 117 any wacky C compilers and linkers they might have.</p>
 118 </dd>
 119 <dd>
 120 <p>No such build tool exists.  Even make itself has wildly different
 121 dialects.  So we have to build our own.</p>
 122 </dd>
 123 </li>
 124 <dt><strong><a name="item_what_is_module_3a_3abuild_and_how_does_it_relate_t">What is Module::Build and how does it relate to MakeMaker?</a></strong>
 125
 126 <dd>
 127 <p>Module::Build is a project by Ken Williams to supplant MakeMaker.
 128 Its primary advantages are:</p>
 129 </dd>
 130 <ul>
 131 <li><strong><a name="item_pure_perl_2e_no_make_2c_no_shell_commands">pure perl.  no make, no shell commands</a></strong>
 132
 133 <li><strong><a name="item_easier_to_customize">easier to customize</a></strong>
 134
 135 <li><strong><a name="item_cleaner_internals">cleaner internals</a></strong>
 136
 137 <li><strong><a name="item_less_cruft">less cruft</a></strong>
 138
 139 </ul>
 140 <p>Module::Build is the official heir apparent to MakeMaker and we
 141 encourage people to work on M::B rather than spending time adding features
 142 to MakeMaker.</p>
 143 </dl>
 144 <p>
 145 </p>
 146 <h2><a name="module_writing">Module Writing</a></h2>
 147 <dl>
 148 <dt><strong><a name="item_how_do_i_keep_my__24version_up_to_date_without_res">How do I keep my $VERSION up to date without resetting it manually?</a></strong>
 149
 150 <dd>
 151 <p>Often you want to manually set the $VERSION in the main module
 152 distribution because this is the version that everybody sees on CPAN
 153 and maybe you want to customize it a bit.  But for all the other
 154 modules in your dist, $VERSION is really just bookkeeping and all that's
 155 important is it goes up every time the module is changed.  Doing this
 156 by hand is a pain and you often forget.</p>
 157 </dd>
 158 <dd>
 159 <p>Simplest way to do it automatically is to use your version control
 160 system's revision number (you are using version control, right?).</p>
 161 </dd>
 162 <dd>
 163 <p>In CVS, RCS and SVN you use $Revision$ (see the documentation of your
 164 version control system for details) writing it like so:</p>
 165 </dd>
 166 <dd>
 167 <pre>
 168     $VERSION = sprintf &quot;%d.%03d&quot;, q$Revision$ =~ /(\d+)/g;</pre>
 169 </dd>
 170 <dd>
 171 <p>Every time the file is checked in the $Revision$ will be updated,
 172 updating your $VERSION.</p>
 173 </dd>
 174 <dd>
 175 <p>In CVS version 1.9 is followed by 1.10.  Since CPAN compares version
 176 numbers numerically we use a <code>sprintf()</code> to convert 1.9 to 1.009 and
 177 1.10 to 1.010 which compare properly.</p>
 178 </dd>
 179 <dd>
 180 <p>If branches are involved (ie. $Revision: 1.5.3.4$) its a little more
 181 complicated.</p>
 182 </dd>
 183 <dd>
 184 <pre>
 185     # must be all on one line or MakeMaker will get confused.
 186     $VERSION = do { my @r = (q$Revision$ =~ /\d+/g); sprintf &quot;%d.&quot;.&quot;%03d&quot; x $#r, @r };</pre>
 187 </dd>
 188 </li>
 189 <dt><strong><a name="item_what_27s_this_meta_2eyml_thing_and_how_did_it_get_">What's this <em>META.yml</em> thing and how did it get in my <em>MANIFEST</em>?!</a></strong>
 190
 191 <dd>
 192 <p><em>META.yml</em> is a module meta-data file pioneered by Module::Build and
 193 automatically generated as part of the 'distdir' target (and thus
 194 'dist').  See <a href="file://C|\msysgit\mingw\html/lib/ExtUtils/MakeMaker.html#module_metadata">Module Meta-Data in the ExtUtils::MakeMaker manpage</a>.</p>
 195 </dd>
 196 <dd>
 197 <p>To shut off its generation, pass the <code>NO_META</code> flag to <code>WriteMakefile()</code>.</p>
 198 </dd>
 199 </li>
 200 </dl>
 201 <p>
 202 </p>
 203 <h2><a name="xs">XS</a></h2>
 204 <dl>
 205 <dt><strong><a name="item_how_to_i_prevent__22object_version_x_2exx_does_not">How to I prevent ``object version X.XX does not match bootstrap parameter Y.YY'' errors?</a></strong>
 206
 207 <dd>
 208 <p>XS code is very sensitive to the module version number and will
 209 complain if the version number in your Perl module doesn't match.  If
 210 you change your module's version # without reruning Makefile.PL the old
 211 version number will remain in the Makefile causing the XS code to be built
 212 with the wrong number.</p>
 213 </dd>
 214 <dd>
 215 <p>To avoid this, you can force the Makefile to be rebuilt whenever you
 216 change the module containing the version number by adding this to your
 217 <code>WriteMakefile()</code> arguments.</p>
 218 </dd>
 219 <dd>
 220 <pre>
 221     depend =&gt; { '$(FIRST_MAKEFILE)' =&gt; '$(VERSION_FROM)' }</pre>
 222 </dd>
 223 </li>
 224 <dt><strong><a name="item_how_do_i_make_two_or_more_xs_files_coexist_in_the_">How do I make two or more XS files coexist in the same directory?</a></strong>
 225
 226 <dd>
 227 <p>Sometimes you need to have two and more XS files in the same package.
 228 One way to go is to put them into separate directories, but sometimes
 229 this is not the most suitable solution. The following technique allows
 230 you to put two (and more) XS files in the same directory.</p>
 231 </dd>
 232 <dd>
 233 <p>Let's assume that we have a package <code>Cool::Foo</code>, which includes
 234 <code>Cool::Foo</code> and <code>Cool::Bar</code> modules each having a separate XS
 235 file. First we use the following <em>Makefile.PL</em>:</p>
 236 </dd>
 237 <dd>
 238 <pre>
 239   use ExtUtils::MakeMaker;</pre>
 240 </dd>
 241 <dd>
 242 <pre>
 243   WriteMakefile(
 244       NAME              =&gt; 'Cool::Foo',
 245       VERSION_FROM      =&gt; 'Foo.pm',
 246       OBJECT              =&gt; q/$(O_FILES)/,
 247       # ... other attrs ...
 248   );</pre>
 249 </dd>
 250 <dd>
 251 <p>Notice the <code>OBJECT</code> attribute. MakeMaker generates the following
 252 variables in <em>Makefile</em>:</p>
 253 </dd>
 254 <dd>
 255 <pre>
 256   # Handy lists of source code files:
 257   XS_FILES= Bar.xs \
 258         Foo.xs
 259   C_FILES = Bar.c \
 260         Foo.c
 261   O_FILES = Bar.o \
 262         Foo.o</pre>
 263 </dd>
 264 <dd>
 265 <p>Therefore we can use the <code>O_FILES</code> variable to tell MakeMaker to use
 266 these objects into the shared library.</p>
 267 </dd>
 268 <dd>
 269 <p>That's pretty much it. Now write <em>Foo.pm</em> and <em>Foo.xs</em>, <em>Bar.pm</em>
 270 and <em>Bar.xs</em>, where <em>Foo.pm</em> bootstraps the shared library and
 271 <em>Bar.pm</em> simply loading <em>Foo.pm</em>.</p>
 272 </dd>
 273 <dd>
 274 <p>The only issue left is to how to bootstrap <em>Bar.xs</em>. This is done
 275 from <em>Foo.xs</em>:</p>
 276 </dd>
 277 <dd>
 278 <pre>
 279   MODULE = Cool::Foo PACKAGE = Cool::Foo</pre>
 280 </dd>
 281 <dd>
 282 <pre>
 283   BOOT:
 284   # boot the second XS file
 285   boot_Cool__Bar(aTHX_ cv);</pre>
 286 </dd>
 287 <dd>
 288 <p>If you have more than two files, this is the place where you should
 289 boot extra XS files from.</p>
 290 </dd>
 291 <dd>
 292 <p>The following four files sum up all the details discussed so far.</p>
 293 </dd>
 294 <dd>
 295 <pre>
 296   Foo.pm:
 297   -------
 298   package Cool::Foo;</pre>
 299 </dd>
 300 <dd>
 301 <pre>
 302   require DynaLoader;</pre>
 303 </dd>
 304 <dd>
 305 <pre>
 306   our @ISA = qw(DynaLoader);
 307   our $VERSION = '0.01';
 308   bootstrap Cool::Foo $VERSION;</pre>
 309 </dd>
 310 <dd>
 311 <pre>
 312   1;</pre>
 313 </dd>
 314 <dd>
 315 <pre>
 316   Bar.pm:
 317   -------
 318   package Cool::Bar;</pre>
 319 </dd>
 320 <dd>
 321 <pre>
 322   use Cool::Foo; # bootstraps Bar.xs</pre>
 323 </dd>
 324 <dd>
 325 <pre>
 326   1;</pre>
 327 </dd>
 328 <dd>
 329 <pre>
 330   Foo.xs:
 331   -------
 332   #include &quot;EXTERN.h&quot;
 333   #include &quot;perl.h&quot;
 334   #include &quot;XSUB.h&quot;</pre>
 335 </dd>
 336 <dd>
 337 <pre>
 338   MODULE = Cool::Foo  PACKAGE = Cool::Foo</pre>
 339 </dd>
 340 <dd>
 341 <pre>
 342   BOOT:
 343   # boot the second XS file
 344   boot_Cool__Bar(aTHX_ cv);</pre>
 345 </dd>
 346 <dd>
 347 <pre>
 348   MODULE = Cool::Foo  PACKAGE = Cool::Foo  PREFIX = cool_foo_</pre>
 349 </dd>
 350 <dd>
 351 <pre>
 352   void
 353   cool_foo_perl_rules()</pre>
 354 </dd>
 355 <dd>
 356 <pre>
 357       CODE:
 358       fprintf(stderr, &quot;Cool::Foo says: Perl Rules\n&quot;);</pre>
 359 </dd>
 360 <dd>
 361 <pre>
 362   Bar.xs:
 363   -------
 364   #include &quot;EXTERN.h&quot;
 365   #include &quot;perl.h&quot;
 366   #include &quot;XSUB.h&quot;</pre>
 367 </dd>
 368 <dd>
 369 <pre>
 370   MODULE = Cool::Bar  PACKAGE = Cool::Bar PREFIX = cool_bar_</pre>
 371 </dd>
 372 <dd>
 373 <pre>
 374   void
 375   cool_bar_perl_rules()</pre>
 376 </dd>
 377 <dd>
 378 <pre>
 379       CODE:
 380       fprintf(stderr, &quot;Cool::Bar says: Perl Rules\n&quot;);</pre>
 381 </dd>
 382 <dd>
 383 <p>And of course a very basic test:</p>
 384 </dd>
 385 <dd>
 386 <pre>
 387   test.pl:
 388   --------
 389   use Test;
 390   BEGIN { plan tests =&gt; 1 };
 391   use Cool::Foo;
 392   use Cool::Bar;
 393   Cool::Foo::perl_rules();
 394   Cool::Bar::perl_rules();
 395   ok 1;</pre>
 396 </dd>
 397 <dd>
 398 <p>This tip has been brought to you by Nick Ing-Simmons and Stas Bekman.</p>
 399 </dd>
 400 </li>
 401 </dl>
 402 <p>
 403 </p>
 404 <hr />
 405 <h1><a name="patching">PATCHING</a></h1>
 406 <p>If you have a question you'd like to see added to the FAQ (whether or
 407 not you have the answer) please send it to <a href="mailto:makemaker@perl.org.">makemaker@perl.org.</a></p>
 408 <p>
 409 </p>
 410 <hr />
 411 <h1><a name="author">AUTHOR</a></h1>
 412 <p>The denizens of <a href="mailto:makemaker@perl.org.">makemaker@perl.org.</a></p>
 413 <p>
 414 </p>
 415 <hr />
 416 <h1><a name="see_also">SEE ALSO</a></h1>
 417 <p><a href="file://C|\msysgit\mingw\html/lib/ExtUtils/MakeMaker.html">the ExtUtils::MakeMaker manpage</a></p>
 418 <table border="0" width="100%" cellspacing="0" cellpadding="3">
 419 <tr><td class="block" style="background-color: #cccccc" valign="middle">
 420 <big><strong><span class="block">&nbsp;ExtUtils::MakeMaker::FAQ - Frequently Asked Questions About MakeMaker</span></strong></big>
 421 </td></tr>
 422 </table>
 423
 424 </body>
 425
 426 </html>