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 2.08
10

SYNOPSIS

12        use FFI::Platypus 2.00;
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 => 2 );
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
112           If the environment variable "V" is set to a true value then the
113           verbosity will be set to 2 regardless of what is passed in.
114

METHODS

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

AUTHOR

203       Author: Graham Ollis <plicease@cpan.org>
204
205       Contributors:
206
207       Bakkiaraj Murugesan (bakkiaraj)
208
209       Dylan Cali (calid)
210
211       pipcet
212
213       Zaki Mughal (zmughal)
214
215       Fitz Elliott (felliott)
216
217       Vickenty Fesunov (vyf)
218
219       Gregor Herrmann (gregoa)
220
221       Shlomi Fish (shlomif)
222
223       Damyan Ivanov
224
225       Ilya Pavlov (Ilya33)
226
227       Petr Písař (ppisar)
228
229       Mohammad S Anwar (MANWAR)
230
231       Håkon Hægland (hakonhagland, HAKONH)
232
233       Meredith (merrilymeredith, MHOWARD)
234
235       Diab Jerius (DJERIUS)
236
237       Eric Brine (IKEGAMI)
238
239       szTheory
240
241       José Joaquín Atria (JJATRIA)
242
243       Pete Houston (openstrike, HOUSTON)
244

246       This software is copyright (c) 2015-2022 by Graham Ollis.
247
248       This is free software; you can redistribute it and/or modify it under
249       the same terms as the Perl 5 programming language system itself.
250
251
252
253perl v5.38.0                      2023-07-20                     FFI::Build(3)
Impressum