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.

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.

Socket Libraries

   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

   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

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

   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.