1ExtUtils::CChecker(3pm)User Contributed Perl DocumentatioEnxtUtils::CChecker(3pm)
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 new
46 $cc = ExtUtils::CChecker->new( %args )
47 Returns a new instance of a "ExtUtils::CChecker" object. Takes the
49 following named parameters:
50 defines_to => PATH
52 If given, defined symbols will be written to a C preprocessor .h
53 file of the given name, instead of by adding extra "-DSYMBOL"
54 arguments to the compiler flags.
55 quiet => BOOL
57 If given, sets the "quiet" option to the underlying
58 "ExtUtils::CBuilder" instance. If absent, defaults to enabled. To
59 disable quietness, i.e. to print more verbosely, pass a defined-
60 but-false value, such as 0.
61 config => HASH
63 If given, passed through as the configuration of the underlying
64 "ExtUtils::CBuilder" instance.
65
67 include_dirs
68 $dirs = $cc->include_dirs
69 Returns the currently-configured include directories in an ARRAY
71 reference.
72 extra_compiler_flags
74 $flags = $cc->extra_compiler_flags
75 Returns the currently-configured extra compiler flags in an ARRAY
77 reference.
78 extra_linker_flags
80 $flags = $cc->extra_linker_flags
81 Returns the currently-configured extra linker flags in an ARRAY
83 reference.
84 push_include_dirs
86 $cc->push_include_dirs( @dirs )
87 Adds more include directories
89 push_extra_compiler_flags
91 $cc->push_extra_compiler_flags( @flags )
92 Adds more compiler flags
94 push_extra_linker_flags
96 $cc->push_extra_linker_flags( @flags )
97 Adds more linker flags
99 try_compile_run
101 $success = $cc->try_compile_run( %args )
102 $success = $cc->try_compile_run( $source )
104 Try to compile, link, and execute a C program whose source is given.
106 Returns true if the program compiled and linked, and exited
107 successfully. Returns false if any of these steps fail.
108 Takes the following named arguments. If a single argument is given,
110 that is taken as the source string.
111 source => STRING
113 The source code of the C program to try compiling, building, and
114 running.
115 extra_compiler_flags => ARRAY
117 Optional. If specified, pass extra flags to the compiler.
118 extra_linker_flags => ARRAY
120 Optional. If specified, pass extra flags to the linker.
121 define => STRING
123 Optional. If specified, then the named symbol will be defined if
124 the program ran successfully. This will either on the C compiler
125 commandline (by passing an option "-DSYMBOL"), or in the
126 "defines_to" file.
127 assert_compile_run
129 $cc->assert_compile_run( %args )
130 Calls "try_compile_run". If it fails, die with an "OS unsupported"
132 message. Useful to call from Build.PL or Makefile.PL.
133 Takes one extra optional argument:
135 diag => STRING
137 If present, this string will be appended to the failure message if
138 one is generated. It may provide more useful information to the
139 user on why the OS is unsupported.
140 try_find_cflags_for
142 $success = $cc->try_find_cflags_for( %args )
143 Since version 0.11.
145 Try to compile, link and execute the given source, using extra compiler
147 flags.
148 When a usable combination is found, the flags are stored in the object
150 for use in further compile operations, or returned by
151 "extra_compiler_flags". The method then returns true.
152 If no usable combination is found, it returns false.
154 Takes the following extra arguments:
156 source => STRING
158 Source code to compile
159 cflags => ARRAY of ARRAYs
161 Gives a list of sets of flags. Each set of flags should be strings
162 in its own array reference.
163 define => STRING
165 Optional. If specified, then the named symbol will be defined if
166 the program ran successfully.
167 try_find_include_dirs_for
169 $success = $cc->try_find_include_dirs_for( %args )
170 Try to compile, link and execute the given source, using extra include
172 directories.
173 When a usable combination is found, the directories required are stored
175 in the object for use in further compile operations, or returned by
176 "include_dirs". The method then returns true.
177 If no a usable combination is found, it returns false.
179 Takes the following arguments:
181 source => STRING
183 Source code to compile
184 dirs => ARRAY of ARRAYs
186 Gives a list of sets of dirs. Each set of dirs should be strings in
187 its own array reference.
188 define => STRING
190 Optional. If specified, then the named symbol will be defined if
191 the program ran successfully. This will either on the C compiler
192 commandline (by passing an option "-DSYMBOL"), or in the
193 "defines_to" file.
194 try_find_libs_for
196 $success = $cc->try_find_libs_for( %args )
197 Try to compile, link and execute the given source, when linked against
199 a given set of extra libraries.
200 When a usable combination is found, the libraries required are stored
202 in the object for use in further link operations, or returned by
203 "extra_linker_flags". The method then returns true.
204 If no usable combination is found, it returns false.
206 Takes the following arguments:
208 source => STRING
210 Source code to compile
211 libs => ARRAY of STRINGs
213 Gives a list of sets of libraries. Each set of libraries should be
214 space-separated.
215 define => STRING
217 Optional. If specified, then the named symbol will be defined if
218 the program ran successfully. This will either on the C compiler
219 commandline (by passing an option "-DSYMBOL"), or in the
220 "defines_to" file.
221 find_cflags_for
223 $cc->find_cflags_for( %args )
224 find_include_dirs_for
226 $cc->find_include_dirs_for( %args )
227 find_libs_for
229 $cc->find_libs_for( %args )
230 Calls "try_find_cflags_for", "try_find_include_dirs_for" or
232 "try_find_libs_for" respectively. If it fails, die with an "OS
233 unsupported" message.
234 Each method takes one extra optional argument:
236 diag => STRING
238 If present, this string will be appended to the failure message if
239 one is generated. It may provide more useful information to the
240 user on why the OS is unsupported.
241 extend_module_build
243 $cc->extend_module_build( $build )
244 Since version 0.11.
246 Sets the appropriate arguments into the given Module::Build instance.
248 new_module_build
250 $mb = $cc->new_module_build( %args )
251 Construct and return a new Module::Build object, preconfigured with the
253 "include_dirs", "extra_compiler_flags" and "extra_linker_flags" options
254 that have been configured on this object, by the above methods.
255 This is provided as a simple shortcut for the common use case, that a
257 Build.PL file is using the "ExtUtils::CChecker" object to detect the
258 required arguments to pass.
259
261 Socket Libraries
262 Some operating systems provide the BSD sockets API in their primary
263 libc. Others keep it in a separate library which should be linked
264 against. The following example demonstrates how this would be handled.
265 use ExtUtils::CChecker;
267 my $cc = ExtUtils::CChecker->new;
269 $cc->find_libs_for(
271 diag => "no socket()",
272 libs => [ "", "socket nsl" ],
273 source => q[
274 #include <sys/socket.h>
275 int main(int argc, char *argv) {
276 int fd = socket(PF_INET, SOCK_STREAM, 0);
277 if(fd < 0)
278 return 1;
279 return 0;
280 }
281 ] );
282 $cc->new_module_build(
284 module_name => "Your::Name::Here",
285 requires => {
286 'IO::Socket' => 0,
287 },
288 ...
289 )->create_build_script;
290 By using the "new_module_build" method, the detected
292 "extra_linker_flags" value has been automatically passed into the new
293 "Module::Build" object.
294 Testing For Optional Features
296 Sometimes a function or ability may be optionally provided by the OS,
297 or you may wish your module to be useable when only partial support is
298 provided, without requiring it all to be present. In these cases it is
299 traditional to detect the presence of this optional feature in the
300 Build.PL script, and define a symbol to declare this fact if it is
301 found. The XS code can then use this symbol to select between differing
302 implementations. For example, the Build.PL:
303 use ExtUtils::CChecker;
305 my $cc = ExtUtils::CChecker->new;
307 $cc->try_compile_run(
309 define => "HAVE_MANGO",
310 source => <<'EOF' );
311 #include <mango.h>
312 #include <unistd.h>
313 int main(void) {
314 if(mango() != 0)
315 exit(1);
316 exit(0);
317 }
318 EOF
319 $cc->new_module_build(
321 ...
322 )->create_build_script;
323 If the C code compiles and runs successfully, and exits with a true
325 status, the symbol "HAVE_MANGO" will be defined on the compiler
326 commandline. This allows the XS code to detect it, for example
327 int
329 mango()
330 CODE:
331 #ifdef HAVE_MANGO
332 RETVAL = mango();
333 #else
334 croak("mango() not implemented");
335 #endif
336 OUTPUT:
337 RETVAL
338 This module will then still compile even if the operating system lacks
340 this particular function. Trying to invoke the function at runtime will
341 simply throw an exception.
342 Linux Kernel Headers
344 Operating systems built on top of the Linux kernel often share a looser
345 association with their kernel version than most other operating
346 systems. It may be the case that the running kernel is newer,
347 containing more features, than the distribution's libc headers would
348 believe. In such circumstances it can be difficult to make use of new
349 socket options, ioctl()s, etc.. without having the constants that
350 define them and their parameter structures, because the relevant header
351 files are not visible to the compiler. In this case, there may be
352 little choice but to pull in some of the kernel header files, which
353 will provide the required constants and structures.
354 The Linux kernel headers can be found using the /lib/modules directory.
356 A fragment in Build.PL like the following, may be appropriate.
357 chomp( my $uname_r = `uname -r` );
359 my @dirs = (
361 [],
362 [ "/lib/modules/$uname_r/source/include" ],
363 );
364 $cc->find_include_dirs_for(
366 diag => "no PF_MOONLASER",
367 dirs => \@dirs,
368 source => <<'EOF' );
369 #include <sys/socket.h>
370 #include <moon/laser.h>
371 int family = PF_MOONLASER;
372 struct laserwl lwl;
373 int main(int argc, char *argv[]) {
374 return 0;
375 }
376 EOF
377 This fragment will first try to compile the program as it stands,
379 hoping that the libc headers will be sufficient. If it fails, it will
380 then try including the kernel headers, which should make the constant
381 and structure visible, allowing the program to compile.
382 Creating an "#include" file
384 Sometimes, rather than setting defined symbols on the compiler
385 commandline, it is preferrable to have them written to a C preprocessor
386 include (.h) file. This may be beneficial for cross-platform
387 portability concerns, as not all C compilers may take extra "-D"
388 arguments on the command line, or platforms may have small length
389 restrictions on the length of a command line.
390 use ExtUtils::CChecker;
392 my $cc = ExtUtils::CChecker->new(
394 defines_to => "mymodule-config.h",
395 );
396 $cc->try_compile_run(
398 define => "HAVE_MANGO",
399 source => <<'EOF' );
400 #include <mango.h>
401 #include <unistd.h>
402 #include "mymodule-config.h"
403 int main(void) {
404 if(mango() != 0)
405 exit(1);
406 exit(0);
407 }
408 EOF
409 Because the mymodule-config.h file is written and flushed after every
411 define operation, it will still be useable in later C fragments to test
412 for features detected in earlier ones.
413 It is suggested not to name the file simply config.h, as the core of
415 Perl itself has a file of that name containing its own compile-time
416 detected configuration. A confusion between the two could lead to
417 surprising results.
418
420 Paul Evans <leonerd@leonerd.org.uk>
421perl v5.38.0 2023-07-20 ExtUtils::CChecker(3pm)