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