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