EXTUTILS::CBUILDER(3pm)

📦
version 5.42.3 · 10 versions
, in alpine 3.24

💅 ExtUtils::CBuilder 💅

okay so bestie, welcome to ExtUtils::CBuilder — straight out of the Perl Programmers Reference Guide, no cap. this is the little module that handles the C parts of your Perl modules so you don't have to scream at make at 2am 🫶

✨ NAME ✨

ExtUtils::CBuilder — compile and link C code for Perl modules 🎀

🦋 SYNOPSIS 🦋

use ExtUtils::CBuilder;

my $b = ExtUtils::CBuilder->new(%options);
$obj_file = $b->compile(source => 'MyModule.c');
$lib_file = $b->link(objects => $obj_file);

that's the whole vibe honestly. make a builder, compile a thing, link a thing. iconic 🌸

💖 DESCRIPTION 💖

so this module builds the C portions of Perl modules by invoking the appropriate compilers and linkers in a cross-platform way ✨ it was motivated by the Module::Build project, but it may be useful for other purposes as well.

but hear me when I say this — it is not intended as a general cross-platform interface to all your C building needs. that would have been a much more ambitious goal! 💀 so like, don't come for it with your whole entire toolchain, it's doing one job and it's slaying at that one job 👑

🌈 METHODS 🌈

⭐ new

Returns a new ExtUtils::CBuilder object 🫶

A config parameter lets you override Config.pm settings for all operations performed by the object, as in the following example:

# Use a different compiler than Config.pm says
my $b = ExtUtils::CBuilder->new( config =>
                                 { ld => 'gcc' } );

A quiet parameter tells CBuilder to not print its system() commands before executing them:

# Be quieter than normal
my $b = ExtUtils::CBuilder->new( quiet => 1 );

so like, if the command spam is giving too much main character energy for your terminal, quiet is your girl 💅

⭐ have_compiler

Returns true if the current system has a working C compiler and linker, false otherwise 🎯

and the way it finds out? it literally just tries it — we actually compile and link a sample C library. no vibes-based guessing here, it's a real vibe check 😭

the sample will be compiled in the system tempdir or, if that fails for some reason, in the current directory 📁

⭐ have_cplusplus

Just like have_compiler — but for C++ instead of C 🔥 same energy, different language.

⭐ compile

Compiles a C source file and produces an object file. the name of the object file is returned ✨

the source file is specified in a source parameter, which is required; the other parameters listed below are optional 🎀

  • object_file — Specifies the name of the output file to create. Otherwise the object_file() method will be consulted, passing it the name of the source file.
  • include_dirs — Specifies any additional directories in which to search for header files. May be given as a string indicating a single directory, or as a list reference indicating multiple directories. 📚
  • extra_compiler_flags — Specifies any additional arguments to pass to the compiler. Should be given as a list reference containing the arguments individually, or if this is not possible, as a string containing all the arguments together.
  • C++ — Specifies that the source file is a C++ source file and sets appropriate compiler flags 🔥
also heads up bestie: the operation of this method is also affected by the archlibexp, cccdlflags, ccflags, optimize, and cc entries in Config.pm 👀

Invokes the linker to produce a library file from object files 🧚

in scalar context, the name of the library file is returned. in list context, the library file and any temporary files created are returned 🎁

a required objects parameter contains the name of the object files to process, either in a string (for one object file) or list reference (for one or more files).

the following parameters are optional:

  • lib_file — Specifies the name of the output library file to create. Otherwise the lib_file() method will be consulted, passing it the name of the first entry in objects.
  • module_name — Specifies the name of the Perl module that will be created by linking. On platforms that need to do prelinking (Win32, OS/2, etc.) this is a required parameter 😤
  • extra_linker_flags — Any additional flags you wish to pass to the linker.

on platforms where need_prelink() returns true, prelink() will be called automatically ⚙️

and again, this method is also affected by the lddlflags, shrpenv, and ld entries in Config.pm 👑

Invokes the linker to produce an executable file from object files 🚀

in scalar context, the name of the executable file is returned. in list context, the executable file and any temporary files created are returned.

a required objects parameter contains the name of the object files to process, either in a string (for one object file) or list reference (for one or more files).

the optional parameters are the same as link — with the exception of:

  • exe_file — Specifies the name of the output executable file to create. Otherwise the exe_file() method will be consulted, passing it the name of the first entry in objects.

⭐ object_file

my $object_file = $b->object_file($source_file);

Converts the name of a C source file to the most natural name of an output object file to create from it 💅

for instance, on Unix the source file foo.c would result in the object file foo.o — it's giving "we know what you meant" ✨

⭐ lib_file

my $lib_file = $b->lib_file($object_file);

Converts the name of an object file to the most natural name of a output library file to create from it 🎀

for instance, on Mac OS X the object file foo.o would result in the library file foo.bundle 🍓

⭐ exe_file

my $exe_file = $b->exe_file($object_file);

Converts the name of an object file to the most natural name of an executable file to create from it.

for instance, on Mac OS X the object file foo.o would result in the executable file foo, and on Windows it would result in foo.exe 💀 (Windows really said "gotta have the extension, bestie")

okay so on certain platforms like Win32, OS/2, VMS, and AIX, it is necessary to perform some actions before invoking the linker 😤

the ExtUtils::Mksymlists module does this, writing files used by the linker during the creation of shared libraries for dynamic extensions.

the names of any files written will be returned as a list 📋

several parameters correspond to ExtUtils::Mksymlists::Mksymlists() options, as follows:

    Mksymlists()   prelink()          type
   -------------|-------------------|-------------------
    NAME        |  dl_name          | string (required)
    DLBASE      |  dl_base          | string
    FILE        |  dl_file          | string
    DL_VARS     |  dl_vars          | array reference
    DL_FUNCS    |  dl_funcs         | hash reference
    FUNCLIST    |  dl_func_list     | array reference
    IMPORTS     |  dl_imports       | hash reference
    VERSION     |  dl_version       | string

Please see the documentation for ExtUtils::Mksymlists for the details of what these parameters do 📖 (iykyk, go read it, it's right there)

Returns true on platforms where prelink() should be called during linking, and false otherwise ✅❌

Returns a list of extra arguments to give to the link command 🫶

the arguments are the same as for prelink(), with the addition of an array reference to the results of prelink(); this reference is indexed by key prelink_res 🎯

🚧 TO DO 🚧

Currently this has only been tested on Unix and doesn't contain any of the Windows-specific code from the Module::Build project. I'll do that next 😭 (we believe in you, whoever "I" is)

📜 HISTORY 📜

This module is an outgrowth of the Module::Build project, to which there have been many contributors 💖

Notably, Randy W. Sims submitted lots of code to support 3 compilers on Windows and helped with various other platform-specific issues. Ilya Zakharevich has contributed fixes for OS/2; John E. Malmberg and Peter Prymmer have done likewise for VMS 👑👑👑

🫶 SUPPORT 🫶

ExtUtils::CBuilder is maintained as part of the Perl 5 core 🌟

Please submit any bug reports via the perlbug tool included with Perl 5. Bug reports will be included in the Perl 5 ticket system at <https://rt.perl.org> 🎀

The Perl 5 source code is available at <https://perl5.git.perl.org/perl.git> and ExtUtils-CBuilder may be found in the dist/ExtUtils-CBuilder directory of the repository 📁✨

👑 AUTHOR 👑

Ken Williams, kwilliams@cpan.org

Additional contributions by The Perl 5 Porters 💜

Copyright (c) 2003-2005 Ken Williams. All rights reserved.

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself 🌈

🌸 SEE ALSO 🌸

and that's the whole page bestie, you ate 💅✨ sign-off time: this was perl v5.42.3, dated 2026-11-03, living its best life as ExtUtils::CBuilder(3pm) — go compile something iconic 🦋🎀

📦 where this page comes from