NAME¶

Module::Build::FFI - Build Perl extensions in C with FFI

VERSION¶

version 0.45

SYNOPSIS¶

In your "Build.PL"

 use Modue::Build::FFI 0.04;
 Module::Build::FFI->new(
   module_name => 'Foo::Bar',
   ...
 )->create_build_script;

or "dist.ini":

 [ModuleBuild]
 mb_class = Module::Build::FFI
 
 [Prereqs / ConfigureRequires]
 Module::Build::FFI = 0.04

Put your .c and .h files in "ffi" ("ffi/example.c"):

 #include <ffi_util.h>
 #include <stdio.h>
 
 FFI_UTIL_EXPORT void
 print_hello(void)
 {
   printf("hello world\n");
 }

Attach it to Perl in your main module ("lib/Foo/Bar.pm"):

 package Foo::Bar;
 
 use FFI::Platypus;
 
 my $ffi = FFI::Platypus->new;
 $ffi->package;  # search for symbols in your bundled C code
 $ffi->attach( hello_world => [] => 'void');

Finally, use it from your perl script or module:

 use Foo::Bar;
 Foo::Bar::hello_world();  # prints "hello world\n"

DESCRIPTION¶

Module::Build variant for writing Perl extensions in C and FFI (sans XS).

PROPERTIES¶

ffi_source_dir

[version 0.15]

By default, C source files in the "ffi" directory are compiled and linked, if that directory exists. You can change that directory with this property.

[version 0.18]

This can be a scalar or a array reference.

ffi_libtest_dir

[version 0.15]

If the libtest directory ("libtest" by default) exists, then C source files will be compiled and linked into a test dynamic library that you can use to test your FFI module with. You can use FFI::CheckLib to find the library from your test:

 use Test::More;
 use FFI::Platypus;
 use FFI::CheckLib;
 
 FFI::Platypus->new->lib(find_lib lib => 'test', libpath => 'libtest');
    

[version 0.18]

This can be a scalar or a array reference.

ffi_include_dir

[version 0.15]

If there is an "include" directory with your distribution with C header files in it, it will be included in the search path for the C files in both the "ffi" and "libtest" directories.

[version 0.18]

This can be a scalar or a array reference.

ffi_libtest_optional

[version 0.15]

If there is no compiler then libtest cannot be built. By default this is not fatal. Your tests need to be written in such a way that any that use libtest are skipped when it is not there.

 use Test::More;
 use FFI::CheckLib;
 
 plan skip_all => 'test requires a compiler'
   unless find_lib lib => 'test', libpath => 'libtest';
    

If you do not want to support environments without a compiler you can set this property to 1 and you won't need to have that check in your test files.

ACTIONS¶

 ./Build ffi

 ./Build libtest

MACROS¶

Defined in "ffi_util.h"

FFI_UTIL_VERSION

[version 0.04]

This is the FFI::Platypus (prior to version 0.15 it was the FFI::Util version number) version number multiplied by 100 (so it would be 4 for 0.04 and 101 for 1.01).

FFI_UTIL_EXPORT

[version 0.04]

The appropriate attribute needed to export functions from shared libraries / DLLs. For now this is only necessary on Windows when using Microsoft Visual C++, but it may be necessary elsewhere in the future.

METHODS¶

 my $has_compiler = $mb->ffi_have_compiler;

 my $dll_path = $mb->ffi_build_dynamic_lib($src_dir, $name, $target_dir);
 my $dll_path = $mb->ffi_build_dynamic_lib($src_dir, $name);

 my @dlext = Module::Build::FFI->ffi_dlext;

AUTHOR¶

Author: Graham Ollis <plicease@cpan.org>

Contributors:

Bakkiaraj Murugesan (bakkiaraj)

Dylan Cali (calid)

pipcet

Zaki Mughal (zmughal)

Fitz Elliott (felliott)

Vickenty Fesunov (vyf)

Gregor Herrmann (gregoa)

COPYRIGHT AND LICENSE¶

This software is copyright (c) 2015 by Graham Ollis.

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