xsubpp

xsubpp [-C] [-nolinkage] [-typemap file] [-proto|-prototypes]
[-noprototypes] [-stubs file] [-nostubs] [-q|-quiet] [-o file] [inputfile]

-C
    Retain C comments in the output C code, which can be useful for debugging the generated code.

-nolinkage
    Do not generate the XS_BOOT_TYPEMAP and XS_APIVERSION linkage code. This option is typically used internally when building specific parts of Perl itself.

-typemap file
    Specify an additional typemap file to use. Typemaps define how C types are converted to and from Perl scalars, facilitating seamless data exchange between Perl and C.

-proto, -prototypes
    Force the generation of prototypes for all XSUBs (XS subroutines). This ensures stricter argument checking at compile time, catching potential errors early.

-noprototypes
    Suppress the generation of prototypes for XSUBs, overriding any default behavior or directives in the XS code. This might be used for compatibility with older compilers or specific build setups.

-stubs file
    Generate stub functions to the specified file. Stubs are small C functions that provide an interface for static linking with Perl libraries, useful in scenarios where dynamic loading is not an option.

-nostubs
    Do not generate stub functions, suitable for environments where dynamic loading of Perl modules is always the preferred or only method.

-q, -quiet
    Suppress verbose output and warnings during the processing of the XS file, leading to a cleaner build log.

-o file
    Specify the output C file. If this option is omitted, xsubpp writes the generated C code to standard output (stdout).

inputfile
    The path to the input XS source file (e.g., MyModule.xs). If omitted, xsubpp reads the XS source from standard input (stdin).

xsubpp is a vital internal utility within the Perl ecosystem, specifically designed to process Perl XS (eXtension Subroutine) source files. XS is a language that allows Perl modules to be written partly in C or C++, enabling Perl to interface with external C libraries or for performance-critical sections. xsubpp takes an .xs file as input, which contains a mix of Perl and C code, and translates it into a .c file. This generated .c file can then be compiled by a standard C compiler into a shared library (e.g., .so on Linux, .dll on Windows), which Perl can dynamically load.

While xsubpp is a standalone executable, it is almost exclusively invoked indirectly by Perl's build tools, such as ExtUtils::MakeMaker or Module::Build, through the ExtUtils::ParseXS module. Developers typically do not run xsubpp manually. Its primary role is to handle the interface glue between Perl and C, managing argument passing, return values, and type conversions, thereby simplifying the development of XS modules.

xsubpp is an internal utility primarily used by Perl's build system (e.g., ExtUtils::MakeMaker and Module::Build). It is generally not intended for direct manual invocation by end-users or even most module developers. Misuse can lead to incorrectly generated C code and compilation errors. Its options and behavior are tightly coupled with the ExtUtils::ParseXS module, which manages its invocation.

XS (eXtension Subroutine) is a language specification used within Perl for writing modules that require high performance or direct interaction with C/C++ libraries. It allows developers to seamlessly integrate C code into Perl, handling the complexities of data type conversions and function calls between the two languages.

When a Perl module contains XS code, the Makefile.PL (generated by ExtUtils::MakeMaker) or Build.PL script (from Module::Build) will orchestrate the compilation process. This typically involves ExtUtils::ParseXS calling xsubpp to convert .xs files to .c files, which are then compiled by a C compiler (like GCC) into a shared library. This shared library is what Perl loads when the module is used, extending Perl's capabilities with compiled code.

xsubpp has been a fundamental component of the Perl core distribution for many years, dating back to early versions of Perl 5. Its development is intertwined with the evolution of Perl's XS interface, enabling robust and efficient integration with C/C++ libraries. It has continuously evolved to support new Perl features and improve the C binding process, remaining a critical, though often unseen, tool for Perl's extensibility.

perl(1), ExtUtils::ParseXS(3pm), ExtUtils::MakeMaker(3pm), Module::Build(3pm), perlxs(1), perlguts(1)