h2xs
Convert C header files into Perl extensions
SYNOPSIS
h2xs [options] ModuleName
PARAMETERS
-A
Create a skeleton without prompting questions.
-n ModuleName
Specify the module name. The ModuleName will be created as directory
-v
Verbose mode.
-X
Create the structure for an extension module.
-C
Create a skeleton for a class.
-m
Create a simple module (no XS).
-p
Create a package.
-f file.h
Specify a C header file to parse.
-h
Display help and exit.
-q
Quiet mode (suppress warnings).
DESCRIPTION
h2xs is a Perl utility that helps in creating Perl extensions from C header files. It generates a skeleton directory structure and basic code for wrapping C functions and data structures defined in a header file so that they can be accessed from Perl. This significantly reduces the initial effort required to interface Perl with existing C libraries. It handles tasks like creating Makefiles, module documentation (pod), and boilerplate code for data type conversions. Essentially, it streamlines the process of creating a Perl XS module from a C header file, providing a starting point that you can then customize with your own logic for interacting with the C library.
After running h2xs, you would then need to adapt the generated code to correctly handle memory management, error checking, and data type conversions specifics to your application.
CAVEATS
h2xs provides a starting point, but manual adjustments are crucial for proper type conversions, memory management, and error handling. It doesn't automatically create a complete, working extension. You *must* understand both Perl and C to effectively use h2xs.
<B>GENERATED FILES</B>
h2xs generates several files, including a Makefile.PL (or Build.PL), a .pm file for the Perl module, and a .xs file for the XS code. The Makefile.PL/Build.PL is used to build and install the module, the .pm file defines the Perl interface, and the .xs file contains the C code that implements the module's functions.
<B>LIMITATIONS</B>
h2xs may not be able to handle all C header file constructs perfectly. Complex macros, preprocessor directives, and data types might require manual intervention and adjustments to the generated code. It is really important to check the generated code and adapt it to real needs.
HISTORY
h2xs has been a core utility in Perl distributions for many years. Its original purpose was to simplify the complex task of writing XS modules. Over time, it has been improved to handle more complex header file structures and to generate better skeleton code. It remains a valuable tool for Perl developers who need to interface with C libraries, although the generated code often requires substantial modification.