| 1 |
.\" -*- mode: troff; coding: utf-8 -*- |
| 2 |
.\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45) |
| 3 |
.\" |
| 4 |
.\" Standard preamble: |
| 5 |
.\" ======================================================================== |
| 6 |
.de Sp \" Vertical space (when we can't use .PP) |
| 7 |
.if t .sp .5v |
| 8 |
.if n .sp |
| 9 |
.. |
| 10 |
.de Vb \" Begin verbatim text |
| 11 |
.ft CW |
| 12 |
.nf |
| 13 |
.ne \\$1 |
| 14 |
.. |
| 15 |
.de Ve \" End verbatim text |
| 16 |
.ft R |
| 17 |
.fi |
| 18 |
.. |
| 19 |
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. |
| 20 |
.ie n \{\ |
| 21 |
. ds C` "" |
| 22 |
. ds C' "" |
| 23 |
'br\} |
| 24 |
.el\{\ |
| 25 |
. ds C` |
| 26 |
. ds C' |
| 27 |
'br\} |
| 28 |
.\" |
| 29 |
.\" Escape single quotes in literal strings from groff's Unicode transform. |
| 30 |
.ie \n(.g .ds Aq \(aq |
| 31 |
.el .ds Aq ' |
| 32 |
.\" |
| 33 |
.\" If the F register is >0, we'll generate index entries on stderr for |
| 34 |
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index |
| 35 |
.\" entries marked with X<> in POD. Of course, you'll have to process the |
| 36 |
.\" output yourself in some meaningful fashion. |
| 37 |
.\" |
| 38 |
.\" Avoid warning from groff about undefined register 'F'. |
| 39 |
.de IX |
| 40 |
.. |
| 41 |
.nr rF 0 |
| 42 |
.if \n(.g .if rF .nr rF 1 |
| 43 |
.if (\n(rF:(\n(.g==0)) \{\ |
| 44 |
. if \nF \{\ |
| 45 |
. de IX |
| 46 |
. tm Index:\\$1\t\\n%\t"\\$2" |
| 47 |
.. |
| 48 |
. if !\nF==2 \{\ |
| 49 |
. nr % 0 |
| 50 |
. nr F 2 |
| 51 |
. \} |
| 52 |
. \} |
| 53 |
.\} |
| 54 |
.rr rF |
| 55 |
.\" ======================================================================== |
| 56 |
.\" |
| 57 |
.IX Title "ExtUtils::MakeMaker::FAQ 3perl" |
| 58 |
.TH ExtUtils::MakeMaker::FAQ 3perl 2025-11-16 "perl v5.40.1" "Perl Programmers Reference Guide" |
| 59 |
.\" For nroff, turn off justification. Always turn off hyphenation; it makes |
| 60 |
.\" way too many mistakes in technical documents. |
| 61 |
.if n .ad l |
| 62 |
.nh |
| 63 |
.SH NAME |
| 64 |
ExtUtils::MakeMaker::FAQ \- Frequently Asked Questions About MakeMaker |
| 65 |
.SH DESCRIPTION |
| 66 |
.IX Header "DESCRIPTION" |
| 67 |
FAQs, tricks and tips for ExtUtils::MakeMaker. |
| 68 |
.SS "Module Installation" |
| 69 |
.IX Subsection "Module Installation" |
| 70 |
.IP "How do I install a module into my home directory?" 4 |
| 71 |
.IX Item "How do I install a module into my home directory?" |
| 72 |
If you're not the Perl administrator you probably don't have |
| 73 |
permission to install a module to its default location. Ways of handling |
| 74 |
this with a \fBlot\fR less manual effort on your part are perlbrew |
| 75 |
and local::lib. |
| 76 |
.Sp |
| 77 |
Otherwise, you can install it for your own use into your home directory |
| 78 |
like so: |
| 79 |
.Sp |
| 80 |
.Vb 2 |
| 81 |
\& # Non\-unix folks, replace ~ with /path/to/your/home/dir |
| 82 |
\& perl Makefile.PL INSTALL_BASE=~ |
| 83 |
.Ve |
| 84 |
.Sp |
| 85 |
This will put modules into \fI~/lib/perl5\fR, man pages into \fI~/man\fR and |
| 86 |
programs into \fI~/bin\fR. |
| 87 |
.Sp |
| 88 |
To ensure your Perl programs can see these newly installed modules, |
| 89 |
set your \f(CW\*(C`PERL5LIB\*(C'\fR environment variable to \fI~/lib/perl5\fR or tell |
| 90 |
each of your programs to look in that directory with the following: |
| 91 |
.Sp |
| 92 |
.Vb 1 |
| 93 |
\& use lib "$ENV{HOME}/lib/perl5"; |
| 94 |
.Ve |
| 95 |
.Sp |
| 96 |
or if \f(CW$ENV\fR{HOME} isn't set and you don't want to set it for some |
| 97 |
reason, do it the long way. |
| 98 |
.Sp |
| 99 |
.Vb 1 |
| 100 |
\& use lib "/path/to/your/home/dir/lib/perl5"; |
| 101 |
.Ve |
| 102 |
.IP "How do I get MakeMaker and Module::Build to install to the same place?" 4 |
| 103 |
.IX Item "How do I get MakeMaker and Module::Build to install to the same place?" |
| 104 |
Module::Build, as of 0.28, supports two ways to install to the same |
| 105 |
location as MakeMaker. |
| 106 |
.Sp |
| 107 |
We highly recommend the install_base method, its the simplest and most |
| 108 |
closely approximates the expected behavior of an installation prefix. |
| 109 |
.Sp |
| 110 |
1) Use INSTALL_BASE / \f(CW\*(C`\-\-install_base\*(C'\fR |
| 111 |
.Sp |
| 112 |
MakeMaker (as of 6.31) and Module::Build (as of 0.28) both can install |
| 113 |
to the same locations using the "install_base" concept. See |
| 114 |
"INSTALL_BASE" in ExtUtils::MakeMaker for details. To get MM and MB to |
| 115 |
install to the same location simply set INSTALL_BASE in MM and |
| 116 |
\&\f(CW\*(C`\-\-install_base\*(C'\fR in MB to the same location. |
| 117 |
.Sp |
| 118 |
.Vb 2 |
| 119 |
\& perl Makefile.PL INSTALL_BASE=/whatever |
| 120 |
\& perl Build.PL \-\-install_base /whatever |
| 121 |
.Ve |
| 122 |
.Sp |
| 123 |
This works most like other language's behavior when you specify a |
| 124 |
prefix. We recommend this method. |
| 125 |
.Sp |
| 126 |
2) Use PREFIX / \f(CW\*(C`\-\-prefix\*(C'\fR |
| 127 |
.Sp |
| 128 |
Module::Build 0.28 added support for \f(CW\*(C`\-\-prefix\*(C'\fR which works like |
| 129 |
MakeMaker's PREFIX. |
| 130 |
.Sp |
| 131 |
.Vb 2 |
| 132 |
\& perl Makefile.PL PREFIX=/whatever |
| 133 |
\& perl Build.PL \-\-prefix /whatever |
| 134 |
.Ve |
| 135 |
.Sp |
| 136 |
We highly discourage this method. It should only be used if you know |
| 137 |
what you're doing and specifically need the PREFIX behavior. The |
| 138 |
PREFIX algorithm is complicated and focused on matching the system |
| 139 |
installation. |
| 140 |
.IP "How do I keep from installing man pages?" 4 |
| 141 |
.IX Item "How do I keep from installing man pages?" |
| 142 |
Recent versions of MakeMaker will only install man pages on Unix-like |
| 143 |
operating systems by default. To generate manpages on non-Unix operating |
| 144 |
systems, make the "manifypods" target. |
| 145 |
.Sp |
| 146 |
For an individual module: |
| 147 |
.Sp |
| 148 |
.Vb 1 |
| 149 |
\& perl Makefile.PL INSTALLMAN1DIR=none INSTALLMAN3DIR=none |
| 150 |
.Ve |
| 151 |
.Sp |
| 152 |
If you want to suppress man page installation for all modules you have |
| 153 |
to reconfigure Perl and tell it 'none' when it asks where to install |
| 154 |
man pages. |
| 155 |
.IP "How do I use a module without installing it?" 4 |
| 156 |
.IX Item "How do I use a module without installing it?" |
| 157 |
Two ways. One is to build the module normally... |
| 158 |
.Sp |
| 159 |
.Vb 3 |
| 160 |
\& perl Makefile.PL |
| 161 |
\& make |
| 162 |
\& make test |
| 163 |
.Ve |
| 164 |
.Sp |
| 165 |
\&...and then use blib to point Perl at the built but uninstalled module: |
| 166 |
.Sp |
| 167 |
.Vb 2 |
| 168 |
\& perl \-Mblib script.pl |
| 169 |
\& perl \-Mblib \-e \*(Aq...\*(Aq |
| 170 |
.Ve |
| 171 |
.Sp |
| 172 |
The other is to install the module in a temporary location. |
| 173 |
.Sp |
| 174 |
.Vb 4 |
| 175 |
\& perl Makefile.PL INSTALL_BASE=~/tmp |
| 176 |
\& make |
| 177 |
\& make test |
| 178 |
\& make install |
| 179 |
.Ve |
| 180 |
.Sp |
| 181 |
And then set PERL5LIB to \fI~/tmp/lib/perl5\fR. This works well when you |
| 182 |
have multiple modules to work with. It also ensures that the module |
| 183 |
goes through its full installation process which may modify it. |
| 184 |
Again, local::lib may assist you here. |
| 185 |
.IP "How can I organize tests into subdirectories and have them run?" 4 |
| 186 |
.IX Item "How can I organize tests into subdirectories and have them run?" |
| 187 |
Let's take the following test directory structure: |
| 188 |
.Sp |
| 189 |
.Vb 3 |
| 190 |
\& t/foo/sometest.t |
| 191 |
\& t/bar/othertest.t |
| 192 |
\& t/bar/baz/anothertest.t |
| 193 |
.Ve |
| 194 |
.Sp |
| 195 |
Now, inside of the \f(CWWriteMakefile()\fR function in your \fIMakefile.PL\fR, specify |
| 196 |
where your tests are located with the \f(CW\*(C`test\*(C'\fR directive: |
| 197 |
.Sp |
| 198 |
.Vb 1 |
| 199 |
\& test => {TESTS => \*(Aqt/*.t t/*/*.t t/*/*/*.t\*(Aq} |
| 200 |
.Ve |
| 201 |
.Sp |
| 202 |
The first entry in the string will run all tests in the top-level \fIt/\fR |
| 203 |
directory. The second will run all test files located in any subdirectory under |
| 204 |
\&\fIt/\fR. The third, runs all test files within any subdirectory within any other |
| 205 |
subdirectory located under \fIt/\fR. |
| 206 |
.Sp |
| 207 |
Note that you do not have to use wildcards. You can specify explicitly which |
| 208 |
subdirectories to run tests in: |
| 209 |
.Sp |
| 210 |
.Vb 1 |
| 211 |
\& test => {TESTS => \*(Aqt/*.t t/foo/*.t t/bar/baz/*.t\*(Aq} |
| 212 |
.Ve |
| 213 |
.IP "PREFIX vs INSTALL_BASE from Module::Build::Cookbook" 4 |
| 214 |
.IX Item "PREFIX vs INSTALL_BASE from Module::Build::Cookbook" |
| 215 |
The behavior of PREFIX is complicated and depends closely on how your |
| 216 |
Perl is configured. The resulting installation locations will vary |
| 217 |
from machine to machine and even different installations of Perl on the |
| 218 |
same machine. Because of this, its difficult to document where prefix |
| 219 |
will place your modules. |
| 220 |
.Sp |
| 221 |
In contrast, INSTALL_BASE has predictable, easy to explain installation |
| 222 |
locations. Now that Module::Build and MakeMaker both have INSTALL_BASE |
| 223 |
there is little reason to use PREFIX other than to preserve your existing |
| 224 |
installation locations. If you are starting a fresh Perl installation we |
| 225 |
encourage you to use INSTALL_BASE. If you have an existing installation |
| 226 |
installed via PREFIX, consider moving it to an installation structure |
| 227 |
matching INSTALL_BASE and using that instead. |
| 228 |
.ie n .IP "Generating *.pm files with substitutions eg of $VERSION" 4 |
| 229 |
.el .IP "Generating *.pm files with substitutions eg of \f(CW$VERSION\fR" 4 |
| 230 |
.IX Item "Generating *.pm files with substitutions eg of $VERSION" |
| 231 |
If you want to configure your module files for local conditions, or to |
| 232 |
automatically insert a version number, you can use EUMM's \f(CW\*(C`PL_FILES\*(C'\fR |
| 233 |
capability, where it will automatically run each \fI*.PL\fR it finds to |
| 234 |
generate its basename. For instance: |
| 235 |
.Sp |
| 236 |
.Vb 10 |
| 237 |
\& # Makefile.PL: |
| 238 |
\& require \*(Aqcommon.pl\*(Aq; |
| 239 |
\& my $version = get_version(); |
| 240 |
\& my @pms = qw(Foo.pm); |
| 241 |
\& WriteMakefile( |
| 242 |
\& NAME => \*(AqFoo\*(Aq, |
| 243 |
\& VERSION => $version, |
| 244 |
\& PM => { map { ($_ => "\e$(INST_LIB)/$_") } @pms }, |
| 245 |
\& clean => { FILES => join \*(Aq \*(Aq, @pms }, |
| 246 |
\& ); |
| 247 |
\& |
| 248 |
\& # common.pl: |
| 249 |
\& sub get_version { \*(Aq0.04\*(Aq } |
| 250 |
\& sub process { my $v = get_version(); s/_\|_VERSION_\|_/$v/g; } |
| 251 |
\& 1; |
| 252 |
\& |
| 253 |
\& # Foo.pm.PL: |
| 254 |
\& require \*(Aqcommon.pl\*(Aq; |
| 255 |
\& $_ = join \*(Aq\*(Aq, <DATA>; |
| 256 |
\& process(); |
| 257 |
\& my $file = shift; |
| 258 |
\& open my $fh, \*(Aq>\*(Aq, $file or die "$file: $!"; |
| 259 |
\& print $fh $_; |
| 260 |
\& _\|_DATA_\|_ |
| 261 |
\& package Foo; |
| 262 |
\& our $VERSION = \*(Aq_\|_VERSION_\|_\*(Aq; |
| 263 |
\& 1; |
| 264 |
.Ve |
| 265 |
.Sp |
| 266 |
You may notice that \f(CW\*(C`PL_FILES\*(C'\fR is not specified above, since the default |
| 267 |
of mapping each .PL file to its basename works well. |
| 268 |
.Sp |
| 269 |
If the generated module were architecture-specific, you could replace |
| 270 |
\&\f(CW\*(C`$(INST_LIB)\*(C'\fR above with \f(CW\*(C`$(INST_ARCHLIB)\*(C'\fR, although if you locate |
| 271 |
modules under \fIlib\fR, that would involve ensuring any \f(CW\*(C`lib/\*(C'\fR in front |
| 272 |
of the module location were removed. |
| 273 |
.SS "Common errors and problems" |
| 274 |
.IX Subsection "Common errors and problems" |
| 275 |
.IP """No rule to make target `/usr/lib/perl5/CORE/config.h', needed by `Makefile'""" 4 |
| 276 |
.IX Item """No rule to make target `/usr/lib/perl5/CORE/config.h', needed by `Makefile'""" |
| 277 |
Just what it says, you're missing that file. MakeMaker uses it to |
| 278 |
determine if perl has been rebuilt since the Makefile was made. It's |
| 279 |
a bit of a bug that it halts installation. |
| 280 |
.Sp |
| 281 |
Some operating systems don't ship the CORE directory with their base |
| 282 |
perl install. To solve the problem, you likely need to install a perl |
| 283 |
development package such as perl-devel (CentOS, Fedora and other |
| 284 |
Redhat systems) or perl (Ubuntu and other Debian systems). |
| 285 |
.SS "Philosophy and History" |
| 286 |
.IX Subsection "Philosophy and History" |
| 287 |
.IP "Why not just use <insert other build config tool here>?" 4 |
| 288 |
.IX Item "Why not just use <insert other build config tool here>?" |
| 289 |
Why did MakeMaker reinvent the build configuration wheel? Why not |
| 290 |
just use autoconf or automake or ppm or Ant or ... |
| 291 |
.Sp |
| 292 |
There are many reasons, but the major one is cross-platform |
| 293 |
compatibility. |
| 294 |
.Sp |
| 295 |
Perl is one of the most ported pieces of software ever. It works on |
| 296 |
operating systems I've never even heard of (see perlport for details). |
| 297 |
It needs a build tool that can work on all those platforms and with |
| 298 |
any wacky C compilers and linkers they might have. |
| 299 |
.Sp |
| 300 |
No such build tool exists. Even make itself has wildly different |
| 301 |
dialects. So we have to build our own. |
| 302 |
.IP "What is Module::Build and how does it relate to MakeMaker?" 4 |
| 303 |
.IX Item "What is Module::Build and how does it relate to MakeMaker?" |
| 304 |
Module::Build is a project by Ken Williams to supplant MakeMaker. |
| 305 |
Its primary advantages are: |
| 306 |
.RS 4 |
| 307 |
.IP \(bu 8 |
| 308 |
pure perl. no make, no shell commands |
| 309 |
.IP \(bu 8 |
| 310 |
easier to customize |
| 311 |
.IP \(bu 8 |
| 312 |
cleaner internals |
| 313 |
.IP \(bu 8 |
| 314 |
less cruft |
| 315 |
.RE |
| 316 |
.RS 4 |
| 317 |
.Sp |
| 318 |
Module::Build was long the official heir apparent to MakeMaker. The |
| 319 |
rate of both its development and adoption has slowed in recent years, |
| 320 |
though, and it is unclear what the future holds for it. That said, |
| 321 |
Module::Build set the stage for \fIsomething\fR to become the heir to |
| 322 |
MakeMaker. MakeMaker's maintainers have long said that it is a dead |
| 323 |
end and should be kept functioning, while being cautious about extending |
| 324 |
with new features. |
| 325 |
.RE |
| 326 |
.SS "Module Writing" |
| 327 |
.IX Subsection "Module Writing" |
| 328 |
.ie n .IP "How do I keep my $VERSION up to date without resetting it manually?" 4 |
| 329 |
.el .IP "How do I keep my \f(CW$VERSION\fR up to date without resetting it manually?" 4 |
| 330 |
.IX Item "How do I keep my $VERSION up to date without resetting it manually?" |
| 331 |
Often you want to manually set the \f(CW$VERSION\fR in the main module |
| 332 |
distribution because this is the version that everybody sees on CPAN |
| 333 |
and maybe you want to customize it a bit. But for all the other |
| 334 |
modules in your dist, \f(CW$VERSION\fR is really just bookkeeping and all that's |
| 335 |
important is it goes up every time the module is changed. Doing this |
| 336 |
by hand is a pain and you often forget. |
| 337 |
.Sp |
| 338 |
Probably the easiest way to do this is using \fIperl-reversion\fR in |
| 339 |
Perl::Version: |
| 340 |
.Sp |
| 341 |
.Vb 1 |
| 342 |
\& perl\-reversion \-bump |
| 343 |
.Ve |
| 344 |
.Sp |
| 345 |
If your version control system supports revision numbers (git doesn't |
| 346 |
easily), the simplest way to do it automatically is to use its revision |
| 347 |
number (you are using version control, right?). |
| 348 |
.Sp |
| 349 |
In CVS, RCS and SVN you use \f(CW$Revision\fR$ (see the documentation of your |
| 350 |
version control system for details). Every time the file is checked |
| 351 |
in the \f(CW$Revision\fR$ will be updated, updating your \f(CW$VERSION\fR. |
| 352 |
.Sp |
| 353 |
SVN uses a simple integer for \f(CW$Revision\fR$ so you can adapt it for your |
| 354 |
\&\f(CW$VERSION\fR like so: |
| 355 |
.Sp |
| 356 |
.Vb 1 |
| 357 |
\& ($VERSION) = q$Revision$ =~ /(\ed+)/; |
| 358 |
.Ve |
| 359 |
.Sp |
| 360 |
In CVS and RCS version 1.9 is followed by 1.10. Since CPAN compares |
| 361 |
version numbers numerically we use a \fBsprintf()\fR to convert 1.9 to 1.009 |
| 362 |
and 1.10 to 1.010 which compare properly. |
| 363 |
.Sp |
| 364 |
.Vb 1 |
| 365 |
\& $VERSION = sprintf "%d.%03d", q$Revision$ =~ /(\ed+)\e.(\ed+)/g; |
| 366 |
.Ve |
| 367 |
.Sp |
| 368 |
If branches are involved (ie. \f(CW$Revision:\fR 1.5.3.4$) it's a little more |
| 369 |
complicated. |
| 370 |
.Sp |
| 371 |
.Vb 2 |
| 372 |
\& # must be all on one line or MakeMaker will get confused. |
| 373 |
\& $VERSION = do { my @r = (q$Revision$ =~ /\ed+/g); sprintf "%d."."%03d" x $#r, @r }; |
| 374 |
.Ve |
| 375 |
.Sp |
| 376 |
In SVN, \f(CW$Revision\fR$ should be the same for every file in the project so |
| 377 |
they would all have the same \f(CW$VERSION\fR. CVS and RCS have a different |
| 378 |
\&\f(CW$Revision\fR$ per file so each file will have a different \f(CW$VERSION\fR. |
| 379 |
Distributed version control systems, such as SVK, may have a different |
| 380 |
\&\f(CW$Revision\fR$ based on who checks out the file, leading to a different \f(CW$VERSION\fR |
| 381 |
on each machine! Finally, some distributed version control systems, such |
| 382 |
as darcs, have no concept of revision number at all. |
| 383 |
.IP "What's this \fIMETA.yml\fR thing and how did it get in my \fIMANIFEST\fR?!" 4 |
| 384 |
.IX Item "What's this META.yml thing and how did it get in my MANIFEST?!" |
| 385 |
\&\fIMETA.yml\fR is a module meta-data file pioneered by Module::Build and |
| 386 |
automatically generated as part of the 'distdir' target (and thus |
| 387 |
\&'dist'). See "Module Meta-Data" in ExtUtils::MakeMaker. |
| 388 |
.Sp |
| 389 |
To shut off its generation, pass the \f(CW\*(C`NO_META\*(C'\fR flag to \f(CWWriteMakefile()\fR. |
| 390 |
.IP "How do I delete everything not in my \fIMANIFEST\fR?" 4 |
| 391 |
.IX Item "How do I delete everything not in my MANIFEST?" |
| 392 |
Some folks are surprised that \f(CW\*(C`make distclean\*(C'\fR does not delete |
| 393 |
everything not listed in their MANIFEST (thus making a clean |
| 394 |
distribution) but only tells them what they need to delete. This is |
| 395 |
done because it is considered too dangerous. While developing your |
| 396 |
module you might write a new file, not add it to the MANIFEST, then |
| 397 |
run a \f(CW\*(C`distclean\*(C'\fR and be sad because your new work was deleted. |
| 398 |
.Sp |
| 399 |
If you really want to do this, you can use |
| 400 |
\&\f(CWExtUtils::Manifest::manifind()\fR to read the MANIFEST and File::Find |
| 401 |
to delete the files. But you have to be careful. Here's a script to |
| 402 |
do that. Use at your own risk. Have fun blowing holes in your foot. |
| 403 |
.Sp |
| 404 |
.Vb 1 |
| 405 |
\& #!/usr/bin/perl \-w |
| 406 |
\& |
| 407 |
\& use strict; |
| 408 |
\& |
| 409 |
\& use File::Spec; |
| 410 |
\& use File::Find; |
| 411 |
\& use ExtUtils::Manifest qw(maniread); |
| 412 |
\& |
| 413 |
\& my %manifest = map {( $_ => 1 )} |
| 414 |
\& grep { File::Spec\->canonpath($_) } |
| 415 |
\& keys %{ maniread() }; |
| 416 |
\& |
| 417 |
\& if( !keys %manifest ) { |
| 418 |
\& print "No files found in MANIFEST. Stopping.\en"; |
| 419 |
\& exit; |
| 420 |
\& } |
| 421 |
\& |
| 422 |
\& find({ |
| 423 |
\& wanted => sub { |
| 424 |
\& my $path = File::Spec\->canonpath($_); |
| 425 |
\& |
| 426 |
\& return unless \-f $path; |
| 427 |
\& return if exists $manifest{ $path }; |
| 428 |
\& |
| 429 |
\& print "unlink $path\en"; |
| 430 |
\& unlink $path; |
| 431 |
\& }, |
| 432 |
\& no_chdir => 1 |
| 433 |
\& }, |
| 434 |
\& "." |
| 435 |
\& ); |
| 436 |
.Ve |
| 437 |
.IP "Which tar should I use on Windows?" 4 |
| 438 |
.IX Item "Which tar should I use on Windows?" |
| 439 |
We recommend ptar from Archive::Tar not older than 1.66 with '\-C' option. |
| 440 |
.IP "Which zip should I use on Windows for '[ndg]make zipdist'?" 4 |
| 441 |
.IX Item "Which zip should I use on Windows for '[ndg]make zipdist'?" |
| 442 |
We recommend InfoZIP: <http://www.info\-zip.org/Zip.html> |
| 443 |
.SS XS |
| 444 |
.IX Subsection "XS" |
| 445 |
.IP "How do I prevent ""object version X.XX does not match bootstrap parameter Y.YY"" errors?" 4 |
| 446 |
.IX Item "How do I prevent ""object version X.XX does not match bootstrap parameter Y.YY"" errors?" |
| 447 |
XS code is very sensitive to the module version number and will |
| 448 |
complain if the version number in your Perl module doesn't match. If |
| 449 |
you change your module's version # without rerunning Makefile.PL the old |
| 450 |
version number will remain in the Makefile, causing the XS code to be built |
| 451 |
with the wrong number. |
| 452 |
.Sp |
| 453 |
To avoid this, you can force the Makefile to be rebuilt whenever you |
| 454 |
change the module containing the version number by adding this to your |
| 455 |
\&\fBWriteMakefile()\fR arguments. |
| 456 |
.Sp |
| 457 |
.Vb 1 |
| 458 |
\& depend => { \*(Aq$(FIRST_MAKEFILE)\*(Aq => \*(Aq$(VERSION_FROM)\*(Aq } |
| 459 |
.Ve |
| 460 |
.IP "How do I make two or more XS files coexist in the same directory?" 4 |
| 461 |
.IX Item "How do I make two or more XS files coexist in the same directory?" |
| 462 |
Sometimes you need to have two and more XS files in the same package. |
| 463 |
There are three ways: \f(CW\*(C`XSMULTI\*(C'\fR, separate directories, and bootstrapping |
| 464 |
one XS from another. |
| 465 |
.RS 4 |
| 466 |
.IP XSMULTI 8 |
| 467 |
.IX Item "XSMULTI" |
| 468 |
Structure your modules so they are all located under \fIlib\fR, such that |
| 469 |
\&\f(CW\*(C`Foo::Bar\*(C'\fR is in \fIlib/Foo/Bar.pm\fR and \fIlib/Foo/Bar.xs\fR, etc. Have your |
| 470 |
top-level \f(CW\*(C`WriteMakefile\*(C'\fR set the variable \f(CW\*(C`XSMULTI\*(C'\fR to a true value. |
| 471 |
.Sp |
| 472 |
Er, that's it. |
| 473 |
.IP "Separate directories" 8 |
| 474 |
.IX Item "Separate directories" |
| 475 |
Put each XS files into separate directories, each with their own |
| 476 |
\&\fIMakefile.PL\fR. Make sure each of those \fIMakefile.PL\fRs has the correct |
| 477 |
\&\f(CW\*(C`CFLAGS\*(C'\fR, \f(CW\*(C`INC\*(C'\fR, \f(CW\*(C`LIBS\*(C'\fR etc. You will need to make sure the top-level |
| 478 |
\&\fIMakefile.PL\fR refers to each of these using \f(CW\*(C`DIR\*(C'\fR. |
| 479 |
.IP Bootstrapping 8 |
| 480 |
.IX Item "Bootstrapping" |
| 481 |
Let's assume that we have a package \f(CW\*(C`Cool::Foo\*(C'\fR, which includes |
| 482 |
\&\f(CW\*(C`Cool::Foo\*(C'\fR and \f(CW\*(C`Cool::Bar\*(C'\fR modules each having a separate XS |
| 483 |
file. First we use the following \fIMakefile.PL\fR: |
| 484 |
.Sp |
| 485 |
.Vb 1 |
| 486 |
\& use ExtUtils::MakeMaker; |
| 487 |
\& |
| 488 |
\& WriteMakefile( |
| 489 |
\& NAME => \*(AqCool::Foo\*(Aq, |
| 490 |
\& VERSION_FROM => \*(AqFoo.pm\*(Aq, |
| 491 |
\& OBJECT => q/$(O_FILES)/, |
| 492 |
\& # ... other attrs ... |
| 493 |
\& ); |
| 494 |
.Ve |
| 495 |
.Sp |
| 496 |
Notice the \f(CW\*(C`OBJECT\*(C'\fR attribute. MakeMaker generates the following |
| 497 |
variables in \fIMakefile\fR: |
| 498 |
.Sp |
| 499 |
.Vb 7 |
| 500 |
\& # Handy lists of source code files: |
| 501 |
\& XS_FILES= Bar.xs \e |
| 502 |
\& Foo.xs |
| 503 |
\& C_FILES = Bar.c \e |
| 504 |
\& Foo.c |
| 505 |
\& O_FILES = Bar.o \e |
| 506 |
\& Foo.o |
| 507 |
.Ve |
| 508 |
.Sp |
| 509 |
Therefore we can use the \f(CW\*(C`O_FILES\*(C'\fR variable to tell MakeMaker to use |
| 510 |
these objects into the shared library. |
| 511 |
.Sp |
| 512 |
That's pretty much it. Now write \fIFoo.pm\fR and \fIFoo.xs\fR, \fIBar.pm\fR |
| 513 |
and \fIBar.xs\fR, where \fIFoo.pm\fR bootstraps the shared library and |
| 514 |
\&\fIBar.pm\fR simply loading \fIFoo.pm\fR. |
| 515 |
.Sp |
| 516 |
The only issue left is to how to bootstrap \fIBar.xs\fR. This is done |
| 517 |
from \fIFoo.xs\fR: |
| 518 |
.Sp |
| 519 |
.Vb 1 |
| 520 |
\& MODULE = Cool::Foo PACKAGE = Cool::Foo |
| 521 |
\& |
| 522 |
\& BOOT: |
| 523 |
\& # boot the second XS file |
| 524 |
\& boot_Cool_\|_Bar(aTHX_ cv); |
| 525 |
.Ve |
| 526 |
.Sp |
| 527 |
If you have more than two files, this is the place where you should |
| 528 |
boot extra XS files from. |
| 529 |
.Sp |
| 530 |
The following four files sum up all the details discussed so far. |
| 531 |
.Sp |
| 532 |
.Vb 3 |
| 533 |
\& Foo.pm: |
| 534 |
\& \-\-\-\-\-\-\- |
| 535 |
\& package Cool::Foo; |
| 536 |
\& |
| 537 |
\& require DynaLoader; |
| 538 |
\& |
| 539 |
\& our @ISA = qw(DynaLoader); |
| 540 |
\& our $VERSION = \*(Aq0.01\*(Aq; |
| 541 |
\& bootstrap Cool::Foo $VERSION; |
| 542 |
\& |
| 543 |
\& 1; |
| 544 |
\& |
| 545 |
\& Bar.pm: |
| 546 |
\& \-\-\-\-\-\-\- |
| 547 |
\& package Cool::Bar; |
| 548 |
\& |
| 549 |
\& use Cool::Foo; # bootstraps Bar.xs |
| 550 |
\& |
| 551 |
\& 1; |
| 552 |
\& |
| 553 |
\& Foo.xs: |
| 554 |
\& \-\-\-\-\-\-\- |
| 555 |
\& #include "EXTERN.h" |
| 556 |
\& #include "perl.h" |
| 557 |
\& #include "XSUB.h" |
| 558 |
\& |
| 559 |
\& MODULE = Cool::Foo PACKAGE = Cool::Foo |
| 560 |
\& |
| 561 |
\& BOOT: |
| 562 |
\& # boot the second XS file |
| 563 |
\& boot_Cool_\|_Bar(aTHX_ cv); |
| 564 |
\& |
| 565 |
\& MODULE = Cool::Foo PACKAGE = Cool::Foo PREFIX = cool_foo_ |
| 566 |
\& |
| 567 |
\& void |
| 568 |
\& cool_foo_perl_rules() |
| 569 |
\& |
| 570 |
\& CODE: |
| 571 |
\& fprintf(stderr, "Cool::Foo says: Perl Rules\en"); |
| 572 |
\& |
| 573 |
\& Bar.xs: |
| 574 |
\& \-\-\-\-\-\-\- |
| 575 |
\& #include "EXTERN.h" |
| 576 |
\& #include "perl.h" |
| 577 |
\& #include "XSUB.h" |
| 578 |
\& |
| 579 |
\& MODULE = Cool::Bar PACKAGE = Cool::Bar PREFIX = cool_bar_ |
| 580 |
\& |
| 581 |
\& void |
| 582 |
\& cool_bar_perl_rules() |
| 583 |
\& |
| 584 |
\& CODE: |
| 585 |
\& fprintf(stderr, "Cool::Bar says: Perl Rules\en"); |
| 586 |
.Ve |
| 587 |
.Sp |
| 588 |
And of course a very basic test: |
| 589 |
.Sp |
| 590 |
.Vb 8 |
| 591 |
\& t/cool.t: |
| 592 |
\& \-\-\-\-\-\-\-\- |
| 593 |
\& use Test::More tests => 1; |
| 594 |
\& use Cool::Foo; |
| 595 |
\& use Cool::Bar; |
| 596 |
\& Cool::Foo::perl_rules(); |
| 597 |
\& Cool::Bar::perl_rules(); |
| 598 |
\& ok 1; |
| 599 |
.Ve |
| 600 |
.Sp |
| 601 |
This tip has been brought to you by Nick Ing-Simmons and Stas Bekman. |
| 602 |
.Sp |
| 603 |
An alternative way to achieve this can be seen in Gtk2::CodeGen |
| 604 |
and Glib::CodeGen. |
| 605 |
.RE |
| 606 |
.RS 4 |
| 607 |
.RE |
| 608 |
.SH DESIGN |
| 609 |
.IX Header "DESIGN" |
| 610 |
.SS "MakeMaker object hierarchy (simplified)" |
| 611 |
.IX Subsection "MakeMaker object hierarchy (simplified)" |
| 612 |
What most people need to know (superclasses on top.) |
| 613 |
.PP |
| 614 |
.Vb 9 |
| 615 |
\& ExtUtils::MM_Any |
| 616 |
\& | |
| 617 |
\& ExtUtils::MM_Unix |
| 618 |
\& | |
| 619 |
\& ExtUtils::MM_{Current OS} |
| 620 |
\& | |
| 621 |
\& ExtUtils::MakeMaker |
| 622 |
\& | |
| 623 |
\& MY |
| 624 |
.Ve |
| 625 |
.PP |
| 626 |
The object actually used is of the class MY which allows you to |
| 627 |
override bits of MakeMaker inside your Makefile.PL by declaring |
| 628 |
\&\fBMY::foo()\fR methods. |
| 629 |
.SS "MakeMaker object hierarchy (real)" |
| 630 |
.IX Subsection "MakeMaker object hierarchy (real)" |
| 631 |
Here's how it really works: |
| 632 |
.PP |
| 633 |
.Vb 10 |
| 634 |
\& ExtUtils::MM_Any |
| 635 |
\& | |
| 636 |
\& ExtUtils::MM_Unix |
| 637 |
\& | |
| 638 |
\& ExtUtils::Liblist::Kid ExtUtils::MM_{Current OS} (if necessary) |
| 639 |
\& | | |
| 640 |
\& ExtUtils::Liblist ExtUtils::MakeMaker | |
| 641 |
\& | | | |
| 642 |
\& | | |\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- |
| 643 |
\& ExtUtils::MM |
| 644 |
\& | | |
| 645 |
\& ExtUtils::MY MM (created by ExtUtils::MM) |
| 646 |
\& | | |
| 647 |
\& MY (created by ExtUtils::MY) | |
| 648 |
\& . | |
| 649 |
\& (mixin) | |
| 650 |
\& . | |
| 651 |
\& PACK### (created each call to ExtUtils::MakeMaker\->new) |
| 652 |
.Ve |
| 653 |
.PP |
| 654 |
NOTE: Yes, this is a mess. See |
| 655 |
<http://archive.develooper.com/[email protected]/msg00134.html> |
| 656 |
for some history. |
| 657 |
.PP |
| 658 |
NOTE: When ExtUtils::MM is loaded it chooses a superclass for MM from |
| 659 |
amongst the ExtUtils::MM_* modules based on the current operating |
| 660 |
system. |
| 661 |
.PP |
| 662 |
NOTE: ExtUtils::MM_{Current OS} represents one of the ExtUtils::MM_* |
| 663 |
modules except ExtUtils::MM_Any chosen based on your operating system. |
| 664 |
.PP |
| 665 |
NOTE: The main object used by MakeMaker is a PACK### object, *not* |
| 666 |
ExtUtils::MakeMaker. It is, effectively, a subclass of MY, |
| 667 |
ExtUtils::MakeMaker, ExtUtils::Liblist and ExtUtils::MM_{Current OS} |
| 668 |
.PP |
| 669 |
NOTE: The methods in MY are simply copied into PACK### rather |
| 670 |
than MY being a superclass of PACK###. I don't remember the rationale. |
| 671 |
.PP |
| 672 |
NOTE: ExtUtils::Liblist should be removed from the inheritance hiearchy |
| 673 |
and simply be called as functions. |
| 674 |
.PP |
| 675 |
NOTE: Modules like File::Spec and Exporter have been omitted for clarity. |
| 676 |
.SS "The MM_* hierarchy" |
| 677 |
.IX Subsection "The MM_* hierarchy" |
| 678 |
.Vb 9 |
| 679 |
\& MM_Win95 MM_NW5 |
| 680 |
\& \e / |
| 681 |
\& MM_BeOS MM_Cygwin MM_OS2 MM_VMS MM_Win32 MM_DOS MM_UWIN |
| 682 |
\& \e | | | / / / |
| 683 |
\& \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- |
| 684 |
\& | | |
| 685 |
\& MM_Unix | |
| 686 |
\& | | |
| 687 |
\& MM_Any |
| 688 |
.Ve |
| 689 |
.PP |
| 690 |
NOTE: Each direct MM_Unix subclass is also an |
| 691 |
MM_Any subclass. This |
| 692 |
is a temporary hack because MM_Unix overrides some MM_Any methods with |
| 693 |
Unix specific code. It allows the non-Unix modules to see the |
| 694 |
original MM_Any implementations. |
| 695 |
.PP |
| 696 |
NOTE: Modules like File::Spec and Exporter have been omitted for clarity. |
| 697 |
.SH PATCHING |
| 698 |
.IX Header "PATCHING" |
| 699 |
If you have a question you'd like to see added to the FAQ (whether or |
| 700 |
not you have the answer) please either: |
| 701 |
.IP \(bu 2 |
| 702 |
make a pull request on the MakeMaker github repository |
| 703 |
.IP \(bu 2 |
| 704 |
raise a issue on the MakeMaker github repository |
| 705 |
.IP \(bu 2 |
| 706 |
file an RT ticket |
| 707 |
.IP \(bu 2 |
| 708 |
email [email protected] |
| 709 |
.SH AUTHOR |
| 710 |
.IX Header "AUTHOR" |
| 711 |
The denizens of [email protected]. |
| 712 |
.SH "SEE ALSO" |
| 713 |
.IX Header "SEE ALSO" |
| 714 |
ExtUtils::MakeMaker |