NAME

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

VERSION

version 0.16

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::Declare qw( void );
 use FFI::Util qw( locate_module_share_lib );
 
 lib locate_module_share_lib();
 attach hello_world => [] => void;

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.

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::Declare;
 use FFI::CheckLib;
 
 lib find_lib lib => 'test', libpath => 'libtest';

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.

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

ffi

 ./Build ffi

This builds any C files that are bundled with your distribution (usually in the ffi directory). If there is no ffi directory, then this action does nothing.

This action is triggered automatically before ./Build build.

libtest

 ./Build libtest

This builds libtest. If you do not have a libtest directory, then this action does nothing.

This action is triggered automatically before ./Build test.

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.

AUTHOR

Graham Ollis <plicease@cpan.org>

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.

cpanm FFI::Platypus

perl -MCPAN -e shell
install FFI::Platypus