NAME

FFI::Build - Build shared libraries for use with FFI

VERSION

version 2.10

SYNOPSIS

use FFI::Platypus 2.00;use FFI::Build;my $build = FFI::Build->new(  'frooble',  source => 'ffi/*.c',);# $lib is an instance of FFI::Build::File::Librarymy $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

DESCRIPTION

Using libffi basedFFI::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 fashionModule::Build.

This module itself doesn't directly integrate with CPAN installers likeExtUtils::MakeMaker orModule::Build, but there is a light weight layerFFI::Build::MM that will allow you to easily use this module withExtUtils::MakeMaker. If you are usingDist::Zilla as your dist builder, then there is alsoDist::Zilla::Plugin::FFI::Build, which will help with the connections.

There is some functional overlap withExtUtils::CBuilder, which was in fact used byModule::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 byFFI::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.

Supported languages out of the box are C, C++ and Fortran. Rust is supported via a language plugin, seeFFI::Platypus::Lang::Rust.

CONSTRUCTOR

new

my $build = FFI::Build->new($name, %options);

Create an instance of this class. The$name argument is used when computing the file name for the library. The actual name will be something likelib$name.so or$name.dll. The following options are supported:

alien

List of Aliens to compile/link against.FFI::Build will work with anyAlien::Base based alien, or modules that provide a compatible API.

buildname

Directory name that will be used for building intermediate files, such as object files. This is_build by default.

cflags

Extra compiler flags to use. Things like-I/foo/include or-DFOO=1.

dir

The directory where the library will be written. This is. by default.

export

Functions that should be exported (Windows + Visual C++ only)

file

An instance ofFFI::Build::File::Library to which the library will be written. Normally not needed.

libs

Extra library flags to use. Things like-L/foo/lib -lfoo.

platform

An instance ofFFI::Build::Platform. Usually you want to omit this and use the default instance.

source

List of source files. You can use wildcards supported bybsd_glob fromFile::Glob.

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:

zero (0)

Default, quiet unless there is a failure.

one (1)

Output the operation (compile, link, etc) and the file, but nothing else

two (2)

Output the complete commands run verbatim.

If the environment variableV is set to a true value then the verbosity will be set to2 regardless of what is passed in.

METHODS

dir

my $dir = $build->dir;

Returns the directory where the library will be written.

buildname

my $builddir = $build->builddir;

Returns the build name. This is used in computing a directory to save intermediate files like objects. For example, if you specify a file likeffi/foo.c, then the object file will be stored inffi/_build/foo.o by default._build in this example (the default) is the build name.

export

my $exports = $build->export;

Returns a array reference of the exported functions (Windows + Visual C++ only)

file

my $file = $build->file;

Returns an instance ofFFI::Build::File::Library corresponding to the library being built. This is also returned by thebuild method below.

platform

my $platform = $build->platform;

An instance ofFFI::Build::Platform, which contains information about the platform on which you are building. The default is usually reasonable.

verbose

my $verbose = $build->verbose;

Returns the verbose flag.

cflags

my @cflags = @{ $build->cflags };

Returns the compiler flags.

cflags_I

my @cflags_I = @{ $build->cflags_I };

Returns the-I cflags.

libs

my @libs = @{ $build->libs };

Returns the library flags.

libs_L

my @libs = @{ $build->libs };

Returns the-L library flags.

alien

my @aliens = @{ $build->alien };

Returns a the list of aliens being used.

source

$build->source(@files);

Add the@files to the list of source files that will be used in building the library. The format is the same as with thesource attribute above.

build

my $lib = $build->build;

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 ofFFI::Build::File::Library is returned which can be used to get the path to the library, which can be feed intoFFI::Platypus or similar.

clean

$build->clean;

Removes the library and intermediate files.

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)

Shlomi Fish (shlomif)

Damyan Ivanov

Ilya Pavlov (Ilya33)

Petr Písař (ppisar)

Mohammad S Anwar (MANWAR)

Håkon Hægland (hakonhagland, HAKONH)

Meredith (merrilymeredith, MHOWARD)

Diab Jerius (DJERIUS)

Eric Brine (IKEGAMI)

szTheory

José Joaquín Atria (JJATRIA)

Pete Houston (openstrike, HOUSTON)

Lukas Mai (MAUKE)

COPYRIGHT AND LICENSE

This software is copyright (c) 2015-2022 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.