.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
.\"
.\" 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
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    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
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "FFI::Build 3pm"
.TH FFI::Build 3pm 2024-01-10 "perl v5.38.2" "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
FFI::Build \- Build shared libraries for use with FFI
.SH VERSION
.IX Header "VERSION"
version 2.08
.SH SYNOPSIS
.IX Header "SYNOPSIS"
.Vb 2
\& use FFI::Platypus 2.00;
\& use FFI::Build;
\& 
\& my $build = FFI::Build\->new(
\&   \*(Aqfrooble\*(Aq,
\&   source => \*(Aqffi/*.c\*(Aq,
\& );
\& 
\& # $lib is an instance of FFI::Build::File::Library
\& my $lib = $build\->build;
\& 
\& my $ffi = FFI::Platypus\->new( api => 2 );
\& # The filename will be platform dependant, but something like libfrooble.so or frooble.dll
\& $ffi\->lib($lib\->path);
\& 
\& ... # use $ffi to attach functions in ffi/*.c
.Ve
.SH DESCRIPTION
.IX Header "DESCRIPTION"
Using libffi based FFI::Platypus is a great alternative to XS for writing library bindings for Perl.
Sometimes, however, you need to bundle a little C code with your FFI module, but this has never been
that easy to use.  Module::Build::FFI was an early attempt to address this use case, but it uses
the now out of fashion Module::Build.
.PP
This module itself doesn't directly integrate with CPAN installers like ExtUtils::MakeMaker or
Module::Build, but there is a light weight layer FFI::Build::MM that will allow you to easily
use this module with ExtUtils::MakeMaker.  If you are using Dist::Zilla as your dist builder,
then there is also Dist::Zilla::Plugin::FFI::Build, which will help with the connections.
.PP
There is some functional overlap with ExtUtils::CBuilder, which was in fact used by Module::Build::FFI.
For this iteration I have decided not to use that module because although it will generate dynamic libraries
that can sometimes be used by FFI::Platypus, it is really designed for building XS modules, and trying
to coerce it into a more general solution has proved difficult in the past.
.PP
Supported languages out of the box are C, C++ and Fortran.  Rust is supported via a language plugin,
see FFI::Platypus::Lang::Rust.
.SH CONSTRUCTOR
.IX Header "CONSTRUCTOR"
.SS new
.IX Subsection "new"
.Vb 1
\& my $build = FFI::Build\->new($name, %options);
.Ve
.PP
Create an instance of this class.  The \f(CW$name\fR argument is used when computing the file name for
the library.  The actual name will be something like \f(CW\*(C`lib$name.so\*(C'\fR or \f(CW\*(C`$name.dll\*(C'\fR.  The following
options are supported:
.IP alien 4
.IX Item "alien"
List of Aliens to compile/link against.  FFI::Build will work with any Alien::Base based
alien, or modules that provide a compatible API.
.IP buildname 4
.IX Item "buildname"
Directory name that will be used for building intermediate files, such as object files.  This is
\&\f(CW\*(C`_build\*(C'\fR by default.
.IP cflags 4
.IX Item "cflags"
Extra compiler flags to use.  Things like \f(CW\*(C`\-I/foo/include\*(C'\fR or \f(CW\*(C`\-DFOO=1\*(C'\fR.
.IP dir 4
.IX Item "dir"
The directory where the library will be written.  This is \f(CW\*(C`.\*(C'\fR by default.
.IP export 4
.IX Item "export"
Functions that should be exported (Windows + Visual C++ only)
.IP file 4
.IX Item "file"
An instance of FFI::Build::File::Library to which the library will be written.  Normally not needed.
.IP libs 4
.IX Item "libs"
Extra library flags to use.  Things like \f(CW\*(C`\-L/foo/lib \-lfoo\*(C'\fR.
.IP platform 4
.IX Item "platform"
An instance of FFI::Build::Platform.  Usually you want to omit this and use the default instance.
.IP source 4
.IX Item "source"
List of source files.  You can use wildcards supported by \f(CW\*(C`bsd_glob\*(C'\fR from File::Glob.
.IP verbose 4
.IX Item "verbose"
By default this class does not print out the actual compiler and linker commands used in building
the library unless there is a failure.  You can alter this behavior with this option.  Set to
one of these values:
.RS 4
.IP "zero (0)" 4
.IX Item "zero (0)"
Default, quiet unless there is a failure.
.IP "one (1)" 4
.IX Item "one (1)"
Output the operation (compile, link, etc) and the file, but nothing else
.IP "two (2)" 4
.IX Item "two (2)"
Output the complete commands run verbatim.
.RE
.RS 4
.Sp
If the environment variable \f(CW\*(C`V\*(C'\fR is set to a true value then the verbosity will be set to \f(CW2\fR regardless
of what is passed in.
.RE
.SH METHODS
.IX Header "METHODS"
.SS dir
.IX Subsection "dir"
.Vb 1
\& my $dir = $build\->dir;
.Ve
.PP
Returns the directory where the library will be written.
.SS buildname
.IX Subsection "buildname"
.Vb 1
\& my $builddir = $build\->builddir;
.Ve
.PP
Returns the build name.  This is used in computing a directory to save intermediate files like objects.  For example,
if you specify a file like \f(CW\*(C`ffi/foo.c\*(C'\fR, then the object file will be stored in \f(CW\*(C`ffi/_build/foo.o\*(C'\fR by default.
\&\f(CW\*(C`_build\*(C'\fR in this example (the default) is the build name.
.SS export
.IX Subsection "export"
.Vb 1
\& my $exports = $build\->export;
.Ve
.PP
Returns a array reference of the exported functions (Windows + Visual C++ only)
.SS file
.IX Subsection "file"
.Vb 1
\& my $file = $build\->file;
.Ve
.PP
Returns an instance of FFI::Build::File::Library corresponding to the library being built.  This is
also returned by the \f(CW\*(C`build\*(C'\fR method below.
.SS platform
.IX Subsection "platform"
.Vb 1
\& my $platform = $build\->platform;
.Ve
.PP
An instance of FFI::Build::Platform, which contains information about the platform on which you are building.
The default is usually reasonable.
.SS verbose
.IX Subsection "verbose"
.Vb 1
\& my $verbose = $build\->verbose;
.Ve
.PP
Returns the verbose flag.
.SS cflags
.IX Subsection "cflags"
.Vb 1
\& my @cflags = @{ $build\->cflags };
.Ve
.PP
Returns the compiler flags.
.SS cflags_I
.IX Subsection "cflags_I"
.Vb 1
\& my @cflags_I = @{ $build\->cflags_I };
.Ve
.PP
Returns the \f(CW\*(C`\-I\*(C'\fR cflags.
.SS libs
.IX Subsection "libs"
.Vb 1
\& my @libs = @{ $build\->libs };
.Ve
.PP
Returns the library flags.
.SS libs_L
.IX Subsection "libs_L"
.Vb 1
\& my @libs = @{ $build\->libs };
.Ve
.PP
Returns the \f(CW\*(C`\-L\*(C'\fR library flags.
.SS alien
.IX Subsection "alien"
.Vb 1
\& my @aliens = @{ $build\->alien };
.Ve
.PP
Returns a the list of aliens being used.
.SS source
.IX Subsection "source"
.Vb 1
\& $build\->source(@files);
.Ve
.PP
Add the \f(CW@files\fR to the list of source files that will be used in building the library.
The format is the same as with the \f(CW\*(C`source\*(C'\fR attribute above.
.SS build
.IX Subsection "build"
.Vb 1
\& my $lib = $build\->build;
.Ve
.PP
This compiles the source files and links the library.  Files that have already been compiled or linked
may be reused without recompiling/linking if the timestamps are newer than the source files.  An instance
of FFI::Build::File::Library is returned which can be used to get the path to the library, which can
be feed into FFI::Platypus or similar.
.SS clean
.IX Subsection "clean"
.Vb 1
\& $build\->clean;
.Ve
.PP
Removes the library and intermediate files.
.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)
.PP
Shlomi Fish (shlomif)
.PP
Damyan Ivanov
.PP
Ilya Pavlov (Ilya33)
.PP
Petr Písař (ppisar)
.PP
Mohammad S Anwar (MANWAR)
.PP
Håkon Hægland (hakonhagland, HAKONH)
.PP
Meredith (merrilymeredith, MHOWARD)
.PP
Diab Jerius (DJERIUS)
.PP
Eric Brine (IKEGAMI)
.PP
szTheory
.PP
José Joaquín Atria (JJATRIA)
.PP
Pete Houston (openstrike, HOUSTON)
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
This software is copyright (c) 2015\-2022 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.