Module::Build::FFI(3) Build Perl extensions in C with FFI

VERSION

version 0.43

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

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.

METHODS

ffi_have_compiler

[version 0.18] 

 my $has_compiler = $mb->ffi_have_compiler;

Returns true if a C or C++ compiler is available.

Only checks for C++ if you appear to have C++ source.

Override for other foreign language subclasses.

ffi_build_dynamic_lib

[version 0.18] 

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

Compiles the C and C++ source in the $src_dir and link it into a dynamic library with base name of "$name.$Config{dlext}". If $target_dir is specified then the dynamic library will be delivered into that directory.

Override for other foreign language subclasses.

ffi_dlext

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

Returns a list of legal dynamic library extensions. $Config{dlext} is good, but many platforms use more than one extension for dynamic libraries. For example, on Mac OS X, there are two different dynamic library types ".bundle" and ".dylib" and sometimes these renamed ".so" files. Although ".bundle" and ".dylib" have subtle differences, they can both be used by FFI::Platypus.

AUTHOR

Author: Graham Ollis <[email protected]>

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.

LAST SEARCHED