NAME

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

VERSION

       version 2.00

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

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

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)

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.