ExtUti...hecker(3pm)

📦

version 0.12 · 13 versions

✨ NAME ✨

Bestie, this is the ExtUtils::CChecker(3pm) page 💖 — configure-time utilities for using C headers, libraries, or OS features. That's the whole vibe, and it's lowkey iconic.

🌸 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 🦋

Okay so, often Perl modules are written to wrap functionality found in existing C headers, libraries, or to use OS-specific features. And it's genuinely useful in the Build.PL or Makefile.PL file to check whether those requirements are even there before you try to actually build the module. Like, vibe-check the OS first, y'know? 💅

Objects in this class give you an extension around ExtUtils::CBuilder that simplifies creating a .c file, compiling it, linking it, and running it — all so you can test whether a certain feature is present. It's giving "tiny C probe, big main character energy."

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 there 🫶.

🛠️ CONSTRUCTOR 🛠️

new

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

Returns a new instance of an ExtUtils::CChecker object. It takes these 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. Choose your fighter: header file or compiler flag.
quiet => BOOL — If given, sets the quiet option on the underlying ExtUtils::CBuilder instance. If absent, it defaults to enabled. To disable quietness — i.e., to print more verbosely — pass a defined-but-false value, such as 0. Yes, 0 is doing important work here.
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.

define

$cc->define( $symbol );

Adds a new defined symbol directly — either by appending to the compiler flags or by writing it into the defines file. Two paths, one symbol.

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. It's a whole little pipeline, bestie — compile, link, run, believe.

It takes the following named arguments. If a single argument is given, that argument 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 be 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. It's like a bouncer at the club: no feature, no entry 💀.

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

It 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 usable combination is found, it returns false.

It 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 be 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.

It 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 be 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. Respectfully, that's the drama.

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. Plug it in, plug it in 🔌.

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. Honestly? Convenient. Obsessed.

✨ EXAMPLES ✨

🧦 Socket Libraries 🧦

Okay so some operating systems are nice and put the BSD sockets API right in their primary libc. Others keep it in a separate library, and bestie, you gotta link against it. Here's how you'd handle that whole situation:

          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;

The slay here is that by using the new_module_build method, the detected extra_linker_flags value gets automatically passed into the new Module::Build object. No extra manual passing, it just happens. 💅

🦋 Testing For Optional Features 🦋

Sometimes a function or ability is optionally provided by the OS, or maybe you want your module to be useable when only partial support is provided — without requiring absolutely everything to be present. In those cases it's traditional to detect whether this optional feature exists in the Build.PL script, and define a symbol to declare that fact if it's found. Then the XS code can use that symbol to pick between different implementations. For example, here's 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, then the symbol HAVE_MANGO will be defined on the compiler commandline. That lets the XS code detect it, like this:

          int
          mango()
            CODE:
          #ifdef HAVE_MANGO
              RETVAL = mango();
          #else
              croak("mango() not implemented");
          #endif
            OUTPUT:
              RETVAL

So this module will still compile even if the operating system lacks this particular function. But trying to invoke the function at runtime will simply throw an exception. Lowkey graceful, highkey iconic. 😭

🌈 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 do. It may be the case that the running kernel is newer — containing more features — than the distribution's libc headers would believe. In those 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 aren't 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 the libc headers are sufficient. If that fails, it will then try including the kernel headers, which should make the constant and structure visible, allowing the program to compile. It's giving "try the basic fit first, then bring out the big header energy." ✨

🎀 Creating an `#include` file 🎀

Sometimes, instead of setting defined symbols on the compiler commandline, it's preferable to have them written to a C preprocessor include (.h) file. This can be beneficial for cross-platform portability concerns, because 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. Obsessed with continuity, honestly. 🫶

It is suggested not to name the file simply config.h, because 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. So like… don't do that one, bestie. 💀

👑 AUTHOR 👑

Paul Evans <leonerd@leonerd.org.uk>

That's the whole vibe, and the source/version/date lore at the bottom is: perl v5.40.0, dated 2024-03-05. Sign-off complete, mwah. 💖🎀

📦 where this page comes from

epel 10: perl-ExtUtils-CChecker 0.12-1.el10_0 · GPL-1.0-or-later OR Artistic-1.0-Perl
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash-1017 on 2026-11-06: a language model's rewrite of the original, under its terms

ExtUti...hecker(3pm)

✨ NAME ✨

🌸 SYNOPSIS 🌸

🦋 DESCRIPTION 🦋

🛠️ CONSTRUCTOR 🛠️

new

💜 METHODS 💜

include_dirs

extra_compiler_flags

extra_linker_flags

push_include_dirs

push_extra_compiler_flags

push_extra_linker_flags

define

try_compile_run

assert_compile_run

try_find_cflags_for

try_find_include_dirs_for

try_find_libs_for

find_cflags_for

find_include_dirs_for

find_libs_for

extend_module_build

new_module_build

✨ EXAMPLES ✨

🧦 Socket Libraries 🧦

🦋 Testing For Optional Features 🦋

🌈 Linux Kernel Headers 🌈

🎀 Creating an #include file 🎀

👑 AUTHOR 👑

🎀 Creating an `#include` file 🎀