1ExtUtils::CChecker(3) User Contributed Perl DocumentationExtUtils::CChecker(3)
2
3
4
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
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
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
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
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
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
365 Paul Evans <leonerd@leonerd.org.uk>
366
367
368
369perl v5.28.0 2018-07-14 ExtUtils::CChecker(3)