ExtUtils::MakeMaker::FAQ(3pm)

1ExtUtils::MakeMaker::FAQP(e3rplm)Programmers ReferenceEGxutiUdteils::MakeMaker::FAQ(3pm)
2
3
4

NAME

6       ExtUtils::MakeMaker::FAQ - Frequently Asked Questions About MakeMaker
7

DESCRIPTION

9       FAQs, tricks and tips for "ExtUtils::MakeMaker".
10
11       Module Installation
12
13       How do I keep from installing man pages?
14           Recent versions of MakeMaker will only install man pages on Unix
15           like operating systems.
16
17           For an individual module:
18
19                   perl Makefile.PL INSTALLMAN1DIR=none INSTALLMAN3DIR=none
20
21           If you want to suppress man page installation for all modules you
22           have to reconfigure Perl and tell it 'none' when it asks where to
23           install man pages.
24
25       How do I use a module without installing it?
26           Two ways.  One is to build the module normally...
27
28                   perl Makefile.PL
29                   make
30
31           ...and then set the PERL5LIB environment variable to point at the
32           blib/lib and blib/arch directories.
33
34           The other is to install the module in a temporary location.
35
36                   perl Makefile.PL PREFIX=~/tmp LIB=~/tmp/lib/perl
37
38           And then set PERL5LIB to ~/tmp/lib/perl.  This works well when you
39           have multiple modules to work with.  It also ensures that the mod‐
40           ule goes through its full installation process which may modify it.
41
42       Philosophy and History
43
44       Why not just use <insert other build config tool here>?
45           Why did MakeMaker reinvent the build configuration wheel?  Why not
46           just use autoconf or automake or ppm or Ant or ...
47
48           There are many reasons, but the major one is cross-platform compat‐
49           ibility.
50
51           Perl is one of the most ported pieces of software ever.  It works
52           on operating systems I've never even heard of (see perlport for
53           details).  It needs a build tool that can work on all those plat‐
54           forms and with any wacky C compilers and linkers they might have.
55
56           No such build tool exists.  Even make itself has wildly different
57           dialects.  So we have to build our own.
58
59       What is Module::Build and how does it relate to MakeMaker?
60           Module::Build is a project by Ken Williams to supplant MakeMaker.
61           Its primary advantages are:
62
63           * pure perl.  no make, no shell commands
64           * easier to customize
65           * cleaner internals
66           * less cruft
67
68           Module::Build is the official heir apparent to MakeMaker and we
69           encourage people to work on M::B rather than spending time adding
70           features to MakeMaker.
71
72       Module Writing
73
74       How do I keep my $VERSION up to date without resetting it manually?
75           Often you want to manually set the $VERSION in the main module dis‐
76           tribution because this is the version that everybody sees on CPAN
77           and maybe you want to customize it a bit.  But for all the other
78           modules in your dist, $VERSION is really just bookkeeping and all
79           that's important is it goes up every time the module is changed.
80           Doing this by hand is a pain and you often forget.
81
82           Simplest way to do it automatically is to use your version control
83           system's revision number (you are using version control, right?).
84
85           In CVS, RCS and SVN you use $Revision$ (see the documentation of
86           your version control system for details) writing it like so:
87
88               $VERSION = sprintf "%d.%03d", q$Revision$ =~ /(\d+)/g;
89
90           Every time the file is checked in the $Revision$ will be updated,
91           updating your $VERSION.
92
93           In CVS version 1.9 is followed by 1.10.  Since CPAN compares ver‐
94           sion numbers numerically we use a sprintf() to convert 1.9 to 1.009
95           and 1.10 to 1.010 which compare properly.
96
97           If branches are involved (ie. $Revision: 1.5.3.4$) its a little
98           more complicated.
99
100               # must be all on one line or MakeMaker will get confused.
101               $VERSION = do { my @r = (q$Revision$ =~ /\d+/g); sprintf "%d."."%03d" x $#r, @r };
102
103       What's this META.yml thing and how did it get in my MANIFEST?!
104           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 "Module Meta-Data" in ExtUtils::MakeMaker.
107
108           To shut off its generation, pass the "NO_META" flag to "WriteMake‐
109           file()".
110
111       XS
112
113       How to I prevent "object version X.XX does not match bootstrap parame‐
114       ter Y.YY" errors?
115           XS code is very sensitive to the module version number and will
116           complain if the version number in your Perl module doesn't match.
117           If you change your module's version # without reruning Makefile.PL
118           the old version number will remain in the Makefile causing the XS
119           code to be built with the wrong number.
120
121           To avoid this, you can force the Makefile to be rebuilt whenever
122           you change the module containing the version number by adding this
123           to your WriteMakefile() arguments.
124
125               depend => { '$(FIRST_MAKEFILE)' => '$(VERSION_FROM)' }
126
127       How do I make two or more XS files coexist in the same directory?
128           Sometimes you need to have two and more XS files in the same pack‐
129           age.  One way to go is to put them into separate directories, but
130           sometimes this is not the most suitable solution. The following
131           technique allows you to put two (and more) XS files in the same
132           directory.
133
134           Let's assume that we have a package "Cool::Foo", which includes
135           "Cool::Foo" and "Cool::Bar" modules each having a separate XS file.
136           First we use the following Makefile.PL:
137
138             use ExtUtils::MakeMaker;
139
140             WriteMakefile(
141                 NAME              => 'Cool::Foo',
142                 VERSION_FROM      => 'Foo.pm',
143                 OBJECT              => q/$(O_FILES)/,
144                 # ... other attrs ...
145             );
146
147           Notice the "OBJECT" attribute. MakeMaker generates the following
148           variables in Makefile:
149
150             # Handy lists of source code files:
151             XS_FILES= Bar.xs \
152                   Foo.xs
153             C_FILES = Bar.c \
154                   Foo.c
155             O_FILES = Bar.o \
156                   Foo.o
157
158           Therefore we can use the "O_FILES" variable to tell MakeMaker to
159           use these objects into the shared library.
160
161           That's pretty much it. Now write Foo.pm and Foo.xs, Bar.pm and
162           Bar.xs, where Foo.pm bootstraps the shared library and Bar.pm sim‐
163           ply loading Foo.pm.
164
165           The only issue left is to how to bootstrap Bar.xs. This is done
166           from Foo.xs:
167
168             MODULE = Cool::Foo PACKAGE = Cool::Foo
169
170             BOOT:
171             # boot the second XS file
172             boot_Cool__Bar(aTHX_ cv);
173
174           If you have more than two files, this is the place where you should
175           boot extra XS files from.
176
177           The following four files sum up all the details discussed so far.
178
179             Foo.pm:
180             -------
181             package Cool::Foo;
182
183             require DynaLoader;
184
185             our @ISA = qw(DynaLoader);
186             our $VERSION = '0.01';
187             bootstrap Cool::Foo $VERSION;
188
189             1;
190
191             Bar.pm:
192             -------
193             package Cool::Bar;
194
195             use Cool::Foo; # bootstraps Bar.xs
196
197             1;
198
199             Foo.xs:
200             -------
201             #include "EXTERN.h"
202             #include "perl.h"
203             #include "XSUB.h"
204
205             MODULE = Cool::Foo  PACKAGE = Cool::Foo
206
207             BOOT:
208             # boot the second XS file
209             boot_Cool__Bar(aTHX_ cv);
210
211             MODULE = Cool::Foo  PACKAGE = Cool::Foo  PREFIX = cool_foo_
212
213             void
214             cool_foo_perl_rules()
215
216                 CODE:
217                 fprintf(stderr, "Cool::Foo says: Perl Rules\n");
218
219             Bar.xs:
220             -------
221             #include "EXTERN.h"
222             #include "perl.h"
223             #include "XSUB.h"
224
225             MODULE = Cool::Bar  PACKAGE = Cool::Bar PREFIX = cool_bar_
226
227             void
228             cool_bar_perl_rules()
229
230                 CODE:
231                 fprintf(stderr, "Cool::Bar says: Perl Rules\n");
232
233           And of course a very basic test:
234
235             test.pl:
236             --------
237             use Test;
238             BEGIN { plan tests => 1 };
239             use Cool::Foo;
240             use Cool::Bar;
241             Cool::Foo::perl_rules();
242             Cool::Bar::perl_rules();
243             ok 1;
244
245           This tip has been brought to you by Nick Ing-Simmons and Stas Bek‐
246           man.
247

PATCHING

249       If you have a question you'd like to see added to the FAQ (whether or
250       not you have the answer) please send it to makemaker@perl.org.
251

AUTHOR

253       The denizens of makemaker@perl.org.
254

NAME

DESCRIPTION

PATCHING

AUTHOR

SEE ALSO