1FFI::Build(3)         User Contributed Perl Documentation        FFI::Build(3)
2
3
4

NAME

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

VERSION

9       version 1.32
10

SYNOPSIS

12        use FFI::Platypus;
13        use FFI::Build;
14
15        my $build = FFI::Build->new(
16          'frooble',
17          source => 'ffi/*.c',
18        );
19
20        # $lib is an instance of FFI::Build::File::Library
21        my $lib = $build->build;
22
23        my $ffi = FFI::Platypus->new( api => 1 );
24        # The filename will be platform dependant, but something like libfrooble.so or frooble.dll
25        $ffi->lib($lib->path);
26
27        ... # use $ffi to attach functions in ffi/*.c
28

DESCRIPTION

30       Using libffi based FFI::Platypus is a great alternative to XS for
31       writing library bindings for Perl.  Sometimes, however, you need to
32       bundle a little C code with your FFI module, but this has never been
33       that easy to use.  Module::Build::FFI was an early attempt to address
34       this use case, but it uses the now out of fashion Module::Build.
35
36       This module itself doesn't directly integrate with CPAN installers like
37       ExtUtils::MakeMaker or Module::Build, but there is a light weight layer
38       FFI::Build::MM that will allow you to easily use this module with
39       ExtUtils::MakeMaker.  If you are using Dist::Zilla as your dist
40       builder, then there is also Dist::Zilla::Plugin::FFI::Build, which will
41       help with the connections.
42
43       There is some functional overlap with ExtUtils::CBuilder, which was in
44       fact used by Module::Build::FFI.  For this iteration I have decided not
45       to use that module because although it will generate dynamic libraries
46       that can sometimes be used by FFI::Platypus, it is really designed for
47       building XS modules, and trying to coerce it into a more general
48       solution has proved difficult in the past.
49
50       Supported languages out of the box are C, C++ and Fortran.  Rust is
51       supported via a language plugin, see FFI::Platypus::Lang::Rust.
52

CONSTRUCTOR

54   new
55        my $build = FFI::Build->new($name, %options);
56
57       Create an instance of this class.  The $name argument is used when
58       computing the file name for the library.  The actual name will be
59       something like "lib$name.so" or "$name.dll".  The following options are
60       supported:
61
62       alien
63           List of Aliens to compile/link against.  FFI::Build will work with
64           any Alien::Base based alien, or modules that provide a compatible
65           API.
66
67       buildname
68           Directory name that will be used for building intermediate files,
69           such as object files.  This is "_build" by default.
70
71       cflags
72           Extra compiler flags to use.  Things like "-I/foo/include" or
73           "-DFOO=1".
74
75       dir The directory where the library will be written.  This is "." by
76           default.
77
78       export
79           Functions that should be exported (Windows + Visual C++ only)
80
81       file
82           An instance of FFI::Build::File::Library to which the library will
83           be written.  Normally not needed.
84
85       libs
86           Extra library flags to use.  Things like "-L/foo/lib -lfoo".
87
88       platform
89           An instance of FFI::Build::Platform.  Usually you want to omit this
90           and use the default instance.
91
92       source
93           List of source files.  You can use wildcards supported by
94           "bsd_glob" from File::Glob.
95
96       verbose
97           By default this class does not print out the actual compiler and
98           linker commands used in building the library unless there is a
99           failure.  You can alter this behavior with this option.  Set to one
100           of these values:
101
102           zero (0)
103               Default, quiet unless there is a failure.
104
105           one (1)
106               Output the operation (compile, link, etc) and the file, but
107               nothing else
108
109           two (2)
110               Output the complete commands run verbatim.
111

METHODS

113   dir
114        my $dir = $build->dir;
115
116       Returns the directory where the library will be written.
117
118   buildname
119        my $builddir = $build->builddir;
120
121       Returns the build name.  This is used in computing a directory to save
122       intermediate files like objects.  For example, if you specify a file
123       like "ffi/foo.c", then the object file will be stored in
124       "ffi/_build/foo.o" by default.  "_build" in this example (the default)
125       is the build name.
126
127   export
128        my $exports = $build->export;
129
130       Returns a array reference of the exported functions (Windows + Visual
131       C++ only)
132
133   file
134        my $file = $build->file;
135
136       Returns an instance of FFI::Build::File::Library corresponding to the
137       library being built.  This is also returned by the "build" method
138       below.
139
140   platform
141        my $platform = $build->platform;
142
143       An instance of FFI::Build::Platform, which contains information about
144       the platform on which you are building.  The default is usually
145       reasonable.
146
147   verbose
148        my $verbose = $build->verbose;
149
150       Returns the verbose flag.
151
152   cflags
153        my @cflags = @{ $build->cflags };
154
155       Returns the compiler flags.
156
157   cflags_I
158        my @cflags_I = @{ $build->cflags_I };
159
160       Returns the "-I" cflags.
161
162   libs
163        my @libs = @{ $build->libs };
164
165       Returns the library flags.
166
167   libs_L
168        my @libs = @{ $build->libs };
169
170       Returns the "-L" library flags.
171
172   alien
173        my @aliens = @{ $build->alien };
174
175       Returns a the list of aliens being used.
176
177   source
178        $build->source(@files);
179
180       Add the @files to the list of source files that will be used in
181       building the library.  The format is the same as with the "source"
182       attribute above.
183
184   build
185        my $lib = $build->build;
186
187       This compiles the source files and links the library.  Files that have
188       already been compiled or linked may be reused without
189       recompiling/linking if the timestamps are newer than the source files.
190       An instance of FFI::Build::File::Library is returned which can be used
191       to get the path to the library, which can be feed into FFI::Platypus or
192       similar.
193
194   clean
195        $build->clean;
196
197       Removes the library and intermediate files.
198

AUTHOR

200       Author: Graham Ollis <plicease@cpan.org>
201
202       Contributors:
203
204       Bakkiaraj Murugesan (bakkiaraj)
205
206       Dylan Cali (calid)
207
208       pipcet
209
210       Zaki Mughal (zmughal)
211
212       Fitz Elliott (felliott)
213
214       Vickenty Fesunov (vyf)
215
216       Gregor Herrmann (gregoa)
217
218       Shlomi Fish (shlomif)
219
220       Damyan Ivanov
221
222       Ilya Pavlov (Ilya33)
223
224       Petr Pisar (ppisar)
225
226       Mohammad S Anwar (MANWAR)
227
228       Håkon Hægland (hakonhagland, HAKONH)
229
230       Meredith (merrilymeredith, MHOWARD)
231
232       Diab Jerius (DJERIUS)
233

235       This software is copyright (c) 2015,2016,2017,2018,2019,2020 by Graham
236       Ollis.
237
238       This is free software; you can redistribute it and/or modify it under
239       the same terms as the Perl 5 programming language system itself.
240
241
242
243perl v5.32.0                      2020-09-21                     FFI::Build(3)
Impressum