.\" Automatically generated by Pod::Man 4.09 (Pod::Simple 3.35)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.if !\nF .nr F 0
.if \nF>0 \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    if !\nF==2 \{\
.        nr % 0
.        nr F 2
.    \}
.\}
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Module::Build::FFI 3pm"
.TH Module::Build::FFI 3pm "2017-07-21" "perl v5.26.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Module::Build::FFI \- Build Perl extensions in C with FFI
.SH "VERSION"
.IX Header "VERSION"
version 0.45
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
In your \f(CW\*(C`Build.PL\*(C'\fR
.PP
.Vb 5
\& use Modue::Build::FFI 0.04;
\& Module::Build::FFI\->new(
\&   module_name => \*(AqFoo::Bar\*(Aq,
\&   ...
\& )\->create_build_script;
.Ve
.PP
or \f(CW\*(C`dist.ini\*(C'\fR:
.PP
.Vb 2
\& [ModuleBuild]
\& mb_class = Module::Build::FFI
\& 
\& [Prereqs / ConfigureRequires]
\& Module::Build::FFI = 0.04
.Ve
.PP
Put your .c and .h files in \f(CW\*(C`ffi\*(C'\fR (\f(CW\*(C`ffi/example.c\*(C'\fR):
.PP
.Vb 2
\& #include <ffi_util.h>
\& #include <stdio.h>
\& 
\& FFI_UTIL_EXPORT void
\& print_hello(void)
\& {
\&   printf("hello world\en");
\& }
.Ve
.PP
Attach it to Perl in your main module (\f(CW\*(C`lib/Foo/Bar.pm\*(C'\fR):
.PP
.Vb 1
\& 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 => [] => \*(Aqvoid\*(Aq);
.Ve
.PP
Finally, use it from your perl script or module:
.PP
.Vb 2
\& use Foo::Bar;
\& Foo::Bar::hello_world();  # prints "hello world\en"
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Module::Build variant for writing Perl extensions in C and \s-1FFI\s0 (sans \s-1XS\s0).
.SH "PROPERTIES"
.IX Header "PROPERTIES"
.IP "ffi_source_dir" 4
.IX Item "ffi_source_dir"
[version 0.15]
.Sp
By default, C source files in the \f(CW\*(C`ffi\*(C'\fR directory are compiled and
linked, if that directory exists.  You can change that directory
with this property.
.Sp
[version 0.18]
.Sp
This can be a scalar or a array reference.
.IP "ffi_libtest_dir" 4
.IX Item "ffi_libtest_dir"
[version 0.15]
.Sp
If the libtest directory (\f(CW\*(C`libtest\*(C'\fR by default) exists, then C source
files will be compiled and linked into a test dynamic library that you
can use to test your \s-1FFI\s0 module with.  You can use FFI::CheckLib to
find the library from your test:
.Sp
.Vb 3
\& use Test::More;
\& use FFI::Platypus;
\& use FFI::CheckLib;
\& 
\& FFI::Platypus\->new\->lib(find_lib lib => \*(Aqtest\*(Aq, libpath => \*(Aqlibtest\*(Aq);
.Ve
.Sp
[version 0.18]
.Sp
This can be a scalar or a array reference.
.IP "ffi_include_dir" 4
.IX Item "ffi_include_dir"
[version 0.15]
.Sp
If there is an \f(CW\*(C`include\*(C'\fR 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 \f(CW\*(C`ffi\*(C'\fR and \f(CW\*(C`libtest\*(C'\fR directories.
.Sp
[version 0.18]
.Sp
This can be a scalar or a array reference.
.IP "ffi_libtest_optional" 4
.IX Item "ffi_libtest_optional"
[version 0.15]
.Sp
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.
.Sp
.Vb 2
\& use Test::More;
\& use FFI::CheckLib;
\& 
\& plan skip_all => \*(Aqtest requires a compiler\*(Aq
\&   unless find_lib lib => \*(Aqtest\*(Aq, libpath => \*(Aqlibtest\*(Aq;
.Ve
.Sp
If you do not want to support environments without a compiler you can set
this property to \f(CW1\fR and you won't need to have that check in your test
files.
.SH "ACTIONS"
.IX Header "ACTIONS"
.SS "ffi"
.IX Subsection "ffi"
.Vb 1
\& ./Build ffi
.Ve
.PP
This builds any C files that are bundled with your distribution (usually
in the \f(CW\*(C`ffi\*(C'\fR directory).  If there is no \f(CW\*(C`ffi\*(C'\fR directory, then this
action does nothing.
.PP
This action is triggered automatically before \f(CW\*(C`./Build build\*(C'\fR.
.SS "libtest"
.IX Subsection "libtest"
.Vb 1
\& ./Build libtest
.Ve
.PP
This builds libtest.  If you do not have a libtest directory, then
this action does nothing.
.PP
This action is triggered automatically before \f(CW\*(C`./Build test\*(C'\fR.
.SH "MACROS"
.IX Header "MACROS"
Defined in \f(CW\*(C`ffi_util.h\*(C'\fR
.IP "\s-1FFI_UTIL_VERSION\s0" 4
.IX Item "FFI_UTIL_VERSION"
[version 0.04]
.Sp
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).
.IP "\s-1FFI_UTIL_EXPORT\s0" 4
.IX Item "FFI_UTIL_EXPORT"
[version 0.04]
.Sp
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.
.SH "METHODS"
.IX Header "METHODS"
.SS "ffi_have_compiler"
.IX Subsection "ffi_have_compiler"
[version 0.18]
.PP
.Vb 1
\& my $has_compiler = $mb\->ffi_have_compiler;
.Ve
.PP
Returns true if a C or \*(C+ compiler is available.
.PP
Only checks for \*(C+ if you appear to have \*(C+ source.
.PP
Override for other foreign language subclasses.
.SS "ffi_build_dynamic_lib"
.IX Subsection "ffi_build_dynamic_lib"
[version 0.18]
.PP
.Vb 2
\& my $dll_path = $mb\->ffi_build_dynamic_lib($src_dir, $name, $target_dir);
\& my $dll_path = $mb\->ffi_build_dynamic_lib($src_dir, $name);
.Ve
.PP
Compiles the C and \*(C+ source in the \f(CW$src_dir\fR and link it into a
dynamic library with base name of \f(CW\*(C`$name.$Config{dlext}\*(C'\fR.  If
\&\f(CW$target_dir\fR is specified then the dynamic library will be delivered
into that directory.
.PP
Override for other foreign language subclasses.
.SS "ffi_dlext"
.IX Subsection "ffi_dlext"
.Vb 1
\& my @dlext = Module::Build::FFI\->ffi_dlext;
.Ve
.PP
Returns a list of legal dynamic library extensions.  \f(CW$Config{dlext}\fR is good,
but many platforms use more than one extension for dynamic libraries.  For
example, on Mac \s-1OS X,\s0 there are two different dynamic library types \f(CW\*(C`.bundle\*(C'\fR
and \f(CW\*(C`.dylib\*(C'\fR and sometimes these renamed \f(CW\*(C`.so\*(C'\fR files.  Although \f(CW\*(C`.bundle\*(C'\fR
and \f(CW\*(C`.dylib\*(C'\fR have subtle differences, they can both be used by FFI::Platypus.
.SH "AUTHOR"
.IX Header "AUTHOR"
Author: Graham Ollis <plicease@cpan.org>
.PP
Contributors:
.PP
Bakkiaraj Murugesan (bakkiaraj)
.PP
Dylan Cali (calid)
.PP
pipcet
.PP
Zaki Mughal (zmughal)
.PP
Fitz Elliott (felliott)
.PP
Vickenty Fesunov (vyf)
.PP
Gregor Herrmann (gregoa)
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
This software is copyright (c) 2015 by Graham Ollis.
.PP
This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.