Commit | Line | Data |
---|---|---|
6b09c160 YST |
1 | package ExtUtils::CBuilder; |
2 | ||
3 | use File::Spec (); | |
4 | use File::Path (); | |
5 | use File::Basename (); | |
6 | ||
7 | use vars qw($VERSION @ISA); | |
8172cd69 | 8 | $VERSION = '0.2801'; |
6b09c160 YST |
9 | $VERSION = eval $VERSION; |
10 | ||
11 | # Okay, this is the brute-force method of finding out what kind of | |
12 | # platform we're on. I don't know of a systematic way. These values | |
13 | # came from the latest (bleadperl) perlport.pod. | |
14 | ||
15 | my %OSTYPES = qw( | |
16 | aix Unix | |
17 | bsdos Unix | |
18 | dgux Unix | |
19 | dynixptx Unix | |
20 | freebsd Unix | |
21 | linux Unix | |
22 | hpux Unix | |
23 | irix Unix | |
24 | darwin Unix | |
25 | machten Unix | |
26 | next Unix | |
27 | openbsd Unix | |
28 | netbsd Unix | |
29 | dec_osf Unix | |
30 | svr4 Unix | |
31 | svr5 Unix | |
32 | sco_sv Unix | |
33 | unicos Unix | |
34 | unicosmk Unix | |
35 | solaris Unix | |
36 | sunos Unix | |
37 | cygwin Unix | |
38 | os2 Unix | |
92760223 NC |
39 | gnu Unix |
40 | gnukfreebsd Unix | |
df00ff3b | 41 | haiku Unix |
6b09c160 YST |
42 | |
43 | dos Windows | |
44 | MSWin32 Windows | |
45 | ||
46 | os390 EBCDIC | |
47 | os400 EBCDIC | |
48 | posix-bc EBCDIC | |
49 | vmesa EBCDIC | |
50 | ||
51 | MacOS MacOS | |
52 | VMS VMS | |
53 | VOS VOS | |
54 | riscos RiscOS | |
55 | amigaos Amiga | |
56 | mpeix MPEiX | |
57 | ); | |
58 | ||
59 | # We only use this once - don't waste a symbol table entry on it. | |
60 | # More importantly, don't make it an inheritable method. | |
61 | my $load = sub { | |
62 | my $mod = shift; | |
63 | eval "use $mod"; | |
64 | die $@ if $@; | |
65 | @ISA = ($mod); | |
66 | }; | |
67 | ||
68 | { | |
69 | my @package = split /::/, __PACKAGE__; | |
70 | ||
71 | if (grep {-e File::Spec->catfile($_, @package, 'Platform', $^O) . '.pm'} @INC) { | |
72 | $load->(__PACKAGE__ . "::Platform::$^O"); | |
73 | ||
74 | } elsif (exists $OSTYPES{$^O} and | |
75 | grep {-e File::Spec->catfile($_, @package, 'Platform', $OSTYPES{$^O}) . '.pm'} @INC) { | |
76 | $load->(__PACKAGE__ . "::Platform::$OSTYPES{$^O}"); | |
77 | ||
78 | } else { | |
79 | $load->(__PACKAGE__ . "::Base"); | |
80 | } | |
81 | } | |
82 | ||
83 | sub os_type { $OSTYPES{$^O} } | |
84 | ||
85 | 1; | |
86 | __END__ | |
87 | ||
88 | =head1 NAME | |
89 | ||
90 | ExtUtils::CBuilder - Compile and link C code for Perl modules | |
91 | ||
92 | =head1 SYNOPSIS | |
93 | ||
94 | use ExtUtils::CBuilder; | |
95 | ||
96 | my $b = ExtUtils::CBuilder->new(%options); | |
97 | $obj_file = $b->compile(source => 'MyModule.c'); | |
98 | $lib_file = $b->link(objects => $obj_file); | |
99 | ||
100 | =head1 DESCRIPTION | |
101 | ||
102 | This module can build the C portions of Perl modules by invoking the | |
103 | appropriate compilers and linkers in a cross-platform manner. It was | |
104 | motivated by the C<Module::Build> project, but may be useful for other | |
105 | purposes as well. However, it is I<not> intended as a general | |
106 | cross-platform interface to all your C building needs. That would | |
107 | have been a much more ambitious goal! | |
108 | ||
109 | =head1 METHODS | |
110 | ||
111 | =over 4 | |
112 | ||
113 | =item new | |
114 | ||
115 | Returns a new C<ExtUtils::CBuilder> object. A C<config> parameter | |
116 | lets you override C<Config.pm> settings for all operations performed | |
117 | by the object, as in the following example: | |
118 | ||
119 | # Use a different compiler than Config.pm says | |
120 | my $b = ExtUtils::CBuilder->new( config => | |
121 | { ld => 'gcc' } ); | |
122 | ||
ea2e6518 RGS |
123 | A C<quiet> parameter tells C<CBuilder> to not print its C<system()> |
124 | commands before executing them: | |
125 | ||
126 | # Be quieter than normal | |
127 | my $b = ExtUtils::CBuilder->new( quiet => 1 ); | |
128 | ||
6b09c160 YST |
129 | =item have_compiler |
130 | ||
131 | Returns true if the current system has a working C compiler and | |
132 | linker, false otherwise. To determine this, we actually compile and | |
9015f106 DG |
133 | link a sample C library. The sample will be compiled in the system |
134 | tempdir or, if that fails for some reason, in the current directory. | |
6b09c160 | 135 | |
506098d4 DG |
136 | =item have_cplusplus |
137 | ||
138 | Just like have_compiler but for C++ instead of C. | |
139 | ||
6b09c160 YST |
140 | =item compile |
141 | ||
142 | Compiles a C source file and produces an object file. The name of the | |
143 | object file is returned. The source file is specified in a C<source> | |
144 | parameter, which is required; the other parameters listed below are | |
145 | optional. | |
146 | ||
147 | =over 4 | |
148 | ||
149 | =item C<object_file> | |
150 | ||
151 | Specifies the name of the output file to create. Otherwise the | |
152 | C<object_file()> method will be consulted, passing it the name of the | |
153 | C<source> file. | |
154 | ||
155 | =item C<include_dirs> | |
156 | ||
157 | Specifies any additional directories in which to search for header | |
158 | files. May be given as a string indicating a single directory, or as | |
159 | a list reference indicating multiple directories. | |
160 | ||
161 | =item C<extra_compiler_flags> | |
162 | ||
163 | Specifies any additional arguments to pass to the compiler. Should be | |
164 | given as a list reference containing the arguments individually, or if | |
165 | this is not possible, as a string containing all the arguments | |
166 | together. | |
167 | ||
506098d4 DG |
168 | =item C<C++> |
169 | ||
170 | Specifies that the source file is a C++ source file and sets appropriate | |
171 | compiler flags | |
172 | ||
6b09c160 YST |
173 | =back |
174 | ||
175 | The operation of this method is also affected by the | |
345dbb93 | 176 | C<archlibexp>, C<cccdlflags>, C<ccflags>, C<optimize>, and C<cc> |
6b09c160 YST |
177 | entries in C<Config.pm>. |
178 | ||
179 | =item link | |
180 | ||
181 | Invokes the linker to produce a library file from object files. In | |
182 | scalar context, the name of the library file is returned. In list | |
183 | context, the library file and any temporary files created are | |
184 | returned. A required C<objects> parameter contains the name of the | |
185 | object files to process, either in a string (for one object file) or | |
186 | list reference (for one or more files). The following parameters are | |
187 | optional: | |
188 | ||
189 | ||
190 | =over 4 | |
191 | ||
192 | =item lib_file | |
193 | ||
194 | Specifies the name of the output library file to create. Otherwise | |
195 | the C<lib_file()> method will be consulted, passing it the name of | |
196 | the first entry in C<objects>. | |
197 | ||
198 | =item module_name | |
199 | ||
200 | Specifies the name of the Perl module that will be created by linking. | |
201 | On platforms that need to do prelinking (Win32, OS/2, etc.) this is a | |
202 | required parameter. | |
203 | ||
204 | =item extra_linker_flags | |
205 | ||
206 | Any additional flags you wish to pass to the linker. | |
207 | ||
208 | =back | |
209 | ||
210 | On platforms where C<need_prelink()> returns true, C<prelink()> | |
211 | will be called automatically. | |
212 | ||
213 | The operation of this method is also affected by the C<lddlflags>, | |
214 | C<shrpenv>, and C<ld> entries in C<Config.pm>. | |
215 | ||
216 | =item link_executable | |
217 | ||
218 | Invokes the linker to produce an executable file from object files. In | |
219 | scalar context, the name of the executable file is returned. In list | |
220 | context, the executable file and any temporary files created are | |
221 | returned. A required C<objects> parameter contains the name of the | |
222 | object files to process, either in a string (for one object file) or | |
223 | list reference (for one or more files). The optional parameters are | |
224 | the same as C<link> with exception for | |
225 | ||
226 | ||
227 | =over 4 | |
228 | ||
229 | =item exe_file | |
230 | ||
231 | Specifies the name of the output executable file to create. Otherwise | |
232 | the C<exe_file()> method will be consulted, passing it the name of the | |
233 | first entry in C<objects>. | |
234 | ||
235 | =back | |
236 | ||
237 | =item object_file | |
238 | ||
239 | my $object_file = $b->object_file($source_file); | |
240 | ||
241 | Converts the name of a C source file to the most natural name of an | |
242 | output object file to create from it. For instance, on Unix the | |
243 | source file F<foo.c> would result in the object file F<foo.o>. | |
244 | ||
245 | =item lib_file | |
246 | ||
247 | my $lib_file = $b->lib_file($object_file); | |
248 | ||
249 | Converts the name of an object file to the most natural name of a | |
250 | output library file to create from it. For instance, on Mac OS X the | |
251 | object file F<foo.o> would result in the library file F<foo.bundle>. | |
252 | ||
253 | =item exe_file | |
254 | ||
255 | my $exe_file = $b->exe_file($object_file); | |
256 | ||
257 | Converts the name of an object file to the most natural name of an | |
258 | executable file to create from it. For instance, on Mac OS X the | |
259 | object file F<foo.o> would result in the executable file F<foo>, and | |
260 | on Windows it would result in F<foo.exe>. | |
261 | ||
262 | ||
263 | =item prelink | |
264 | ||
265 | On certain platforms like Win32, OS/2, VMS, and AIX, it is necessary | |
266 | to perform some actions before invoking the linker. The | |
267 | C<ExtUtils::Mksymlists> module does this, writing files used by the | |
268 | linker during the creation of shared libraries for dynamic extensions. | |
269 | The names of any files written will be returned as a list. | |
270 | ||
271 | Several parameters correspond to C<ExtUtils::Mksymlists::Mksymlists()> | |
272 | options, as follows: | |
273 | ||
274 | Mksymlists() prelink() type | |
275 | -------------|-------------------|------------------- | |
276 | NAME | dl_name | string (required) | |
277 | DLBASE | dl_base | string | |
278 | FILE | dl_file | string | |
279 | DL_VARS | dl_vars | array reference | |
280 | DL_FUNCS | dl_funcs | hash reference | |
281 | FUNCLIST | dl_func_list | array reference | |
282 | IMPORTS | dl_imports | hash reference | |
ce87d91c | 283 | VERSION | dl_version | string |
6b09c160 YST |
284 | |
285 | Please see the documentation for C<ExtUtils::Mksymlists> for the | |
286 | details of what these parameters do. | |
287 | ||
288 | =item need_prelink | |
289 | ||
290 | Returns true on platforms where C<prelink()> should be called | |
291 | during linking, and false otherwise. | |
292 | ||
ce87d91c SP |
293 | =item extra_link_args_after_prelink |
294 | ||
295 | Returns list of extra arguments to give to the link command; the arguments | |
296 | are the same as for prelink(), with addition of array reference to the | |
297 | results of prelink(); this reference is indexed by key C<prelink_res>. | |
298 | ||
6b09c160 YST |
299 | =back |
300 | ||
301 | =head1 TO DO | |
302 | ||
303 | Currently this has only been tested on Unix and doesn't contain any of | |
304 | the Windows-specific code from the C<Module::Build> project. I'll do | |
305 | that next. | |
306 | ||
307 | =head1 HISTORY | |
308 | ||
309 | This module is an outgrowth of the C<Module::Build> project, to which | |
310 | there have been many contributors. Notably, Randy W. Sims submitted | |
311 | lots of code to support 3 compilers on Windows and helped with various | |
ce87d91c SP |
312 | other platform-specific issues. Ilya Zakharevich has contributed |
313 | fixes for OS/2; John E. Malmberg and Peter Prymmer have done likewise | |
314 | for VMS. | |
6b09c160 YST |
315 | |
316 | =head1 AUTHOR | |
317 | ||
318 | Ken Williams, kwilliams@cpan.org | |
319 | ||
320 | =head1 COPYRIGHT | |
321 | ||
322 | Copyright (c) 2003-2005 Ken Williams. All rights reserved. | |
323 | ||
324 | This library is free software; you can redistribute it and/or | |
325 | modify it under the same terms as Perl itself. | |
326 | ||
327 | =head1 SEE ALSO | |
328 | ||
329 | perl(1), Module::Build(3) | |
330 | ||
331 | =cut |