ExtUtils::CChecker - configure-time utilities for using C headers,
libraries,
or OS features
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;
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.
Returns a new instance of a ExtUtils::CChecker object.
Returns the currently-configured include directories in an ARRAY reference.
Returns the currently-configured extra compiler flags in an ARRAY reference.
Returns the currently-configured extra linker flags in an ARRAY reference.
Try to complile, 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.
The source code of the C program to try compiling, building, and running.
Optional. If specified, pass extra flags to the compiler.
Optional. If specified, pass extra flags to the linker.
Optional. If specified, then the named symbol will be defined on the C compiler commandline if the program ran successfully (by passing an option -DSYMBOL).
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:
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.
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.
If no usable combination is found, an assertion message is thrown.
Takes the following arguments:
Source code to compile
Gives a list of sets of dirs. Each set of dirs should be strings in its own array reference.
If present, this string will be appended to the failure message if one is generated.
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.
If no usable combination is found, an assertion message is thrown.
Takes the following arguments:
Source code to compile
Gives a list of sets of libraries. Each set of libraries should be space-separated.
If present, this string will be appended to the failure message if one is generated.
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.
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.
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.
Paul Evans <leonerd@leonerd.org.uk>