1ExtUtils::CBuilder(3) User Contributed Perl DocumentationExtUtils::CBuilder(3)
2
3
4

NAME

6       ExtUtils::CBuilder - Compile and link C code for Perl modules
7

SYNOPSIS

9         use ExtUtils::CBuilder;
10
11         my $b = ExtUtils::CBuilder->new(%options);
12         $obj_file = $b->compile(source => 'MyModule.c');
13         $lib_file = $b->link(objects => $obj_file);
14

DESCRIPTION

16       This module can build the C portions of Perl modules by invoking the
17       appropriate compilers and linkers in a cross-platform manner.  It was
18       motivated by the "Module::Build" project, but may be useful for other
19       purposes as well.  However, it is not intended as a general cross-
20       platform interface to all your C building needs.  That would have been
21       a much more ambitious goal!
22

METHODS

24       new Returns a new "ExtUtils::CBuilder" object.  A "config" parameter
25           lets you override "Config.pm" settings for all operations performed
26           by the object, as in the following example:
27
28             # Use a different compiler than Config.pm says
29             my $b = ExtUtils::CBuilder->new( config =>
30                                              { ld => 'gcc' } );
31
32           A "quiet" parameter tells "CBuilder" to not print its "system()"
33           commands before executing them:
34
35             # Be quieter than normal
36             my $b = ExtUtils::CBuilder->new( quiet => 1 );
37
38       have_compiler
39           Returns true if the current system has a working C compiler and
40           linker, false otherwise.  To determine this, we actually compile
41           and link a sample C library.  The sample will be compiled in the
42           system tempdir or, if that fails for some reason, in the current
43           directory.
44
45       have_cplusplus
46           Just like have_compiler but for C++ instead of C.
47
48       compile
49           Compiles a C source file and produces an object file.  The name of
50           the object file is returned.  The source file is specified in a
51           "source" parameter, which is required; the other parameters listed
52           below are optional.
53
54           "object_file"
55               Specifies the name of the output file to create.  Otherwise the
56               "object_file()" method will be consulted, passing it the name
57               of the "source" file.
58
59           "include_dirs"
60               Specifies any additional directories in which to search for
61               header files.  May be given as a string indicating a single
62               directory, or as a list reference indicating multiple
63               directories.
64
65           "extra_compiler_flags"
66               Specifies any additional arguments to pass to the compiler.
67               Should be given as a list reference containing the arguments
68               individually, or if this is not possible, as a string
69               containing all the arguments together.
70
71           "C++"
72               Specifies that the source file is a C++ source file and sets
73               appropriate compiler flags
74
75           The operation of this method is also affected by the "archlibexp",
76           "cccdlflags", "ccflags", "optimize", and "cc" entries in
77           "Config.pm".
78
79       link
80           Invokes the linker to produce a library file from object files.  In
81           scalar context, the name of the library file is returned.  In list
82           context, the library file and any temporary files created are
83           returned.  A required "objects" parameter contains the name of the
84           object files to process, either in a string (for one object file)
85           or list reference (for one or more files).  The following
86           parameters are optional:
87
88           lib_file
89               Specifies the name of the output library file to create.
90               Otherwise the "lib_file()" method will be consulted, passing it
91               the name of the first entry in "objects".
92
93           module_name
94               Specifies the name of the Perl module that will be created by
95               linking.  On platforms that need to do prelinking (Win32, OS/2,
96               etc.) this is a required parameter.
97
98           extra_linker_flags
99               Any additional flags you wish to pass to the linker.
100
101           On platforms where "need_prelink()" returns true, "prelink()" will
102           be called automatically.
103
104           The operation of this method is also affected by the "lddlflags",
105           "shrpenv", and "ld" entries in "Config.pm".
106
107       link_executable
108           Invokes the linker to produce an executable file from object files.
109           In scalar context, the name of the executable file is returned.  In
110           list context, the executable file and any temporary files created
111           are returned.  A required "objects" parameter contains the name of
112           the object files to process, either in a string (for one object
113           file) or list reference (for one or more files).  The optional
114           parameters are the same as "link" with exception for
115
116           exe_file
117               Specifies the name of the output executable file to create.
118               Otherwise the "exe_file()" method will be consulted, passing it
119               the name of the first entry in "objects".
120
121       object_file
122            my $object_file = $b->object_file($source_file);
123
124           Converts the name of a C source file to the most natural name of an
125           output object file to create from it.  For instance, on Unix the
126           source file foo.c would result in the object file foo.o.
127
128       lib_file
129            my $lib_file = $b->lib_file($object_file);
130
131           Converts the name of an object file to the most natural name of a
132           output library file to create from it.  For instance, on Mac OS X
133           the object file foo.o would result in the library file foo.bundle.
134
135       exe_file
136            my $exe_file = $b->exe_file($object_file);
137
138           Converts the name of an object file to the most natural name of an
139           executable file to create from it.  For instance, on Mac OS X the
140           object file foo.o would result in the executable file foo, and on
141           Windows it would result in foo.exe.
142
143       prelink
144           On certain platforms like Win32, OS/2, VMS, and AIX, it is
145           necessary to perform some actions before invoking the linker.  The
146           "ExtUtils::Mksymlists" module does this, writing files used by the
147           linker during the creation of shared libraries for dynamic
148           extensions.  The names of any files written will be returned as a
149           list.
150
151           Several parameters correspond to
152           "ExtUtils::Mksymlists::Mksymlists()" options, as follows:
153
154               Mksymlists()   prelink()          type
155              -------------|-------------------|-------------------
156               NAME        |  dl_name          | string (required)
157               DLBASE      |  dl_base          | string
158               FILE        |  dl_file          | string
159               DL_VARS     |  dl_vars          | array reference
160               DL_FUNCS    |  dl_funcs         | hash reference
161               FUNCLIST    |  dl_func_list     | array reference
162               IMPORTS     |  dl_imports       | hash reference
163               VERSION     |  dl_version       | string
164
165           Please see the documentation for "ExtUtils::Mksymlists" for the
166           details of what these parameters do.
167
168       need_prelink
169           Returns true on platforms where "prelink()" should be called during
170           linking, and false otherwise.
171
172       extra_link_args_after_prelink
173           Returns list of extra arguments to give to the link command; the
174           arguments are the same as for prelink(), with addition of array
175           reference to the results of prelink(); this reference is indexed by
176           key "prelink_res".
177

TO DO

179       Currently this has only been tested on Unix and doesn't contain any of
180       the Windows-specific code from the "Module::Build" project.  I'll do
181       that next.
182

HISTORY

184       This module is an outgrowth of the "Module::Build" project, to which
185       there have been many contributors.  Notably, Randy W. Sims submitted
186       lots of code to support 3 compilers on Windows and helped with various
187       other platform-specific issues.  Ilya Zakharevich has contributed fixes
188       for OS/2; John E. Malmberg and Peter Prymmer have done likewise for
189       VMS.
190

SUPPORT

192       ExtUtils::CBuilder is maintained as part of the Perl 5 core.  Please
193       submit any bug reports via the perlbug tool included with Perl 5.  Bug
194       reports will be included in the Perl 5 ticket system at
195       <https://rt.perl.org>.
196
197       The Perl 5 source code is available at
198       <https://perl5.git.perl.org/perl.git> and ExtUtils-CBuilder may be
199       found in the dist/ExtUtils-CBuilder directory of the repository.
200

AUTHOR

202       Ken Williams, kwilliams@cpan.org
203
204       Additional contributions by The Perl 5 Porters.
205
207       Copyright (c) 2003-2005 Ken Williams.  All rights reserved.
208
209       This library is free software; you can redistribute it and/or modify it
210       under the same terms as Perl itself.
211

SEE ALSO

213       perl(1), Module::Build(3)
214
215
216
217perl v5.34.0                      2022-01-21             ExtUtils::CBuilder(3)
Impressum