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

NAME

6       "ExtUtils::CChecker" - configure-time utilities for using C headers,
7       libraries, or OS features
8

SYNOPSIS

10          use Module::Build;
11          use ExtUtils::CChecker;
12
13          my $cc = ExtUtils::CChecker->new;
14
15          $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
26          Module::Build->new(
27            ...
28          )->create_build_script;
29

DESCRIPTION

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
36       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
40       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

CONSTRUCTOR

45   new
46          $cc = ExtUtils::CChecker->new( %args )
47
48       Returns a new instance of a "ExtUtils::CChecker" object. Takes the
49       following named parameters:
50
51       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
56       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
62       config => HASH
63           If given, passed through as the configuration of the underlying
64           "ExtUtils::CBuilder" instance.
65

METHODS

67   include_dirs
68          $dirs = $cc->include_dirs
69
70       Returns the currently-configured include directories in an ARRAY
71       reference.
72
73   extra_compiler_flags
74          $flags = $cc->extra_compiler_flags
75
76       Returns the currently-configured extra compiler flags in an ARRAY
77       reference.
78
79   extra_linker_flags
80          $flags = $cc->extra_linker_flags
81
82       Returns the currently-configured extra linker flags in an ARRAY
83       reference.
84
85   push_include_dirs
86          $cc->push_include_dirs( @dirs )
87
88       Adds more include directories
89
90   push_extra_compiler_flags
91          $cc->push_extra_compiler_flags( @flags )
92
93       Adds more compiler flags
94
95   push_extra_linker_flags
96          $cc->push_extra_linker_flags( @flags )
97
98       Adds more linker flags
99
100   try_compile_run
101          $success = $cc->try_compile_run( %args )
102
103          $success = $cc->try_compile_run( $source )
104
105       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
109       Takes the following named arguments. If a single argument is given,
110       that is taken as the source string.
111
112       source => STRING
113           The source code of the C program to try compiling, building, and
114           running.
115
116       extra_compiler_flags => ARRAY
117           Optional. If specified, pass extra flags to the compiler.
118
119       extra_linker_flags => ARRAY
120           Optional. If specified, pass extra flags to the linker.
121
122       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
128   assert_compile_run
129          $cc->assert_compile_run( %args )
130
131       Calls "try_compile_run". If it fails, die with an "OS unsupported"
132       message.  Useful to call from Build.PL or Makefile.PL.
133
134       Takes one extra optional argument:
135
136       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
141   try_find_cflags_for
142          $success = $cc->try_find_cflags_for( %args )
143
144       Since version 0.11.
145
146       Try to compile, link and execute the given source, using extra compiler
147       flags.
148
149       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
153       If no usable combination is found, it returns false.
154
155       Takes the following extra arguments:
156
157       source => STRING
158           Source code to compile
159
160       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
164       define => STRING
165           Optional. If specified, then the named symbol will be defined if
166           the program ran successfully.
167
168   try_find_include_dirs_for
169          $success = $cc->try_find_include_dirs_for( %args )
170
171       Try to compile, link and execute the given source, using extra include
172       directories.
173
174       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
178       If no a usable combination is found, it returns false.
179
180       Takes the following arguments:
181
182       source => STRING
183           Source code to compile
184
185       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
189       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
195   try_find_libs_for
196          $success = $cc->try_find_libs_for( %args )
197
198       Try to compile, link and execute the given source, when linked against
199       a given set of extra libraries.
200
201       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
205       If no usable combination is found, it returns false.
206
207       Takes the following arguments:
208
209       source => STRING
210           Source code to compile
211
212       libs => ARRAY of STRINGs
213           Gives a list of sets of libraries. Each set of libraries should be
214           space-separated.
215
216       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
222   find_cflags_for
223          $cc->find_cflags_for( %args )
224
225   find_include_dirs_for
226          $cc->find_include_dirs_for( %args )
227
228   find_libs_for
229          $cc->find_libs_for( %args )
230
231       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
235       Each method takes one extra optional argument:
236
237       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
242   extend_module_build
243          $cc->extend_module_build( $build )
244
245       Since version 0.11.
246
247       Sets the appropriate arguments into the given Module::Build instance.
248
249   new_module_build
250          $mb = $cc->new_module_build( %args )
251
252       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
256       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

EXAMPLES

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
266          use ExtUtils::CChecker;
267
268          my $cc = ExtUtils::CChecker->new;
269
270          $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
283          $cc->new_module_build(
284             module_name => "Your::Name::Here",
285             requires => {
286                'IO::Socket' => 0,
287             },
288             ...
289          )->create_build_script;
290
291       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
295   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
304          use ExtUtils::CChecker;
305
306          my $cc = ExtUtils::CChecker->new;
307
308          $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
320          $cc->new_module_build(
321             ...
322          )->create_build_script;
323
324       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
328          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
339       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
343   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
355       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
358          chomp( my $uname_r = `uname -r` );
359
360          my @dirs = (
361             [],
362             [ "/lib/modules/$uname_r/source/include" ],
363          );
364
365          $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
378       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
383   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
391          use ExtUtils::CChecker;
392
393          my $cc = ExtUtils::CChecker->new(
394             defines_to => "mymodule-config.h",
395          );
396
397          $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
410       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
414       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

AUTHOR

420       Paul Evans <leonerd@leonerd.org.uk>
421
422
423
424perl v5.34.0                      2021-07-22             ExtUtils::CChecker(3)
Impressum