1FFI::Build(3) User Contributed Perl Documentation FFI::Build(3)
2
3
4
6 FFI::Build - Build shared libraries for use with FFI
7
9 version 2.05
10
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
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
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
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
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.36.0 2022-11-18 FFI::Build(3)