1ExtUtils::CChecker(3) User Contributed Perl DocumentationExtUtils::CChecker(3)
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 $check_PF_MOONLASER = <<'EOF';
14 #include <stdio.h>
15 #include <sys/socket.h>
16 int main(int argc, char *argv[]) {
17 printf("PF_MOONLASER is %d\n", PF_MOONLASER);
18 return 0;
19 }
20 EOF
21 ExtUtils::CChecker->new->assert_compile_run(
23 diag => "no PF_MOONLASER",
24 source => $check_PF_MOONLASER,
25 );
26 Module::Build->new(
28 ...
29 )->create_build_script;
30
32 Often Perl modules are written to wrap functionallity found in existing
33 C headers, libraries, or to use OS-specific features. It is useful in
34 the Build.PL or Makefile.PL file to check for the existance of these
35 requirements before attempting to actually build the module.
36 Objects in this class provide an extension around ExtUtils::CBuilder to
38 simplify the creation of a .c file, compiling, linking and running it,
39 to test if a certain feature is present.
40 It may also be necessary to search for the correct library to link
42 against, or for the right include directories to find header files in.
43 This class also provides assistance here.
44
46 $cc = ExtUtils::CChecker->new
47 Returns a new instance of a "ExtUtils::CChecker" object.
48
50 $dirs = $cc->include_dirs
51 Returns the currently-configured include directories in an ARRAY
52 reference.
53 $flags = $cc->extra_compiler_flags
55 Returns the currently-configured extra compiler flags in an ARRAY
56 reference.
57 $flags = $cc->extra_linker_flags
59 Returns the currently-configured extra linker flags in an ARRAY
60 reference.
61 $success = $cc->try_compile_run( %args )
63 $success = $cc->try_compile_run( $source )
64 Try to compile, link, and execute a C program whose source is given.
65 Returns true if the program compiled and linked, and exited
66 successfully. Returns false if any of these steps fail.
67 Takes the following named arguments. If a single argument is given,
69 that is taken as the source string.
70 · source => STRING
72 The source code of the C program to try compiling, building,
74 and running.
75 · extra_compiler_flags => ARRAY
77 Optional. If specified, pass extra flags to the compiler.
79 · extra_linker_flags => ARRAY
81 Optional. If specified, pass extra flags to the linker.
83 · define => STRING
85 Optional. If specified, then the named symbol will be defined
87 on the C compiler commandline if the program ran successfully
88 (by passing an option "-DSYMBOL").
89 $cc->assert_compile_run( %args )
91 Calls "try_compile_run". If it fails, die with an "OS unsupported"
92 message. Useful to call from Build.PL or Makefile.PL.
93 Takes one extra optional argument:
95 · diag => STRING
97 If present, this string will be appended to the failure message
99 if one is generated. It may provide more useful information to
100 the user on why the OS is unsupported.
101 $success = $cc->try_find_include_dirs_for( %args )
103 Try to compile, link and execute the given source, using extra include
104 directories.
105 When a usable combination is found, the directories required are stored
107 in the object for use in further compile operations, or returned by
108 "include_dirs". The method then returns true.
109 If no a usable combination is found, it returns false.
111 Takes the following arguments:
113 · source => STRING
115 Source code to compile
117 · dirs => ARRAY of ARRAYs
119 Gives a list of sets of dirs. Each set of dirs should be
121 strings in its own array reference.
122 · define => STRING
124 Optional. If specified, then the named symbol will be defined
126 on the C compiler commandline if the program ran successfully
127 (by passing an option "-DSYMBOL").
128 $success = $cc->try_find_libs_for( %args )
130 Try to compile, link and execute the given source, when linked against
131 a given set of extra libraries.
132 When a usable combination is found, the libraries required are stored
134 in the object for use in further link operations, or returned by
135 "extra_linker_flags". The method then returns true.
136 If no usable combination is found, it returns false.
138 Takes the following arguments:
140 · source => STRING
142 Source code to compile
144 · libs => ARRAY of STRINGs
146 Gives a list of sets of libraries. Each set of libraries should
148 be space-separated.
149 · define => STRING
151 Optional. If specified, then the named symbol will be defined
153 on the C compiler commandline if the program ran successfully
154 (by passing an option "-DSYMBOL").
155 $cc->find_include_dirs_for( %args )
157 $cc->find_libs_for( %args )
158 Calls "try_find_include_dirs_for" or "try_find_libs_for" respectively.
159 If it fails, die with an "OS unsupported" message.
160 Each method takes one extra optional argument:
162 · diag => STRING
164 If present, this string will be appended to the failure message
166 if one is generated. It may provide more useful information to
167 the user on why the OS is unsupported.
168 $mb = $cc->new_module_build( %args )
170 Construct and return a new Module::Build object, preconfigured with the
171 "include_dirs", "extra_compiler_flags" and "extra_linker_flags" options
172 that have been configured on this object, by the above methods.
173 This is provided as a simple shortcut for the common use case, that a
175 Build.PL file is using the "ExtUtils::CChecker" object to detect the
176 required arguments to pass.
177
179 Socket Libraries
180 Some operating systems provide the BSD sockets API in their primary
181 libc. Others keep it in a separate library which should be linked
182 against. The following example demonstrates how this would be handled.
183 use Module::Build;
185 use ExtUtils::CChecker;
186 my $cc = ExtUtils::CChecker->new;
188 $cc->find_libs_for(
190 diag => "no socket()",
191 libs => [ "", "socket nsl" ],
192 source => q[
193 #include <sys/socket.h>
194 int main(int argc, char *argv) {
195 int fd = socket(PF_INET, SOCK_STREAM, 0);
196 if(fd < 0)
197 return 1;
198 return 0;
199 }
200 ] );
201 $cc->new_module_build(
203 module_name => "Your::Name::Here",
204 requires => {
205 'IO::Socket' => 0,
206 },
207 ...
208 )->create_build_script;
209 By using the "new_module_build" method, the detected
211 "extra_linker_flags" value has been automatically passed into the new
212 "Module::Build" object.
213 Testing For Optional Features
215 Sometimes a function or ability may be optionally provided by the OS,
216 or you may wish your module to be useable when only partial support is
217 provided, without requiring it all to be present. In these cases it is
218 traditional to detect the presence of this optional feature in the
219 Build.PL script, and define a symbol to declare this fact if it is
220 found. The XS code can then use this symbol to select between differing
221 implementations. For example, the Build.PL:
222 use Module::Build;
224 use ExtUtils::CChecker;
225 my $cc = ExtUtils::CChecker->new;
227 $cc->try_compile_run(
229 define => "HAVE_MANGO",
230 source => <<'EOF' );
231 #include <mango.h>
232 #include <unistd.h>
233 int main(void) {
234 if(mango() != 0)
235 exit(1);
236 exit(0);
237 }
238 EOF
239 $cc->new_module_build(
241 ...
242 )->create_build_script;
243 If the C code compiles and runs successfully, and exits with a true
245 status, the symbol "HAVE_MANGO" will be defined on the compiler
246 commandline. This allows the XS code to detect it, for example
247 int
249 mango()
250 CODE:
251 #ifdef HAVE_MANGO
252 RETVAL = mango();
253 #else
254 croak("mango() not implemented");
255 #endif
256 OUTPUT:
257 RETVAL
258 This module will then still compile even if the operating system lacks
260 this particular function. Trying to invoke the function at runtime will
261 simply throw an exception.
262 Linux Kernel Headers
264 Operating systems built on top of the Linux kernel often share a looser
265 association with their kernel version than most other operating
266 systems. It may be the case that the running kernel is newer,
267 containing more features, than the distribution's libc headers would
268 believe. In such circumstances it can be difficult to make use of new
269 socket options, "ioctl()"s, etc.. without having the constants that
270 define them and their parameter structures, because the relevant header
271 files are not visible to the compiler. In this case, there may be
272 little choice but to pull in some of the kernel header files, which
273 will provide the required constants and structures.
274 The Linux kernel headers can be found using the /lib/modules directory.
276 A fragment in Build.PL like the following, may be appropriate.
277 chomp( my $uname_r = `uname -r` );
279 my @dirs = (
281 [],
282 [ "/lib/modules/$uname_r/source/include" ],
283 );
284 $cc->find_include_dirs_for(
286 diag => "no PF_MOONLASER",
287 dirs => \@dirs,
288 source => <<'EOF' );
289 #include <sys/socket.h>
290 #include <moon/laser.h>
291 int family = PF_MOONLASER;
292 struct laserwl lwl;
293 int main(int argc, char *argv[]) {
294 return 0;
295 }
296 EOF
297 This fragment will first try to compile the program as it stands,
299 hoping that the libc headers will be sufficient. If it fails, it will
300 then try including the kernel headers, which should make the constant
301 and structure visible, allowing the program to compile.
302
304 Paul Evans <leonerd@leonerd.org.uk>
305perl v5.12.1 2010-08-22 ExtUtils::CChecker(3)