Install Now
FFI::Build - Build shared libraries for use with FFI
Contents
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.
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.
perl v5.40.0 2025-01-11 FFI::Build(3pm)
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 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. Rust is supported via a language plugin, see
FFI::Platypus::Lang::Rust.
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 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 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.
Name
FFI::Build - Build shared libraries for use with FFI
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
Version
version 2.10
PNG Icons
Emojis