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

       Leon Timmermans <fawaka@gmail.com>

       This software is copyright (c) 2012 by Leon Timmermans.

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

perl v5.40.1                                       2025-05-16                       ExtUtils::Builder::Conf(3pm)

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.

       defines => HASH
           Optional. A set of defines to be passed to the compiler.

       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.

       include_dirs => ARRAY
           Optional. If specified, pass extra include dirs to the compiler.

       libraries => ARRAY
           Optional. If specified, pass extra libaries to the linker.

       library_dirs => ARRAY
           Optional. If specified, pass extra libary directories 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.

       push_args => BOOL
           If  true,  any  of   "extra_compiler_flags",   "extra_linker_flags",   "include_dirs",   "libraries",
           "library_dirs"  or  "defines" will have its value pushed on success (e.g. "push_include_dirs" for the
           "include_dirs" argument).

   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.

       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.

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

   TestingForOptionalFeatures
       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.

   LinuxKernelHeaders
       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.

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

        load_extension("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

       version 0.032