FFI::Build(3pm)

okay bestie, welcome to the FFI::Build(3pm) manual page from the User Contributed Perl Documentation — this is the one about building shared libraries for use with FFI, and it's genuinely useful, no cap 💅

💖 NAME 💖

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

🌈 VERSION 🌈

version 2.11

✨ 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::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

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

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 the author 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. Rust is supported via a language plugin, see FFI::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 like lib$name.so or $name.dll. The following options are supported:

• 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.
• 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 of FFI::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 of FFI::Build::Platform. Usually you want to omit this and use the default instance.
• source — List of source files. You can use wildcards supported by bsd_glob from File::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 variable V is set to a true value then the verbosity will be set to 2 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 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.

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 of FFI::Build::File::Library corresponding to the library being built. This is also returned by the build method below.

platform

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.

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

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.

mwah 💋 — this page came from perl v5.42.3, dated 2026-08-20, and that's the whole vibe, bestie 🫶