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

METHODS

65   $dirs = $cc->include_dirs
66       Returns the currently-configured include directories in an ARRAY
67       reference.
68
69   $flags = $cc->extra_compiler_flags
70       Returns the currently-configured extra compiler flags in an ARRAY
71       reference.
72
73   $flags = $cc->extra_linker_flags
74       Returns the currently-configured extra linker flags in an ARRAY
75       reference.
76
77   $cc->push_include_dirs( @dirs )
78       Adds more include directories
79
80   $cc->push_extra_compiler_flags( @flags )
81       Adds more compiler flags
82
83   $cc->push_extra_linker_flags( @flags )
84       Adds more linker flags
85
86   $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
92       Takes the following named arguments. If a single argument is given,
93       that is taken as the source string.
94
95       •       source => STRING
96
97               The source code of the C program to try compiling, building,
98               and running.
99
100       •       extra_compiler_flags => ARRAY
101
102               Optional. If specified, pass extra flags to the compiler.
103
104       •       extra_linker_flags => ARRAY
105
106               Optional. If specified, pass extra flags to the linker.
107
108       •       define => STRING
109
110               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
115   $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
119       Takes one extra optional argument:
120
121       •       diag => STRING
122
123               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
127   $success = $cc->try_find_include_dirs_for( %args )
128       Try to compile, link and execute the given source, using extra include
129       directories.
130
131       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
135       If no a usable combination is found, it returns false.
136
137       Takes the following arguments:
138
139       •       source => STRING
140
141               Source code to compile
142
143       •       dirs => ARRAY of ARRAYs
144
145               Gives a list of sets of dirs. Each set of dirs should be
146               strings in its own array reference.
147
148       •       define => STRING
149
150               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
155   $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
159       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
163       If no usable combination is found, it returns false.
164
165       Takes the following arguments:
166
167       •       source => STRING
168
169               Source code to compile
170
171       •       libs => ARRAY of STRINGs
172
173               Gives a list of sets of libraries. Each set of libraries should
174               be space-separated.
175
176       •       define => STRING
177
178               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
183   $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
188       Each method takes one extra optional argument:
189
190       •       diag => STRING
191
192               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
196   $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
201       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

EXAMPLES

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
211        use ExtUtils::CChecker;
212
213        my $cc = ExtUtils::CChecker->new;
214
215        $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
228        $cc->new_module_build(
229           module_name => "Your::Name::Here",
230           requires => {
231              'IO::Socket' => 0,
232           },
233           ...
234        )->create_build_script;
235
236       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
240   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
249        use ExtUtils::CChecker;
250
251        my $cc = ExtUtils::CChecker->new;
252
253        $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
265        $cc->new_module_build(
266           ...
267        )->create_build_script;
268
269       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
273        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
284       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
288   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
300       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
303        chomp( my $uname_r = `uname -r` );
304
305        my @dirs = (
306           [],
307           [ "/lib/modules/$uname_r/source/include" ],
308        );
309
310        $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
323       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
328   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
336        use ExtUtils::CChecker;
337
338        my $cc = ExtUtils::CChecker->new(
339           defines_to => "mymodule-config.h",
340        );
341
342        $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
355       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
359       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

AUTHOR

365       Paul Evans <leonerd@leonerd.org.uk>
366
367
368
369perl v5.32.1                      2021-01-27             ExtUtils::CChecker(3)
Impressum