/ 
XS-JIT-0.14
/ XS::JIT::Header

NAME

XS::JIT::Header - FFI-like interface for C headers using XS::JIT

SYNOPSIS

use XS::JIT::Header;

# Bind to math library (JIT compile at runtime)
my $math = XS::JIT::Header->new(
    header  => 'math.h',
    package => 'FastMath',
);

$math->attach('sin');
$math->attach('cos');
$math->attach('pow');
$math->compile;

# Now use the functions
my $result = FastMath::sin(3.14159);
my $power = FastMath::pow(2, 10);  # 1024

# Or generate static files for distribution (no JIT needed)
my $lib = XS::JIT::Header->new(
    header  => 'mylib.h',
    package => 'My::Lib',
);
$lib->attach_all();
$lib->write_module(dir => 'My-Lib');
# Creates My-Lib/lib/My/Lib.pm, Lib.xs, Lib_funcs.c

# Or just export the C code for embedding
$lib->write_c_file('mylib_wrappers.c');

DESCRIPTION

XS::JIT::Header provides an FFI::Platypus-like interface for binding C libraries through their header files, but uses XS::JIT's compilation approach for better runtime performance (~2x faster than FFI).

The module parses C header files to extract function declarations, generates XS wrapper code using XS::JIT::Builder, and compiles it using XS::JIT. The compiled code is cached for subsequent runs.

METHODS

new(%options)

Creates a new XS::JIT::Header instance.

my $h = XS::JIT::Header->new(
    header    => 'mylib.h',      # Required: path to C header
    lib       => 'mylib',        # Optional: library name or path
    include   => ['/opt/include'], # Optional: additional include paths
    define    => { DEBUG => 1 }, # Optional: preprocessor defines
    package   => 'MyLib',        # Optional: target Perl package (default: caller)
    prefix    => 'mylib_',       # Optional: prefix to strip from function names
    cache_dir => '_CACHED_XS',   # Optional: cache directory
    force     => 0,              # Optional: force recompilation
);

attach($c_name)

attach($c_name => $perl_name)

attach($c_name => \@arg_types => $return_type)

Attach a C function to be compiled as a Perl subroutine.

# Use same name (stripped of prefix)
$h->attach('mylib_calculate');  # becomes MyLib::calculate

# Use custom Perl name
$h->attach('mylib_calculate' => 'calc');  # becomes MyLib::calc

# Explicit type specification (overrides header parsing)
$h->attach('custom_func' => ['int', 'double'] => 'double');

attach_all()

attach_all($filter)

Attach all functions from the parsed header.

$h->attach_all;                  # All functions
$h->attach_all(qr/^math_/);      # Only functions matching regex
$h->attach_all(sub { length($_[0]) < 10 });  # Custom filter

compile()

Compile all attached functions. This is called automatically when the object goes out of scope, but can be called explicitly for better error handling.

$h->compile or die "Compilation failed";

write_module(%options)

Generate a complete distributable XS module without JIT compilation. This creates static C, XS, and PM files that can be compiled using a standard Makefile.PL build process.

$h->write_module(
    dir     => 'MyModule',    # Output directory (default: '.')
    package => 'My::Lib',     # Package name (default: from new())
);

This creates:

MyModule/
  lib/
    My/
      Lib.pm        # Perl module with XSLoader
      Lib.xs        # XS boot code
      Lib_funcs.c   # Generated function wrappers

Returns a hashref with the created file paths.

write_c_file($filename)

Write just the generated C code (function wrappers) to a file. Useful for embedding into existing XS modules.

$h->write_c_file('my_funcs.c');

functions()

Returns a list of function names parsed from the header.

my @funcs = $h->functions;

function($name)

Returns detailed information about a specific function.

my $info = $h->function('sin');
# { name => 'sin', return_type => 'double',
#   params => [{ type => 'double', name => 'x' }], ... }

constants()

Returns a list of constant names (from #define) parsed from the header.

my @consts = $h->constants;

constant($name)

Returns the value of a constant.

my $pi = $h->constant('M_PI');

TYPE MAPPING

The following C types are automatically mapped to Perl types:

C Type              Perl Type   Conversion
------------------  ----------  ----------
char, short, int    IV          SvIV/newSViv
long, long long
unsigned ...        UV          SvUV/newSVuv
size_t, uint*_t
float, double       NV          SvNV/newSVnv
char*, const char*  PV          SvPV/newSVpv
void                -           -
void*, T*           UV          PTR2UV/INT2PTR

Unknown types are treated as opaque pointers (UV).

LIMITATIONS

  • Struct arguments are not yet supported (treated as opaque pointers)

  • Variable argument functions (like printf) have limited support

  • Complex preprocessor macros may not parse correctly

SEE ALSO

XS::JIT, XS::JIT::Builder, FFI::Platypus

AUTHOR

LNATION <email@lnation.org>

LICENSE

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