Scroll to navigation

FFI::Build(3pm) User Contributed Perl Documentation FFI::Build(3pm)


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


version 0.98


 use FFI::Platypus;
 use FFI::Build;
 my $build = FFI::Build->new(
   source => 'ffi/*.c',
 # $lib is an instance of FFI::Build::File::Library
 my $lib = $build->build;
 my $ffi = FFI::Platypus->new;
 # The filename will be platform dependant, but something like or frooble.dll
 ... # use $ffi to attach functions in ffi/*.c


WARNING: Alpha quality software, expect a somewhat unstable API until it stabilizes. Documentation may be missing or inaccurate.

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.

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.

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.

Supported languages out of the box are C, C++ and Fortran. In the future I plan on also supporting other languages like Rust, and maybe Go, but the machinery for that will eventually live in FFI::Build::Foreign.

The hope is that this module will be merged into FFI::Platypus, if and when this module becomes appropriately stable.



 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 like "lib$" or "$name.dll". The following options are supported:

List of Aliens to compile/link against. FFI::Build will work with any Alien::Base based alien, or modules that provide a compatible API.
Directory name that will be used for building intermediate files, such as object files. This is "_build" by default.
Extra compiler flags to use. Things like "-I/foo/include" or "-DFOO=1".
The directory where the library will be written. This is "." by default.
An instance of FFI::Build::File::Library to which the library will be written. Normally not needed.
Extra library flags to use. Things like "-L/foo/lib -lfoo".
An instance of FFI::Build::Platform. Usually you want to omit this and use the default instance.
List of source files. You can use wildcards supported by "bsd_glob" from File::Glob.
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.



 my $dir = $build->dir;

Returns the directory where the library will be written.


 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 like "ffi/foo.c", then the object file will be stored in "ffi/_build/foo.o" by default. "_build" in this example (the default) is the build name.


 my $file = $build->file;

Returns an instance of FFI::Build::File::Library corresponding to the library being built. This is also returned by the "build" method below.


 my $platform = $build->platform;

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


 my $verbose = $build->verbose;

Returns the verbose flag.


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

Returns the compiler flags.


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

Returns the "-I" cflags.


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

Returns the library flags.


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

Returns the "-L" library flags.


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

Returns a the list of aliens being used.



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


 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 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.



Removes the library and intermediate files.


Author: Graham Ollis <>


Bakkiaraj Murugesan (bakkiaraj)

Dylan Cali (calid)


Zaki Mughal (zmughal)

Fitz Elliott (felliott)

Vickenty Fesunov (vyf)

Gregor Herrmann (gregoa)

Shlomi Fish (shlomif)

Damyan Ivanov

Ilya Pavlov (Ilya33)

Petr Pisar (ppisar)

Mohammad S Anwar (MANWAR)

Håkon Hægland (hakonhagland, HAKONH)

Meredith (merrilymeredith, MHOWARD)


This software is copyright (c) 2015,2016,2017,2018,2019 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.

2019-10-15 perl v5.30.0