LinuxCommandLibrary

h2xs

Convert C header files into Perl extensions

SYNOPSIS

h2xs [options] [module_name | header_file...]

PARAMETERS

-A
    Do not generate auxiliary files like Makefile.PL, README, test.pl, etc. Only creates the .xs file.

-B
    Do not add a BOOT: section to the .xs file.

-C
    Do not generate a CHANGES file.

-D
    Do not generate POD documentation in the .pm file. (Same as -P).

-F
    Do not create a Makefile.PL file.

-H
    Do not include ExtUtils::MakeMaker specific hints in Makefile.PL.

-M
    Do not include any ExtUtils::MakeMaker specific options or arguments in Makefile.PL.

-P
    Do not generate POD documentation in the .pm file. (Same as -D).

-T
    Do not generate test.pl or t/*.t files.

-V
    Print version information and exit.

-X
    Do not add extern "C" declaration in the generated .xs file.

-a
    Add boilerplate for the AUTOLOAD subroutine.

-c [header_file ...]
    Take existing C header files to generate an .xs file. Overrides new module creation.

-d directory
    Create generated files in the specified directory.

-e
    Force export of all symbols found in the header file(s).

-f
    Force overwrite of existing files without prompting.

-k
    Keep Makefile.PL around after perl Makefile.PL runs.

-l library
    Add -llibrary to LIBS in Makefile.PL. Can be specified multiple times.

-m module
    Specify the module name. Equivalent to -n.

-n module_name
    Specify the module name for a new extension. Creates a new module structure.

-o output_file
    Write .xs code to output_file instead of the default.

-p prefix
    Prefix all XS function names with prefix_.

-s
    Skip generating sub definitions for certain functions.

-v
    Enable verbose output during operation.

-x
    Generate code for handling C structures (structs).

DESCRIPTION

h2xs is a powerful utility included with Perl that significantly automates the creation of a Perl extension module. It can generate a module skeleton either from a specified C header file or by simply providing a module name.
The tool populates a new directory with all the necessary boilerplate files for a Perl XS module, including Makefile.PL (configured for ExtUtils::MakeMaker), a .pm file, an .xs file, basic test scripts, and documentation templates.
This automation dramatically simplifies the often-complex process of wrapping existing C libraries or writing new C code to be called directly from Perl, enabling Perl developers to leverage high-performance C routines and interface seamlessly with system APIs or legacy codebases.

CAVEATS

h2xs is a helpful starting point, but it does not parse C code perfectly; complex macros, pointers, and custom types often require significant manual adjustments to the generated .xs and .pm files.
It's designed primarily for C interfaces, and while it can handle extern "C", direct C++ class wrapping is beyond its scope. Always review and refine the generated code.

TYPICAL WORKFLOW

A common workflow involves running h2xs -n My::Module to create the module skeleton.
Then, manually edit My/Module.xs to add XS glue code, and My/Module.pm for Perl logic.
Finally, perl Makefile.PL, make, make test, and make install are used to build and install the module.

HISTORY

h2xs has been an integral part of the Perl distribution for a long time, evolving alongside the Perl XS mechanism and ExtUtils::MakeMaker.
Its core purpose has remained consistent: to facilitate the creation of Perl modules that interface with C code, simplifying the initial setup and reducing boilerplate for developers.
It is an essential tool for extending Perl's capabilities with high-performance C routines or leveraging existing C libraries.

SEE ALSO

perl(1), perlxstut(1), perlxs(1), ExtUtils::MakeMaker(3pm), ExtUtils::ParseXS(3pm), xsubpp(1)

Copied to clipboard