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 0.94
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;
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       WARNING: Alpha quality software, expect a somewhat unstable API until
31       it stabilizes.  Documentation may be missing or inaccurate.
32
33       Using libffi based FFI::Platypus is a great alternative to XS for
34       writing library bindings for Perl.  Sometimes, however, you need to
35       bundle a little C code with your FFI module, but this has never been
36       that easy to use.  Module::Build::FFI was an early attempt to address
37       this use case, but it uses the now out of fashion Module::Build.
38
39       This module itself doesn't directly integrate with CPAN installers like
40       ExtUtils::MakeMaker or Module::Build, but there is a light weight layer
41       FFI::Build::MM that will allow you to easily use this module with
42       ExtUtils::MakeMaker.  If you are using Dist::Zilla as your dist
43       builder, then there is also Dist::Zilla::Plugin::FFI::Build, which will
44       help with the connections.
45
46       There is some functional overlap with ExtUtils::CBuilder, which was in
47       fact used by Module::Build::FFI.  For this iteration I have decided not
48       to use that module because although it will generate dynamic libraries
49       that can sometimes be used by FFI::Platypus, it is really designed for
50       building XS modules, and trying to coerce it into a more general
51       solution has proved difficult in the past.
52
53       Supported languages out of the box are C, C++ and Fortran.  In the
54       future I plan on also supporting other languages like Rust, and maybe
55       Go, but the machinery for that will eventually live in
56       FFI::Build::Foreign.
57
58       The hope is that this module will be merged into FFI::Platypus, if and
59       when this module becomes appropriately stable.
60

CONSTRUCTOR

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

METHODS

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

AUTHOR

199       Author: Graham Ollis <plicease@cpan.org>
200
201       Contributors:
202
203       Bakkiaraj Murugesan (bakkiaraj)
204
205       Dylan Cali (calid)
206
207       pipcet
208
209       Zaki Mughal (zmughal)
210
211       Fitz Elliott (felliott)
212
213       Vickenty Fesunov (vyf)
214
215       Gregor Herrmann (gregoa)
216
217       Shlomi Fish (shlomif)
218
219       Damyan Ivanov
220
221       Ilya Pavlov (Ilya33)
222
223       Petr Pisar (ppisar)
224
225       Mohammad S Anwar (MANWAR)
226

228       This software is copyright (c) 2015,2016,2017,2018,2019 by Graham
229       Ollis.
230
231       This is free software; you can redistribute it and/or modify it under
232       the same terms as the Perl 5 programming language system itself.
233
234
235
236perl v5.30.0                      2019-07-26                     FFI::Build(3)
Impressum