Commit | Line | Data |
6b09c160 |
1 | package ExtUtils::CBuilder; |
2 | |
3 | use File::Spec (); |
4 | use File::Path (); |
5 | use File::Basename (); |
6 | |
7 | use vars qw($VERSION @ISA); |
100ba297 |
8 | $VERSION = '0.2601'; |
6b09c160 |
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 |
39 | gnu Unix |
40 | gnukfreebsd Unix |
df00ff3b |
41 | haiku Unix |
6b09c160 |
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 |
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 |
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 |
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 | |
136 | =item compile |
137 | |
138 | Compiles a C source file and produces an object file. The name of the |
139 | object file is returned. The source file is specified in a C<source> |
140 | parameter, which is required; the other parameters listed below are |
141 | optional. |
142 | |
143 | =over 4 |
144 | |
145 | =item C<object_file> |
146 | |
147 | Specifies the name of the output file to create. Otherwise the |
148 | C<object_file()> method will be consulted, passing it the name of the |
149 | C<source> file. |
150 | |
151 | =item C<include_dirs> |
152 | |
153 | Specifies any additional directories in which to search for header |
154 | files. May be given as a string indicating a single directory, or as |
155 | a list reference indicating multiple directories. |
156 | |
157 | =item C<extra_compiler_flags> |
158 | |
159 | Specifies any additional arguments to pass to the compiler. Should be |
160 | given as a list reference containing the arguments individually, or if |
161 | this is not possible, as a string containing all the arguments |
162 | together. |
163 | |
164 | =back |
165 | |
166 | The operation of this method is also affected by the |
345dbb93 |
167 | C<archlibexp>, C<cccdlflags>, C<ccflags>, C<optimize>, and C<cc> |
6b09c160 |
168 | entries in C<Config.pm>. |
169 | |
170 | =item link |
171 | |
172 | Invokes the linker to produce a library file from object files. In |
173 | scalar context, the name of the library file is returned. In list |
174 | context, the library file and any temporary files created are |
175 | returned. A required C<objects> parameter contains the name of the |
176 | object files to process, either in a string (for one object file) or |
177 | list reference (for one or more files). The following parameters are |
178 | optional: |
179 | |
180 | |
181 | =over 4 |
182 | |
183 | =item lib_file |
184 | |
185 | Specifies the name of the output library file to create. Otherwise |
186 | the C<lib_file()> method will be consulted, passing it the name of |
187 | the first entry in C<objects>. |
188 | |
189 | =item module_name |
190 | |
191 | Specifies the name of the Perl module that will be created by linking. |
192 | On platforms that need to do prelinking (Win32, OS/2, etc.) this is a |
193 | required parameter. |
194 | |
195 | =item extra_linker_flags |
196 | |
197 | Any additional flags you wish to pass to the linker. |
198 | |
199 | =back |
200 | |
201 | On platforms where C<need_prelink()> returns true, C<prelink()> |
202 | will be called automatically. |
203 | |
204 | The operation of this method is also affected by the C<lddlflags>, |
205 | C<shrpenv>, and C<ld> entries in C<Config.pm>. |
206 | |
207 | =item link_executable |
208 | |
209 | Invokes the linker to produce an executable file from object files. In |
210 | scalar context, the name of the executable file is returned. In list |
211 | context, the executable file and any temporary files created are |
212 | returned. A required C<objects> parameter contains the name of the |
213 | object files to process, either in a string (for one object file) or |
214 | list reference (for one or more files). The optional parameters are |
215 | the same as C<link> with exception for |
216 | |
217 | |
218 | =over 4 |
219 | |
220 | =item exe_file |
221 | |
222 | Specifies the name of the output executable file to create. Otherwise |
223 | the C<exe_file()> method will be consulted, passing it the name of the |
224 | first entry in C<objects>. |
225 | |
226 | =back |
227 | |
228 | =item object_file |
229 | |
230 | my $object_file = $b->object_file($source_file); |
231 | |
232 | Converts the name of a C source file to the most natural name of an |
233 | output object file to create from it. For instance, on Unix the |
234 | source file F<foo.c> would result in the object file F<foo.o>. |
235 | |
236 | =item lib_file |
237 | |
238 | my $lib_file = $b->lib_file($object_file); |
239 | |
240 | Converts the name of an object file to the most natural name of a |
241 | output library file to create from it. For instance, on Mac OS X the |
242 | object file F<foo.o> would result in the library file F<foo.bundle>. |
243 | |
244 | =item exe_file |
245 | |
246 | my $exe_file = $b->exe_file($object_file); |
247 | |
248 | Converts the name of an object file to the most natural name of an |
249 | executable file to create from it. For instance, on Mac OS X the |
250 | object file F<foo.o> would result in the executable file F<foo>, and |
251 | on Windows it would result in F<foo.exe>. |
252 | |
253 | |
254 | =item prelink |
255 | |
256 | On certain platforms like Win32, OS/2, VMS, and AIX, it is necessary |
257 | to perform some actions before invoking the linker. The |
258 | C<ExtUtils::Mksymlists> module does this, writing files used by the |
259 | linker during the creation of shared libraries for dynamic extensions. |
260 | The names of any files written will be returned as a list. |
261 | |
262 | Several parameters correspond to C<ExtUtils::Mksymlists::Mksymlists()> |
263 | options, as follows: |
264 | |
265 | Mksymlists() prelink() type |
266 | -------------|-------------------|------------------- |
267 | NAME | dl_name | string (required) |
268 | DLBASE | dl_base | string |
269 | FILE | dl_file | string |
270 | DL_VARS | dl_vars | array reference |
271 | DL_FUNCS | dl_funcs | hash reference |
272 | FUNCLIST | dl_func_list | array reference |
273 | IMPORTS | dl_imports | hash reference |
ce87d91c |
274 | VERSION | dl_version | string |
6b09c160 |
275 | |
276 | Please see the documentation for C<ExtUtils::Mksymlists> for the |
277 | details of what these parameters do. |
278 | |
279 | =item need_prelink |
280 | |
281 | Returns true on platforms where C<prelink()> should be called |
282 | during linking, and false otherwise. |
283 | |
ce87d91c |
284 | =item extra_link_args_after_prelink |
285 | |
286 | Returns list of extra arguments to give to the link command; the arguments |
287 | are the same as for prelink(), with addition of array reference to the |
288 | results of prelink(); this reference is indexed by key C<prelink_res>. |
289 | |
6b09c160 |
290 | =back |
291 | |
292 | =head1 TO DO |
293 | |
294 | Currently this has only been tested on Unix and doesn't contain any of |
295 | the Windows-specific code from the C<Module::Build> project. I'll do |
296 | that next. |
297 | |
298 | =head1 HISTORY |
299 | |
300 | This module is an outgrowth of the C<Module::Build> project, to which |
301 | there have been many contributors. Notably, Randy W. Sims submitted |
302 | lots of code to support 3 compilers on Windows and helped with various |
ce87d91c |
303 | other platform-specific issues. Ilya Zakharevich has contributed |
304 | fixes for OS/2; John E. Malmberg and Peter Prymmer have done likewise |
305 | for VMS. |
6b09c160 |
306 | |
307 | =head1 AUTHOR |
308 | |
309 | Ken Williams, kwilliams@cpan.org |
310 | |
311 | =head1 COPYRIGHT |
312 | |
313 | Copyright (c) 2003-2005 Ken Williams. All rights reserved. |
314 | |
315 | This library is free software; you can redistribute it and/or |
316 | modify it under the same terms as Perl itself. |
317 | |
318 | =head1 SEE ALSO |
319 | |
320 | perl(1), Module::Build(3) |
321 | |
322 | =cut |