NAME

ExtUtils::Builder::Conf - Configure-time utilities for using C headers, libraries, or OS features

VERSION

version 0.022

SYNOPSIS

 load_module("ExtUtils::Builder::Conf");
 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

DESCRIPTION

Often Perl modules are written to wrap functionality found in existing C headers, libraries, or to use OS-specific features. It is useful to check for the existance of these requirements before attempting to actually build the module.

Objects in this class provide an extension around ExtUtils::Builder::Compiler 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.

DELEGATES

try_compile_run

 $success = try_compile_run(%args);

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:

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.
quiet => BOOL: This makes try_compile_run run quietly.
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), in the defines method, or via the write_defines method.

assert_compile_run

 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 = try_find_cflags_for(%args);

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. This will either on the C compiler commandline (by passing an option -DSYMBOL), in the defines method, or via the write_defines method.

try_find_include_dirs_for

 $success = 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), in the defines method, or via the write_defines method.

try_find_libraries_for

 $success = try_find_libraries_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 libraries. 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), in the defines method, or via the write_defines method.

try_find_library_dirs_for

 $success = try_find_library_dirs_for(%args);

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

When a usable combination is found, the directories required are stored in the object for use in further compile operations, or returned by library_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), in the defines method, or via the write_defines method.

find_cflags_for

 find_cflags_for(%args);

find_include_dirs_for

 find_include_dirs_for(%args);

find_libraries_for

 find_libraries_for(%args);

Calls try_find_cflags_for, try_find_include_dirs_for or try_find_libraries_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.

include_dirs

 $dirs = include_dirs;

Returns the currently-configured include directories as an array.

library_dirs

 $dirs = library_dirs;

Returns the currently-configured library directories as an array.

libraries

 $libs = libraries;

Returns the currently-configured libraries as an array.

extra_compiler_flags

 $flags = extra_compiler_flags;

Returns the currently-configured extra compiler flags as an array.

extra_linker_flags

 $flags = extra_linker_flags;

Returns the currently-configured extra linker flags as an array.

push_include_dirs

 push_include_dirs(@dirs);

Adds more include directories

push_library_dirs

 push_library_dirs(@dirs);

Adds more library directories

push_libraries

 push_libraries(@libs);

Adds more libraries

push_extra_compiler_flags

 push_extra_compiler_flags(@flags);

Adds more compiler flags

push_extra_linker_flags

 push_extra_linker_flags(@flags);

Adds more linker flags

define

 define($symbol);

Adds a new defined symbol directly; either by appending to the compiler flags or writing it into the defines file.

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.

 find_libraries_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;
 }
 ]);

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:

 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

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" ],
   );

   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

Leon Timmermans <fawaka@gmail.com>

COPYRIGHT AND LICENSE

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.

To install ExtUtils::Builder::Compiler, copy and paste the appropriate command in to your terminal.

cpanm

cpanm ExtUtils::Builder::Compiler

CPAN shell

perl -MCPAN -e shell
install ExtUtils::Builder::Compiler

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

VERSION

SYNOPSIS

DESCRIPTION

DELEGATES

try_compile_run

assert_compile_run

try_find_cflags_for

try_find_include_dirs_for

try_find_libraries_for

try_find_library_dirs_for

find_cflags_for

find_include_dirs_for

find_libraries_for

include_dirs

library_dirs

libraries

extra_compiler_flags

extra_linker_flags

push_include_dirs

push_library_dirs

push_libraries

push_extra_compiler_flags

push_extra_linker_flags

define

EXAMPLES

Socket Libraries

Testing For Optional Features

Linux Kernel Headers

AUTHOR

COPYRIGHT AND LICENSE

Module Install Instructions