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