Debian Codegraph @

README

raw
1 NAME
2
3 ExtUtils::CChecker - configure-time utilities for using C headers,
4 libraries, or OS features
5
6 SYNOPSIS
7
8 use Module::Build;
9 use ExtUtils::CChecker;
10
11 my $cc = ExtUtils::CChecker->new;
12
13 $cc->assert_compile_run(
14 diag => "no PF_MOONLASER",
15 source => <<'EOF' );
16 #include <stdio.h>
17 #include <sys/socket.h>
18 int main(int argc, char *argv[]) {
19 printf("PF_MOONLASER is %d\n", PF_MOONLASER);
20 return 0;
21 }
22 EOF
23
24 Module::Build->new(
25 ...
26 )->create_build_script;
27
28 DESCRIPTION
29
30 Often Perl modules are written to wrap functionality found in existing
31 C headers, libraries, or to use OS-specific features. It is useful in
32 the Build.PL or Makefile.PL file to check for the existance of these
33 requirements before attempting to actually build the module.
34
35 Objects in this class provide an extension around ExtUtils::CBuilder to
36 simplify the creation of a .c file, compiling, linking and running it,
37 to test if a certain feature is present.
38
39 It may also be necessary to search for the correct library to link
40 against, or for the right include directories to find header files in.
41 This class also provides assistance here.
42
43 CONSTRUCTOR
44
45 new
46
47 $cc = ExtUtils::CChecker->new( %args );
48
49 Returns a new instance of a ExtUtils::CChecker object. Takes the
50 following named parameters:
51
52 defines_to => PATH
53
54 If given, defined symbols will be written to a C preprocessor .h file
55 of the given name, instead of by adding extra -DSYMBOL arguments to
56 the compiler flags.
57
58 quiet => BOOL
59
60 If given, sets the quiet option to the underlying ExtUtils::CBuilder
61 instance. If absent, defaults to enabled. To disable quietness, i.e.
62 to print more verbosely, pass a defined-but-false value, such as 0.
63
64 config => HASH
65
66 If given, passed through as the configuration of the underlying
67 ExtUtils::CBuilder instance.
68
69 METHODS
70
71 include_dirs
72
73 $dirs = $cc->include_dirs;
74
75 Returns the currently-configured include directories in an ARRAY
76 reference.
77
78 extra_compiler_flags
79
80 $flags = $cc->extra_compiler_flags;
81
82 Returns the currently-configured extra compiler flags in an ARRAY
83 reference.
84
85 extra_linker_flags
86
87 $flags = $cc->extra_linker_flags;
88
89 Returns the currently-configured extra linker flags in an ARRAY
90 reference.
91
92 push_include_dirs
93
94 $cc->push_include_dirs( @dirs );
95
96 Adds more include directories
97
98 push_extra_compiler_flags
99
100 $cc->push_extra_compiler_flags( @flags );
101
102 Adds more compiler flags
103
104 push_extra_linker_flags
105
106 $cc->push_extra_linker_flags( @flags );
107
108 Adds more linker flags
109
110 define
111
112 $cc->define( $symbol );
113
114 Adds a new defined symbol directly; either by appending to the compiler
115 flags or writing it into the defines file.
116
117 try_compile_run
118
119 $success = $cc->try_compile_run( %args );
120
121 $success = $cc->try_compile_run( $source );
122
123 Try to compile, link, and execute a C program whose source is given.
124 Returns true if the program compiled and linked, and exited
125 successfully. Returns false if any of these steps fail.
126
127 Takes the following named arguments. If a single argument is given,
128 that is taken as the source string.
129
130 source => STRING
131
132 The source code of the C program to try compiling, building, and
133 running.
134
135 extra_compiler_flags => ARRAY
136
137 Optional. If specified, pass extra flags to the compiler.
138
139 extra_linker_flags => ARRAY
140
141 Optional. If specified, pass extra flags to the linker.
142
143 define => STRING
144
145 Optional. If specified, then the named symbol will be defined if the
146 program ran successfully. This will either on the C compiler
147 commandline (by passing an option -DSYMBOL), or in the defines_to
148 file.
149
150 assert_compile_run
151
152 $cc->assert_compile_run( %args );
153
154 Calls try_compile_run. If it fails, die with an OS unsupported message.
155 Useful to call from Build.PL or Makefile.PL.
156
157 Takes one extra optional argument:
158
159 diag => STRING
160
161 If present, this string will be appended to the failure message if
162 one is generated. It may provide more useful information to the user
163 on why the OS is unsupported.
164
165 try_find_cflags_for
166
167 $success = $cc->try_find_cflags_for( %args );
168
169 Since version 0.11.
170
171 Try to compile, link and execute the given source, using extra compiler
172 flags.
173
174 When a usable combination is found, the flags are stored in the object
175 for use in further compile operations, or returned by
176 extra_compiler_flags. The method then returns true.
177
178 If no usable combination is found, it returns false.
179
180 Takes the following extra arguments:
181
182 source => STRING
183
184 Source code to compile
185
186 cflags => ARRAY of ARRAYs
187
188 Gives a list of sets of flags. Each set of flags should be strings in
189 its own array reference.
190
191 define => STRING
192
193 Optional. If specified, then the named symbol will be defined if the
194 program ran successfully.
195
196 try_find_include_dirs_for
197
198 $success = $cc->try_find_include_dirs_for( %args );
199
200 Try to compile, link and execute the given source, using extra include
201 directories.
202
203 When a usable combination is found, the directories required are stored
204 in the object for use in further compile operations, or returned by
205 include_dirs. The method then returns true.
206
207 If no a usable combination is found, it returns false.
208
209 Takes the following arguments:
210
211 source => STRING
212
213 Source code to compile
214
215 dirs => ARRAY of ARRAYs
216
217 Gives a list of sets of dirs. Each set of dirs should be strings in
218 its own array reference.
219
220 define => STRING
221
222 Optional. If specified, then the named symbol will be defined if the
223 program ran successfully. This will either on the C compiler
224 commandline (by passing an option -DSYMBOL), or in the defines_to
225 file.
226
227 try_find_libs_for
228
229 $success = $cc->try_find_libs_for( %args );
230
231 Try to compile, link and execute the given source, when linked against
232 a given set of extra libraries.
233
234 When a usable combination is found, the libraries required are stored
235 in the object for use in further link operations, or returned by
236 extra_linker_flags. The method then returns true.
237
238 If no usable combination is found, it returns false.
239
240 Takes the following arguments:
241
242 source => STRING
243
244 Source code to compile
245
246 libs => ARRAY of STRINGs
247
248 Gives a list of sets of libraries. Each set of libraries should be
249 space-separated.
250
251 define => STRING
252
253 Optional. If specified, then the named symbol will be defined if the
254 program ran successfully. This will either on the C compiler
255 commandline (by passing an option -DSYMBOL), or in the defines_to
256 file.
257
258 find_cflags_for
259
260 $cc->find_cflags_for( %args );
261
262 find_include_dirs_for
263
264 $cc->find_include_dirs_for( %args );
265
266 find_libs_for
267
268 $cc->find_libs_for( %args );
269
270 Calls try_find_cflags_for, try_find_include_dirs_for or
271 try_find_libs_for respectively. If it fails, die with an OS unsupported
272 message.
273
274 Each method takes one extra optional argument:
275
276 diag => STRING
277
278 If present, this string will be appended to the failure message if
279 one is generated. It may provide more useful information to the user
280 on why the OS is unsupported.
281
282 extend_module_build
283
284 $cc->extend_module_build( $build );
285
286 Since version 0.11.
287
288 Sets the appropriate arguments into the given Module::Build instance.
289
290 new_module_build
291
292 $mb = $cc->new_module_build( %args );
293
294 Construct and return a new Module::Build object, preconfigured with the
295 include_dirs, extra_compiler_flags and extra_linker_flags options that
296 have been configured on this object, by the above methods.
297
298 This is provided as a simple shortcut for the common use case, that a
299 Build.PL file is using the ExtUtils::CChecker object to detect the
300 required arguments to pass.
301
302 EXAMPLES
303
304 Socket Libraries
305
306 Some operating systems provide the BSD sockets API in their primary
307 libc. Others keep it in a separate library which should be linked
308 against. The following example demonstrates how this would be handled.
309
310 use ExtUtils::CChecker;
311
312 my $cc = ExtUtils::CChecker->new;
313
314 $cc->find_libs_for(
315 diag => "no socket()",
316 libs => [ "", "socket nsl" ],
317 source => q[
318 #include <sys/socket.h>
319 int main(int argc, char *argv) {
320 int fd = socket(PF_INET, SOCK_STREAM, 0);
321 if(fd < 0)
322 return 1;
323 return 0;
324 }
325 ] );
326
327 $cc->new_module_build(
328 module_name => "Your::Name::Here",
329 requires => {
330 'IO::Socket' => 0,
331 },
332 ...
333 )->create_build_script;
334
335 By using the new_module_build method, the detected extra_linker_flags
336 value has been automatically passed into the new Module::Build object.
337
338 Testing For Optional Features
339
340 Sometimes a function or ability may be optionally provided by the OS,
341 or you may wish your module to be useable when only partial support is
342 provided, without requiring it all to be present. In these cases it is
343 traditional to detect the presence of this optional feature in the
344 Build.PL script, and define a symbol to declare this fact if it is
345 found. The XS code can then use this symbol to select between differing
346 implementations. For example, the Build.PL:
347
348 use ExtUtils::CChecker;
349
350 my $cc = ExtUtils::CChecker->new;
351
352 $cc->try_compile_run(
353 define => "HAVE_MANGO",
354 source => <<'EOF' );
355 #include <mango.h>
356 #include <unistd.h>
357 int main(void) {
358 if(mango() != 0)
359 exit(1);
360 exit(0);
361 }
362 EOF
363
364 $cc->new_module_build(
365 ...
366 )->create_build_script;
367
368 If the C code compiles and runs successfully, and exits with a true
369 status, the symbol HAVE_MANGO will be defined on the compiler
370 commandline. This allows the XS code to detect it, for example
371
372 int
373 mango()
374 CODE:
375 #ifdef HAVE_MANGO
376 RETVAL = mango();
377 #else
378 croak("mango() not implemented");
379 #endif
380 OUTPUT:
381 RETVAL
382
383 This module will then still compile even if the operating system lacks
384 this particular function. Trying to invoke the function at runtime will
385 simply throw an exception.
386
387 Linux Kernel Headers
388
389 Operating systems built on top of the Linux kernel often share a looser
390 association with their kernel version than most other operating
391 systems. It may be the case that the running kernel is newer,
392 containing more features, than the distribution's libc headers would
393 believe. In such circumstances it can be difficult to make use of new
394 socket options, ioctl()s, etc.. without having the constants that
395 define them and their parameter structures, because the relevant header
396 files are not visible to the compiler. In this case, there may be
397 little choice but to pull in some of the kernel header files, which
398 will provide the required constants and structures.
399
400 The Linux kernel headers can be found using the /lib/modules directory.
401 A fragment in Build.PL like the following, may be appropriate.
402
403 chomp( my $uname_r = `uname -r` );
404
405 my @dirs = (
406 [],
407 [ "/lib/modules/$uname_r/source/include" ],
408 );
409
410 $cc->find_include_dirs_for(
411 diag => "no PF_MOONLASER",
412 dirs => \@dirs,
413 source => <<'EOF' );
414 #include <sys/socket.h>
415 #include <moon/laser.h>
416 int family = PF_MOONLASER;
417 struct laserwl lwl;
418 int main(int argc, char *argv[]) {
419 return 0;
420 }
421 EOF
422
423 This fragment will first try to compile the program as it stands,
424 hoping that the libc headers will be sufficient. If it fails, it will
425 then try including the kernel headers, which should make the constant
426 and structure visible, allowing the program to compile.
427
428 Creating an #include file
429
430 Sometimes, rather than setting defined symbols on the compiler
431 commandline, it is preferrable to have them written to a C preprocessor
432 include (.h) file. This may be beneficial for cross-platform
433 portability concerns, as not all C compilers may take extra -D
434 arguments on the command line, or platforms may have small length
435 restrictions on the length of a command line.
436
437 use ExtUtils::CChecker;
438
439 my $cc = ExtUtils::CChecker->new(
440 defines_to => "mymodule-config.h",
441 );
442
443 $cc->try_compile_run(
444 define => "HAVE_MANGO",
445 source => <<'EOF' );
446 #include <mango.h>
447 #include <unistd.h>
448 #include "mymodule-config.h"
449 int main(void) {
450 if(mango() != 0)
451 exit(1);
452 exit(0);
453 }
454 EOF
455
456 Because the mymodule-config.h file is written and flushed after every
457 define operation, it will still be useable in later C fragments to test
458 for features detected in earlier ones.
459
460 It is suggested not to name the file simply config.h, as the core of
461 Perl itself has a file of that name containing its own compile-time
462 detected configuration. A confusion between the two could lead to
463 surprising results.
464
465 AUTHOR
466
467 Paul Evans <[email protected]>
468