Debian Codegraph @

upstream/debian-unstable/man3/ExtUtils::CBuilder.3perl

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\" ========================================================================
56 .\"
57 .IX Title "ExtUtils::CBuilder 3perl"
58 .TH ExtUtils::CBuilder 3perl 2025-11-16 "perl v5.40.1" "Perl Programmers Reference Guide"
59 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
60 .\" way too many mistakes in technical documents.
61 .if n .ad l
62 .nh
63 .SH NAME
64 ExtUtils::CBuilder \- Compile and link C code for Perl modules
65 .SH SYNOPSIS
66 .IX Header "SYNOPSIS"
67 .Vb 1
68 \& use ExtUtils::CBuilder;
69 \&
70 \& my $b = ExtUtils::CBuilder\->new(%options);
71 \& $obj_file = $b\->compile(source => \*(AqMyModule.c\*(Aq);
72 \& $lib_file = $b\->link(objects => $obj_file);
73 .Ve
74 .SH DESCRIPTION
75 .IX Header "DESCRIPTION"
76 This module can build the C portions of Perl modules by invoking the
77 appropriate compilers and linkers in a cross-platform manner. It was
78 motivated by the \f(CW\*(C`Module::Build\*(C'\fR project, but may be useful for other
79 purposes as well. However, it is \fInot\fR intended as a general
80 cross-platform interface to all your C building needs. That would
81 have been a much more ambitious goal!
82 .SH METHODS
83 .IX Header "METHODS"
84 .IP new 4
85 .IX Item "new"
86 Returns a new \f(CW\*(C`ExtUtils::CBuilder\*(C'\fR object. A \f(CW\*(C`config\*(C'\fR parameter
87 lets you override \f(CW\*(C`Config.pm\*(C'\fR settings for all operations performed
88 by the object, as in the following example:
89 .Sp
90 .Vb 3
91 \& # Use a different compiler than Config.pm says
92 \& my $b = ExtUtils::CBuilder\->new( config =>
93 \& { ld => \*(Aqgcc\*(Aq } );
94 .Ve
95 .Sp
96 A \f(CW\*(C`quiet\*(C'\fR parameter tells \f(CW\*(C`CBuilder\*(C'\fR to not print its \f(CWsystem()\fR
97 commands before executing them:
98 .Sp
99 .Vb 2
100 \& # Be quieter than normal
101 \& my $b = ExtUtils::CBuilder\->new( quiet => 1 );
102 .Ve
103 .IP have_compiler 4
104 .IX Item "have_compiler"
105 Returns true if the current system has a working C compiler and
106 linker, false otherwise. To determine this, we actually compile and
107 link a sample C library. The sample will be compiled in the system
108 tempdir or, if that fails for some reason, in the current directory.
109 .IP have_cplusplus 4
110 .IX Item "have_cplusplus"
111 Just like have_compiler but for C++ instead of C.
112 .IP compile 4
113 .IX Item "compile"
114 Compiles a C source file and produces an object file. The name of the
115 object file is returned. The source file is specified in a \f(CW\*(C`source\*(C'\fR
116 parameter, which is required; the other parameters listed below are
117 optional.
118 .RS 4
119 .ie n .IP """object_file""" 4
120 .el .IP \f(CWobject_file\fR 4
121 .IX Item "object_file"
122 Specifies the name of the output file to create. Otherwise the
123 \&\f(CWobject_file()\fR method will be consulted, passing it the name of the
124 \&\f(CW\*(C`source\*(C'\fR file.
125 .ie n .IP """include_dirs""" 4
126 .el .IP \f(CWinclude_dirs\fR 4
127 .IX Item "include_dirs"
128 Specifies any additional directories in which to search for header
129 files. May be given as a string indicating a single directory, or as
130 a list reference indicating multiple directories.
131 .ie n .IP """extra_compiler_flags""" 4
132 .el .IP \f(CWextra_compiler_flags\fR 4
133 .IX Item "extra_compiler_flags"
134 Specifies any additional arguments to pass to the compiler. Should be
135 given as a list reference containing the arguments individually, or if
136 this is not possible, as a string containing all the arguments
137 together.
138 .ie n .IP """C++""" 4
139 .el .IP \f(CWC++\fR 4
140 .IX Item "C++"
141 Specifies that the source file is a C++ source file and sets appropriate
142 compiler flags
143 .RE
144 .RS 4
145 .Sp
146 The operation of this method is also affected by the
147 \&\f(CW\*(C`archlibexp\*(C'\fR, \f(CW\*(C`cccdlflags\*(C'\fR, \f(CW\*(C`ccflags\*(C'\fR, \f(CW\*(C`optimize\*(C'\fR, and \f(CW\*(C`cc\*(C'\fR
148 entries in \f(CW\*(C`Config.pm\*(C'\fR.
149 .RE
150 .IP link 4
151 .IX Item "link"
152 Invokes the linker to produce a library file from object files. In
153 scalar context, the name of the library file is returned. In list
154 context, the library file and any temporary files created are
155 returned. A required \f(CW\*(C`objects\*(C'\fR parameter contains the name of the
156 object files to process, either in a string (for one object file) or
157 list reference (for one or more files). The following parameters are
158 optional:
159 .RS 4
160 .IP lib_file 4
161 .IX Item "lib_file"
162 Specifies the name of the output library file to create. Otherwise
163 the \f(CWlib_file()\fR method will be consulted, passing it the name of
164 the first entry in \f(CW\*(C`objects\*(C'\fR.
165 .IP module_name 4
166 .IX Item "module_name"
167 Specifies the name of the Perl module that will be created by linking.
168 On platforms that need to do prelinking (Win32, OS/2, etc.) this is a
169 required parameter.
170 .IP extra_linker_flags 4
171 .IX Item "extra_linker_flags"
172 Any additional flags you wish to pass to the linker.
173 .RE
174 .RS 4
175 .Sp
176 On platforms where \f(CWneed_prelink()\fR returns true, \f(CWprelink()\fR
177 will be called automatically.
178 .Sp
179 The operation of this method is also affected by the \f(CW\*(C`lddlflags\*(C'\fR,
180 \&\f(CW\*(C`shrpenv\*(C'\fR, and \f(CW\*(C`ld\*(C'\fR entries in \f(CW\*(C`Config.pm\*(C'\fR.
181 .RE
182 .IP link_executable 4
183 .IX Item "link_executable"
184 Invokes the linker to produce an executable file from object files. In
185 scalar context, the name of the executable file is returned. In list
186 context, the executable file and any temporary files created are
187 returned. A required \f(CW\*(C`objects\*(C'\fR parameter contains the name of the
188 object files to process, either in a string (for one object file) or
189 list reference (for one or more files). The optional parameters are
190 the same as \f(CW\*(C`link\*(C'\fR with exception for
191 .RS 4
192 .IP exe_file 4
193 .IX Item "exe_file"
194 Specifies the name of the output executable file to create. Otherwise
195 the \f(CWexe_file()\fR method will be consulted, passing it the name of the
196 first entry in \f(CW\*(C`objects\*(C'\fR.
197 .RE
198 .RS 4
199 .RE
200 .IP object_file 4
201 .IX Item "object_file"
202 .Vb 1
203 \& my $object_file = $b\->object_file($source_file);
204 .Ve
205 .Sp
206 Converts the name of a C source file to the most natural name of an
207 output object file to create from it. For instance, on Unix the
208 source file \fIfoo.c\fR would result in the object file \fIfoo.o\fR.
209 .IP lib_file 4
210 .IX Item "lib_file"
211 .Vb 1
212 \& my $lib_file = $b\->lib_file($object_file);
213 .Ve
214 .Sp
215 Converts the name of an object file to the most natural name of a
216 output library file to create from it. For instance, on Mac OS X the
217 object file \fIfoo.o\fR would result in the library file \fIfoo.bundle\fR.
218 .IP exe_file 4
219 .IX Item "exe_file"
220 .Vb 1
221 \& my $exe_file = $b\->exe_file($object_file);
222 .Ve
223 .Sp
224 Converts the name of an object file to the most natural name of an
225 executable file to create from it. For instance, on Mac OS X the
226 object file \fIfoo.o\fR would result in the executable file \fIfoo\fR, and
227 on Windows it would result in \fIfoo.exe\fR.
228 .IP prelink 4
229 .IX Item "prelink"
230 On certain platforms like Win32, OS/2, VMS, and AIX, it is necessary
231 to perform some actions before invoking the linker. The
232 \&\f(CW\*(C`ExtUtils::Mksymlists\*(C'\fR module does this, writing files used by the
233 linker during the creation of shared libraries for dynamic extensions.
234 The names of any files written will be returned as a list.
235 .Sp
236 Several parameters correspond to \f(CWExtUtils::Mksymlists::Mksymlists()\fR
237 options, as follows:
238 .Sp
239 .Vb 10
240 \& Mksymlists() prelink() type
241 \& \-\-\-\-\-\-\-\-\-\-\-\-\-|\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-|\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
242 \& NAME | dl_name | string (required)
243 \& DLBASE | dl_base | string
244 \& FILE | dl_file | string
245 \& DL_VARS | dl_vars | array reference
246 \& DL_FUNCS | dl_funcs | hash reference
247 \& FUNCLIST | dl_func_list | array reference
248 \& IMPORTS | dl_imports | hash reference
249 \& VERSION | dl_version | string
250 .Ve
251 .Sp
252 Please see the documentation for \f(CW\*(C`ExtUtils::Mksymlists\*(C'\fR for the
253 details of what these parameters do.
254 .IP need_prelink 4
255 .IX Item "need_prelink"
256 Returns true on platforms where \f(CWprelink()\fR should be called
257 during linking, and false otherwise.
258 .IP extra_link_args_after_prelink 4
259 .IX Item "extra_link_args_after_prelink"
260 Returns list of extra arguments to give to the link command; the arguments
261 are the same as for \fBprelink()\fR, with addition of array reference to the
262 results of \fBprelink()\fR; this reference is indexed by key \f(CW\*(C`prelink_res\*(C'\fR.
263 .SH "TO DO"
264 .IX Header "TO DO"
265 Currently this has only been tested on Unix and doesn't contain any of
266 the Windows-specific code from the \f(CW\*(C`Module::Build\*(C'\fR project. I'll do
267 that next.
268 .SH HISTORY
269 .IX Header "HISTORY"
270 This module is an outgrowth of the \f(CW\*(C`Module::Build\*(C'\fR project, to which
271 there have been many contributors. Notably, Randy W. Sims submitted
272 lots of code to support 3 compilers on Windows and helped with various
273 other platform-specific issues. Ilya Zakharevich has contributed
274 fixes for OS/2; John E. Malmberg and Peter Prymmer have done likewise
275 for VMS.
276 .SH SUPPORT
277 .IX Header "SUPPORT"
278 ExtUtils::CBuilder is maintained as part of the Perl 5 core. Please
279 submit any bug reports via the \fIperlbug\fR tool included with Perl 5.
280 Bug reports will be included in the Perl 5 ticket system at
281 <https://rt.perl.org>.
282 .PP
283 The Perl 5 source code is available at <https://perl5.git.perl.org/perl.git>
284 and ExtUtils-CBuilder may be found in the \fIdist/ExtUtils\-CBuilder\fR directory
285 of the repository.
286 .SH AUTHOR
287 .IX Header "AUTHOR"
288 Ken Williams, [email protected]
289 .PP
290 Additional contributions by The Perl 5 Porters.
291 .SH COPYRIGHT
292 .IX Header "COPYRIGHT"
293 Copyright (c) 2003\-2005 Ken Williams. All rights reserved.
294 .PP
295 This library is free software; you can redistribute it and/or
296 modify it under the same terms as Perl itself.
297 .SH "SEE ALSO"
298 .IX Header "SEE ALSO"
299 \&\fBperl\fR\|(1), \fBModule::Build\fR\|(3)