Debian Codegraph @

upstream/opensuse-tumbleweed/man3/ExtUtils::CBuilder.3pm

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