<!-- GENERATED by docs/sphinx/bin/20-reference (p5) from reference/bundled/FFI/Build.md. Do not edit. -->

```{index} single: FFI::Build
```

# FFI::Build

Build shared libraries for use with FFI

## VERSION

version 2.12

## SYNOPSIS

```perl
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

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](https://metacpan.org/pod/Module::Build::FFI) was an early attempt to address this use case, but it uses the now out of fashion [Module::Build](https://metacpan.org/pod/Module::Build).

This module itself doesn't directly integrate with CPAN installers like [ExtUtils::MakeMaker](../ExtUtils/MakeMaker.md) or
[Module::Build](https://metacpan.org/pod/Module::Build), but there is a light weight layer [FFI::Build::MM](Build/MM.md) that will allow you to easily
use this module with [ExtUtils::MakeMaker](../ExtUtils/MakeMaker.md).  If you are using [Dist::Zilla](https://metacpan.org/pod/Dist::Zilla) as your dist builder,
then there is also [Dist::Zilla::Plugin::FFI::Build](https://metacpan.org/pod/Dist::Zilla::Plugin::FFI::Build), which will help with the connections.

There is some functional overlap with [ExtUtils::CBuilder](../ExtUtils/CBuilder.md), which was in fact used by [Module::Build::FFI](https://metacpan.org/pod/Module::Build::FFI).

Supported languages out of the box are C, C++ and Fortran.  Rust is supported via a language plugin,
see [FFI::Platypus::Lang::Rust](https://metacpan.org/pod/FFI::Platypus::Lang::Rust).

## CONSTRUCTOR

### new

```perl
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](Build.md) will work with any [Alien::Base](https://metacpan.org/pod/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](Build/File/Library.md) 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](Build/Platform.md).  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](../File/Glob.md).

- 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

```perl
my $dir = $build->dir;
```

Returns the directory where the library will be written.

### buildname

```perl
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

```perl
my $exports = $build->export;
```

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

### file

```perl
my $file = $build->file;
```

Returns an instance of [FFI::Build::File::Library](Build/File/Library.md) corresponding to the library being built.  This is
also returned by the `build` method below.

### platform

```perl
my $platform = $build->platform;
```

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

### verbose

```perl
my $verbose = $build->verbose;
```

Returns the verbose flag.

### cflags

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

Returns the compiler flags.

### cflags\_I

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

Returns the `-I` cflags.

### libs

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

Returns the library flags.

### libs\_L

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

Returns the `-L` library flags.

### alien

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

Returns a the list of aliens being used.

### source

```perl
$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

```perl
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](Build/File/Library.md) is returned which can be used to get the path to the library, which can
be feed into [FFI::Platypus](Platypus.md) or similar.

### clean

```perl
$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.

## Modules

- [`FFI::Build::File`](Build/File.md)
- [`FFI::Build::MM`](Build/MM.md) - FFI::Build installer code for ExtUtils::MakeMaker
- [`FFI::Build::Platform`](Build/Platform.md) - Platform specific configuration.
- [`FFI::Build::Plugin`](Build/Plugin.md) - Platform and local customizations of FFI::Build
- [`FFI::Build::PluginData`](Build/PluginData.md) - Platform and local customizations of FFI::Build

```{toctree}
:hidden:
:maxdepth: 1

Build/File
Build/MM
Build/Platform
Build/Plugin
Build/PluginData
```