1ExtUtils::CChecker(3) User Contributed Perl DocumentationExtUtils::CChecker(3)
2
6 "ExtUtils::CChecker" - configure-time utilities for using C headers,
7 libraries, or OS features
8
10 use Module::Build;
11 use ExtUtils::CChecker;
12 my $cc = ExtUtils::CChecker->new;
14 $cc->assert_compile_run(
16 diag => "no PF_MOONLASER",
17 source => <<'EOF' );
18 #include <stdio.h>
19 #include <sys/socket.h>
20 int main(int argc, char *argv[]) {
21 printf("PF_MOONLASER is %d\n", PF_MOONLASER);
22 return 0;
23 }
24 EOF
25 Module::Build->new(
27 ...
28 )->create_build_script;
29
31 Often Perl modules are written to wrap functionality found in existing
32 C headers, libraries, or to use OS-specific features. It is useful in
33 the Build.PL or Makefile.PL file to check for the existance of these
34 requirements before attempting to actually build the module.
35 Objects in this class provide an extension around ExtUtils::CBuilder to
37 simplify the creation of a .c file, compiling, linking and running it,
38 to test if a certain feature is present.
39 It may also be necessary to search for the correct library to link
41 against, or for the right include directories to find header files in.
42 This class also provides assistance here.
43
45 $cc = ExtUtils::CChecker->new( %args )
46 Returns a new instance of a "ExtUtils::CChecker" object. Takes the
47 following named parameters:
48 defines_to => PATH
50 If given, defined symbols will be written to a C preprocessor
51 .h file of the given name, instead of by adding extra
52 "-DSYMBOL" arguments to the compiler flags.
53 quiet => BOOL
55 If given, sets the "quiet" option to the underlying
56 "ExtUtils::CBuilder" instance. If absent, defaults to enabled.
57 To disable quietness, i.e. to print more verbosely, pass a
58 defined-but-false value, such as 0.
59 config => HASH
61 If given, passed through as the configuration of the underlying
62 "ExtUtils::CBuilder" instance.
63
65 $dirs = $cc->include_dirs
66 Returns the currently-configured include directories in an ARRAY
67 reference.
68 $flags = $cc->extra_compiler_flags
70 Returns the currently-configured extra compiler flags in an ARRAY
71 reference.
72 $flags = $cc->extra_linker_flags
74 Returns the currently-configured extra linker flags in an ARRAY
75 reference.
76 $cc->push_include_dirs( @dirs )
78 Adds more include directories
79 $cc->push_extra_compiler_flags( @flags )
81 Adds more compiler flags
82 $cc->push_extra_linker_flags( @flags )
84 Adds more linker flags
85 $success = $cc->try_compile_run( %args )
87 $success = $cc->try_compile_run( $source )
88 Try to compile, link, and execute a C program whose source is given.
89 Returns true if the program compiled and linked, and exited
90 successfully. Returns false if any of these steps fail.
91 Takes the following named arguments. If a single argument is given,
93 that is taken as the source string.
94 • source => STRING
96 The source code of the C program to try compiling, building,
98 and running.
99 • extra_compiler_flags => ARRAY
101 Optional. If specified, pass extra flags to the compiler.
103 • extra_linker_flags => ARRAY
105 Optional. If specified, pass extra flags to the linker.
107 • define => STRING
109 Optional. If specified, then the named symbol will be defined
111 if the program ran successfully. This will either on the C
112 compiler commandline (by passing an option "-DSYMBOL"), or in
113 the "defines_to" file.
114 $cc->assert_compile_run( %args )
116 Calls "try_compile_run". If it fails, die with an "OS unsupported"
117 message. Useful to call from Build.PL or Makefile.PL.
118 Takes one extra optional argument:
120 • diag => STRING
122 If present, this string will be appended to the failure message
124 if one is generated. It may provide more useful information to
125 the user on why the OS is unsupported.
126 $success = $cc->try_find_include_dirs_for( %args )
128 Try to compile, link and execute the given source, using extra include
129 directories.
130 When a usable combination is found, the directories required are stored
132 in the object for use in further compile operations, or returned by
133 "include_dirs". The method then returns true.
134 If no a usable combination is found, it returns false.
136 Takes the following arguments:
138 • source => STRING
140 Source code to compile
142 • dirs => ARRAY of ARRAYs
144 Gives a list of sets of dirs. Each set of dirs should be
146 strings in its own array reference.
147 • define => STRING
149 Optional. If specified, then the named symbol will be defined
151 if the program ran successfully. This will either on the C
152 compiler commandline (by passing an option "-DSYMBOL"), or in
153 the "defines_to" file.
154 $success = $cc->try_find_libs_for( %args )
156 Try to compile, link and execute the given source, when linked against
157 a given set of extra libraries.
158 When a usable combination is found, the libraries required are stored
160 in the object for use in further link operations, or returned by
161 "extra_linker_flags". The method then returns true.
162 If no usable combination is found, it returns false.
164 Takes the following arguments:
166 • source => STRING
168 Source code to compile
170 • libs => ARRAY of STRINGs
172 Gives a list of sets of libraries. Each set of libraries should
174 be space-separated.
175 • define => STRING
177 Optional. If specified, then the named symbol will be defined
179 if the program ran successfully. This will either on the C
180 compiler commandline (by passing an option "-DSYMBOL"), or in
181 the "defines_to" file.
182 $cc->find_include_dirs_for( %args )
184 $cc->find_libs_for( %args )
185 Calls "try_find_include_dirs_for" or "try_find_libs_for" respectively.
186 If it fails, die with an "OS unsupported" message.
187 Each method takes one extra optional argument:
189 • diag => STRING
191 If present, this string will be appended to the failure message
193 if one is generated. It may provide more useful information to
194 the user on why the OS is unsupported.
195 $mb = $cc->new_module_build( %args )
197 Construct and return a new Module::Build object, preconfigured with the
198 "include_dirs", "extra_compiler_flags" and "extra_linker_flags" options
199 that have been configured on this object, by the above methods.
200 This is provided as a simple shortcut for the common use case, that a
202 Build.PL file is using the "ExtUtils::CChecker" object to detect the
203 required arguments to pass.
204
206 Socket Libraries
207 Some operating systems provide the BSD sockets API in their primary
208 libc. Others keep it in a separate library which should be linked
209 against. The following example demonstrates how this would be handled.
210 use ExtUtils::CChecker;
212 my $cc = ExtUtils::CChecker->new;
214 $cc->find_libs_for(
216 diag => "no socket()",
217 libs => [ "", "socket nsl" ],
218 source => q[
219 #include <sys/socket.h>
220 int main(int argc, char *argv) {
221 int fd = socket(PF_INET, SOCK_STREAM, 0);
222 if(fd < 0)
223 return 1;
224 return 0;
225 }
226 ] );
227 $cc->new_module_build(
229 module_name => "Your::Name::Here",
230 requires => {
231 'IO::Socket' => 0,
232 },
233 ...
234 )->create_build_script;
235 By using the "new_module_build" method, the detected
237 "extra_linker_flags" value has been automatically passed into the new
238 "Module::Build" object.
239 Testing For Optional Features
241 Sometimes a function or ability may be optionally provided by the OS,
242 or you may wish your module to be useable when only partial support is
243 provided, without requiring it all to be present. In these cases it is
244 traditional to detect the presence of this optional feature in the
245 Build.PL script, and define a symbol to declare this fact if it is
246 found. The XS code can then use this symbol to select between differing
247 implementations. For example, the Build.PL:
248 use ExtUtils::CChecker;
250 my $cc = ExtUtils::CChecker->new;
252 $cc->try_compile_run(
254 define => "HAVE_MANGO",
255 source => <<'EOF' );
256 #include <mango.h>
257 #include <unistd.h>
258 int main(void) {
259 if(mango() != 0)
260 exit(1);
261 exit(0);
262 }
263 EOF
264 $cc->new_module_build(
266 ...
267 )->create_build_script;
268 If the C code compiles and runs successfully, and exits with a true
270 status, the symbol "HAVE_MANGO" will be defined on the compiler
271 commandline. This allows the XS code to detect it, for example
272 int
274 mango()
275 CODE:
276 #ifdef HAVE_MANGO
277 RETVAL = mango();
278 #else
279 croak("mango() not implemented");
280 #endif
281 OUTPUT:
282 RETVAL
283 This module will then still compile even if the operating system lacks
285 this particular function. Trying to invoke the function at runtime will
286 simply throw an exception.
287 Linux Kernel Headers
289 Operating systems built on top of the Linux kernel often share a looser
290 association with their kernel version than most other operating
291 systems. It may be the case that the running kernel is newer,
292 containing more features, than the distribution's libc headers would
293 believe. In such circumstances it can be difficult to make use of new
294 socket options, "ioctl()"s, etc.. without having the constants that
295 define them and their parameter structures, because the relevant header
296 files are not visible to the compiler. In this case, there may be
297 little choice but to pull in some of the kernel header files, which
298 will provide the required constants and structures.
299 The Linux kernel headers can be found using the /lib/modules directory.
301 A fragment in Build.PL like the following, may be appropriate.
302 chomp( my $uname_r = `uname -r` );
304 my @dirs = (
306 [],
307 [ "/lib/modules/$uname_r/source/include" ],
308 );
309 $cc->find_include_dirs_for(
311 diag => "no PF_MOONLASER",
312 dirs => \@dirs,
313 source => <<'EOF' );
314 #include <sys/socket.h>
315 #include <moon/laser.h>
316 int family = PF_MOONLASER;
317 struct laserwl lwl;
318 int main(int argc, char *argv[]) {
319 return 0;
320 }
321 EOF
322 This fragment will first try to compile the program as it stands,
324 hoping that the libc headers will be sufficient. If it fails, it will
325 then try including the kernel headers, which should make the constant
326 and structure visible, allowing the program to compile.
327 Creating an "#include" file
329 Sometimes, rather than setting defined symbols on the compiler
330 commandline, it is preferrable to have them written to a C preprocessor
331 include (.h) file. This may be beneficial for cross-platform
332 portability concerns, as not all C compilers may take extra "-D"
333 arguments on the command line, or platforms may have small length
334 restrictions on the length of a command line.
335 use ExtUtils::CChecker;
337 my $cc = ExtUtils::CChecker->new(
339 defines_to => "mymodule-config.h",
340 );
341 $cc->try_compile_run(
343 define => "HAVE_MANGO",
344 source => <<'EOF' );
345 #include <mango.h>
346 #include <unistd.h>
347 #include "mymodule-config.h"
348 int main(void) {
349 if(mango() != 0)
350 exit(1);
351 exit(0);
352 }
353 EOF
354 Because the mymodule-config.h file is written and flushed after every
356 define operation, it will still be useable in later C fragments to test
357 for features detected in earlier ones.
358 It is suggested not to name the file simply config.h, as the core of
360 Perl itself has a file of that name containing its own compile-time
361 detected configuration. A confusion between the two could lead to
362 surprising results.
363
365 Paul Evans <leonerd@leonerd.org.uk>
366perl v5.32.1 2021-01-27 ExtUtils::CChecker(3)