Provided by: libextutils-cchecker-perl_0.11-3_all bug

NAME

       "ExtUtils::CChecker" - configure-time utilities for using C headers, libraries, or OS
       features

SYNOPSIS

          use Module::Build;
          use ExtUtils::CChecker;

          my $cc = ExtUtils::CChecker->new;

          $cc->assert_compile_run(
             diag => "no PF_MOONLASER",
             source => <<'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

          Module::Build->new(
            ...
          )->create_build_script;

DESCRIPTION

       Often Perl modules are written to wrap functionality 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

   new
          $cc = ExtUtils::CChecker->new( %args )

       Returns a new instance of a "ExtUtils::CChecker" object. Takes the following named
       parameters:

       defines_to => PATH
           If given, defined symbols will be written to a C preprocessor .h file of the given
           name, instead of by adding extra "-DSYMBOL" arguments to the compiler flags.

       quiet => BOOL
           If given, sets the "quiet" option to the underlying "ExtUtils::CBuilder" instance. If
           absent, defaults to enabled. To disable quietness, i.e. to print more verbosely, pass
           a defined-but-false value, such as 0.

       config => HASH
           If given, passed through as the configuration of the underlying "ExtUtils::CBuilder"
           instance.

METHODS

   include_dirs
          $dirs = $cc->include_dirs

       Returns the currently-configured include directories in an ARRAY reference.

   extra_compiler_flags
          $flags = $cc->extra_compiler_flags

       Returns the currently-configured extra compiler flags in an ARRAY reference.

   extra_linker_flags
          $flags = $cc->extra_linker_flags

       Returns the currently-configured extra linker flags in an ARRAY reference.

   push_include_dirs
          $cc->push_include_dirs( @dirs )

       Adds more include directories

   push_extra_compiler_flags
          $cc->push_extra_compiler_flags( @flags )

       Adds more compiler flags

   push_extra_linker_flags
          $cc->push_extra_linker_flags( @flags )

       Adds more linker flags

   try_compile_run
          $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 if the program ran
           successfully. This will either on the C compiler commandline (by passing an option
           "-DSYMBOL"), or in the "defines_to" file.

   assert_compile_run
          $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.

   try_find_cflags_for
          $success = $cc->try_find_cflags_for( %args )

       Since version 0.11.

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

       When a usable combination is found, the flags are stored in the object for use in further
       compile operations, or returned by "extra_compiler_flags". The method then returns true.

       If no usable combination is found, it returns false.

       Takes the following extra arguments:

       source => STRING
           Source code to compile

       cflags => ARRAY of ARRAYs
           Gives a list of sets of flags. Each set of flags should be strings in its own array
           reference.

       define => STRING
           Optional. If specified, then the named symbol will be defined if the program ran
           successfully.

   try_find_include_dirs_for
          $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 if the program ran
           successfully. This will either on the C compiler commandline (by passing an option
           "-DSYMBOL"), or in the "defines_to" file.

   try_find_libs_for
          $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 if the program ran
           successfully. This will either on the C compiler commandline (by passing an option
           "-DSYMBOL"), or in the "defines_to" file.

   find_cflags_for
          $cc->find_cflags_for( %args )

   find_include_dirs_for
          $cc->find_include_dirs_for( %args )

   find_libs_for
          $cc->find_libs_for( %args )

       Calls "try_find_cflags_for", "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.

   extend_module_build
          $cc->extend_module_build( $build )

       Since version 0.11.

       Sets the appropriate arguments into the given Module::Build instance.

   new_module_build
          $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 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 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.

   Creating an "#include" file
       Sometimes, rather than setting defined symbols on the compiler commandline, it is
       preferrable to have them written to a C preprocessor include (.h) file.  This may be
       beneficial for cross-platform portability concerns, as not all C compilers may take extra
       "-D" arguments on the command line, or platforms may have small length restrictions on the
       length of a command line.

          use ExtUtils::CChecker;

          my $cc = ExtUtils::CChecker->new(
             defines_to => "mymodule-config.h",
          );

          $cc->try_compile_run(
             define => "HAVE_MANGO",
             source => <<'EOF' );
          #include <mango.h>
          #include <unistd.h>
          #include "mymodule-config.h"
          int main(void) {
            if(mango() != 0)
              exit(1);
            exit(0);
          }
          EOF

       Because the mymodule-config.h file is written and flushed after every define operation, it
       will still be useable in later C fragments to test for features detected in earlier ones.

       It is suggested not to name the file simply config.h, as the core of Perl itself has a
       file of that name containing its own compile-time detected configuration. A confusion
       between the two could lead to surprising results.

AUTHOR

       Paul Evans <leonerd@leonerd.org.uk>