This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
ExtUtils::MakeMaker 6.03 -> 6.06_05ish
[perl5.git] / lib / ExtUtils / MakeMaker / FAQ.pod
CommitLineData
479d2113
MS
1package ExtUtils::MakeMaker::FAQ;
2
3our $VERSION = '0.02';
4
51;
6__END__
7
8=head1 NAME
9
10ExtUtils::MakeMaker::FAQ - Frequently Asked Questions About MakeMaker
11
12=head1 DESCRIPTION
13
14FAQs, 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
22Why did MakeMaker reinvent the build configuration wheel? Why not
23just use autoconf or automake or ppm or Ant or ...
24
25There are many reasons, but the major one is cross-platform
26compatibility.
27
28Perl is one of the most ported pieces of software ever. It works on
29operating systems I've never even heard of (see perlport for details).
30It needs a build tool that can work on all those platforms and with
31any wacky C compilers they might have.
32
33No 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
39Module::Build is a project by Ken Williams to supplant MakeMaker.
40Its 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
54Module::Build is the official heir apparent to MakeMaker and we
55encourage people to work on M::B rather than spending time improving
56MakeMaker.
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
66Sometimes you need to have two and more XS files in the same package.
67One way to go is to put them into separate directories, but sometimes
68this is not the most suitable solution. The following technique allows
69you to put two (and more) XS files in the same directory.
70
71Let's assume that we have a package C<Cool::Foo>, which includes
72C<Cool::Foo> and C<Cool::Bar> modules each having a separate XS
73file. 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
84Notice the C<OBJECT> attribute. MakeMaker generates the following
85variables 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
95Therefore we can use the C<O_FILES> variable to tell MakeMaker to use
96these objects into the shared library.
97
98That's pretty much it. Now write I<Foo.pm> and I<Foo.xs>, I<Bar.pm>
99and I<Bar.xs>, where I<Foo.pm> bootstraps the shared library and
100I<Bar.pm> simply loading I<Foo.pm>.
101
102The only issue left is to how to bootstrap I<Bar.xs>. This is done
103from 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
111If you have more than two files, this is the place where you should
112boot extra XS files from.
113
114The 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
170And 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
182This tip has been brought to you by Nick Ing-Simmons and Stas Bekman.
183
184=back
185
186=head1 PATCHING
187
188If you have a question you'd like to see added to the FAQ (whether or
189not you have the answer) please send it to makemaker@perl.org.
190
191=head1 AUTHOR
192
193The denizens of makemaker@perl.org.
194
195=head1 SEE ALSO
196
197L<ExtUtils::MakeMaker>
198
199=cut