SEARCH
NEW RPMS
DIRECTORIES
ABOUT
FAQ
VARIOUS
BLOG
DONATE




YUM REPOSITORY

 
 

MAN page from Mandriva 2010 perl-ExtUtils-CChecker-0.30.0-1mdv2010.1.noarch.rpm

ExtUtils::CChecker

Section: User Contributed Perl Documentation (3)
Updated: 2010-03-02
Index 

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 Cheaders, libraries, or to use OS-specific features. It is useful in theBuild.PL or Makefile.PL file to check for the existance of theserequirements before attempting to actually build the module.

Objects in this class provide an extension around ExtUtils::CBuilder tosimplify the creation of a .c file, compiling, linking and running it, totest 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 alsoprovides 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 complile, link, and execute a C program whose source is given. Returnstrue if the program compiled and linked, and exited successfully. Returnsfalse if any of these steps fail.

Takes the following named arguments. If a single argument is given, that istaken 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 Ccompiler commandline if the program ran successfully (by passing an option"-DSYMBOL").

 

$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 isgenerated. It may provide more useful information to the user on why the OS isunsupported.

 

$cc->find_include_dirs_for( %args )

Try to compile, link and execute the given source, using extra includedirectories.

When a usable combination is found, the directories required are stored in theobject 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 => 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 ownarray reference.

*
diag => STRING

If present, this string will be appended to the failure message if one isgenerated.

 

$cc->find_libs_for( %args )

Try to compile, link and execute the given source, when linked against agiven set of extra libraries.

When a usable combination is found, the libraries required are stored in theobject 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 => STRING

Source code to compile

*
libs => ARRAY of STRINGs

Gives a list of sets of libraries. Each set of libraries should bespace-separated.

*
diag => STRING

If present, this string will be appended to the failure message if one isgenerated.

 

$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" optionsthat have been configured on this object, by the above methods.

This is provided as a simple shortcut for the common use case, that aBuild.PL file is using the "ExtUtils::CChecker" object to detect therequired 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. Thefollowing 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 youmay 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 todetect the presence of this optional feature in the Build.PL script, anddefine a symbol to declare this fact if it is found. The XS code can then usethis symbol to select between differing implementations. For example, theBuild.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. Thisallows 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 thisparticular function. Trying to invoke the function at runtime will simplythrow an exception. 

AUTHOR

Paul Evans <leonerdAATTleonerd.org.uk>


 

Index

NAME
SYNOPSIS
DESCRIPTION
CONSTRUCTOR
$cc = ExtUtils::CChecker->new
METHODS
$dirs = $cc->include_dirs
$flags = $cc->extra_compiler_flags
$flags = $cc->extra_linker_flags
$success = $cc->try_compile_run( %args )
$success = $cc->try_compile_run( $source )
$cc->assert_compile_run( %args )
$cc->find_include_dirs_for( %args )
$cc->find_libs_for( %args )
$mb = $cc->new_module_build( %args )
EXAMPLES
Socket Libraries
Testing For Optional Features
AUTHOR

This document was created byman2html,using the manual pages.