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

NAME

6       FFI::Platypus - Write Perl bindings to non-Perl libraries with FFI. No
7       XS required.
8

VERSION

10       version 0.94
11

SYNOPSIS

13        use FFI::Platypus;
14
15        my $ffi = FFI::Platypus->new;
16        $ffi->lib(undef); # search libc
17
18        # call dynamically
19        $ffi->function( puts => ['string'] => 'int' )->call("hello world");
20
21        # attach as a xsub and call (much faster)
22        $ffi->attach( puts => ['string'] => 'int' );
23        puts("hello world");
24

DESCRIPTION

26       Platypus is a library for creating interfaces to machine code libraries
27       written in languages like C, C++, Fortran, Rust, Pascal. Essentially
28       anything that gets compiled into machine code.  This implementation
29       uses "libffi" to accomplish this task.  "libffi" is battle tested by a
30       number of other scripting and virtual machine languages, such as Python
31       and Ruby to serve a similar role.  There are a number of reasons why
32       you might want to write an extension with Platypus instead of XS:
33
34       FFI / Platypus does not require messing with the guts of Perl
35           XS is less of an API and more of the guts of perl splayed out to do
36           whatever you want.  That may at times be very powerful, but it can
37           also be a frustrating exercise in hair pulling.
38
39       FFI / Platypus is portable
40           Lots of languages have FFI interfaces, and it is subjectively
41           easier to port an extension written in FFI in Perl or another
42           language to FFI in another language or Perl.  One goal of the
43           Platypus Project is to reduce common interface specifications to a
44           common format like JSON that could be shared between different
45           languages.
46
47       FFI / Platypus could be a bridge to Perl 6
48           One of those "other" languages could be Perl 6 and Perl 6 already
49           has an FFI interface I am told.
50
51       FFI / Platypus can be reimplemented
52           In a bright future with multiple implementations of Perl 5, each
53           interpreter will have its own implementation of Platypus, allowing
54           extensions to be written once and used on multiple platforms, in
55           much the same way that Ruby-FFI extensions can be use in Ruby,
56           JRuby and Rubinius.
57
58       FFI / Platypus is pure perl (sorta)
59           One Platypus script or module works on any platform where the
60           libraries it uses are available.  That means you can deploy your
61           Platypus script in a shared filesystem where they may be run on
62           different platforms.  It also means that Platypus modules do not
63           need to be installed in the platform specific Perl library path.
64
65       FFI / Platypus is not C or C++ centric
66           XS is implemented primarily as a bunch of C macros, which requires
67           at least some understanding of C, the C pre-processor, and some C++
68           caveats (since on some platforms Perl is compiled and linked with a
69           C++ compiler). Platypus on the other hand could be used to call
70           other compiled languages, like Fortran, Rust, Pascal, C++, or even
71           assembly, allowing you to focus on your strengths.
72
73       FFI / Platypus does not require a parser
74           Inline isolates the extension developer from XS to some extent, but
75           it also requires a parser.  The various Inline language bindings
76           are a great technical achievement, but I think writing a parser for
77           every language that you want to interface with is a bit of an anti-
78           pattern.
79
80       This document consists of an API reference, a set of examples, some
81       support and development (for contributors) information.  If you are new
82       to Platypus or FFI, you may want to skip down to the EXAMPLES to get a
83       taste of what you can do with Platypus.
84
85       Platypus has extensive documentation of types at FFI::Platypus::Type
86       and its custom types API at FFI::Platypus::API.
87

CONSTRUCTORS

89   new
90        my $ffi = FFI::Platypus->new(%options);
91
92       Create a new instance of FFI::Platypus.
93
94       Any types defined with this instance will be valid for this instance
95       only, so you do not need to worry about stepping on the toes of other
96       CPAN FFI / Platypus Authors.
97
98       Any functions found will be out of the list of libraries specified with
99       the lib attribute.
100
101       options
102
103       api Sets the API level.  Legal values are
104
105           0   Original API level.  See FFI::Platypus::TypeParser::Version0
106               for details on the differences.
107
108           1   Enable the next generation type parser which allows pass-by-
109               value records and type decoration on basic types.  Using API
110               level 1 prior to Platypus version 1.00 will trigger a (noisy)
111               warning.
112
113       lib Either a pathname (string) or a list of pathnames (array ref of
114           strings) to pre-populate the lib attribute.  Use "[undef]" to
115           search the current process for symbols.
116
117           0.48
118
119           "undef" (without the array reference) can be used to search the
120           current process for symbols.
121
122       ignore_not_found
123           [version 0.15]
124
125           Set the ignore_not_found attribute.
126
127       lang
128           [version 0.18]
129
130           Set the lang attribute.
131

ATTRIBUTES

133   lib
134        $ffi->lib($path1, $path2, ...);
135        my @paths = $ffi->lib;
136
137       The list of libraries to search for symbols in.
138
139       The most portable and reliable way to find dynamic libraries is by
140       using FFI::CheckLib, like this:
141
142        use FFI::CheckLib 0.06;
143        $ffi->lib(find_lib_or_die lib => 'archive');
144          # finds libarchive.so on Linux
145          #       libarchive.bundle on OS X
146          #       libarchive.dll (or archive.dll) on Windows
147          #       cygarchive-13.dll on Cygwin
148          #       ...
149          # and will die if it isn't found
150
151       FFI::CheckLib has a number of options, such as checking for specific
152       symbols, etc.  You should consult the documentation for that module.
153
154       As a special case, if you add "undef" as a "library" to be searched,
155       Platypus will also search the current process for symbols. This is
156       mostly useful for finding functions in the standard C library, without
157       having to know the name of the standard c library for your platform (as
158       it turns out it is different just about everywhere!).
159
160       You may also use the "find_lib" method as a shortcut:
161
162        $ffi->find_lib( lib => 'archive' );
163
164   ignore_not_found
165       [version 0.15]
166
167        $ffi->ignore_not_found(1);
168        my $ignore_not_found = $ffi->ignore_not_found;
169
170       Normally the attach and function methods will throw an exception if it
171       cannot find the name of the function you provide it.  This will change
172       the behavior such that function will return "undef" when the function
173       is not found and attach will ignore functions that are not found.  This
174       is useful when you are writing bindings to a library and have many
175       optional functions and you do not wish to wrap every call to function
176       or attach in an "eval".
177
178   lang
179       [version 0.18]
180
181        $ffi->lang($language);
182
183       Specifies the foreign language that you will be interfacing with. The
184       default is C.  The foreign language specified with this attribute
185       changes the default native types (for example, if you specify Rust, you
186       will get "i32" as an alias for "sint32" instead of "int" as you do with
187       C).
188
189       If the foreign language plugin supports it, this will also enable
190       Platypus to find symbols using the demangled names (for example, if you
191       specify CPP for C++ you can use method names like "Foo::get_bar()" with
192       "attach" or "function".
193

METHODS

195   type
196        $ffi->type($typename);
197        $ffi->type($typename => $alias);
198
199       Define a type.  The first argument is the native or C name of the type.
200       The second argument (optional) is an alias name that you can use to
201       refer to this new type.  See FFI::Platypus::Type for legal type
202       definitions.
203
204       Examples:
205
206        $ffi->type('sint32'); # oly checks to see that sint32 is a valid type
207        $ffi->type('sint32' => 'myint'); # creates an alias myint for sint32
208        $ffi->type('bogus'); # dies with appropriate diagnostic
209
210   custom_type
211        $ffi->custom_type($alias => {
212          native_type         => $native_type,
213          native_to_perl      => $coderef,
214          perl_to_native      => $coderef,
215          perl_to_native_post => $coderef,
216        });
217
218       Define a custom type.  See FFI::Platypus::Type#Custom-Types for
219       details.
220
221   load_custom_type
222        $ffi->load_custom_type($name => $alias, @type_args);
223
224       Load the custom type defined in the module $name, and make an alias
225       $alias. If the custom type requires any arguments, they may be passed
226       in as @type_args. See FFI::Platypus::Type#Custom-Types for details.
227
228       If $name contains "::" then it will be assumed to be a fully qualified
229       package name. If not, then "FFI::Platypus::Type::" will be prepended to
230       it.
231
232   types
233        my @types = $ffi->types;
234        my @types = FFI::Platypus->types;
235
236       Returns the list of types that FFI knows about.  This will include the
237       native "libffi" types (example: "sint32", "opaque" and "double") and
238       the normal C types (example: "unsigned int", "uint32_t"), any types
239       that you have defined using the type method, and custom types.
240
241       The list of types that Platypus knows about varies somewhat from
242       platform to platform, FFI::Platypus::Type includes a list of the core
243       types that you can always count on having access to.
244
245       It can also be called as a class method, in which case, no user defined
246       or custom types will be included in the list.
247
248   type_meta
249        my $meta = $ffi->type_meta($type_name);
250        my $meta = FFI::Platypus->type_meta($type_name);
251
252       Returns a hash reference with the meta information for the given type.
253
254       It can also be called as a class method, in which case, you won't be
255       able to get meta data on user defined types.
256
257       The format of the meta data is implementation dependent and subject to
258       change.  It may be useful for display or debugging.
259
260       Examples:
261
262        my $meta = $ffi->type_meta('int');        # standard int type
263        my $meta = $ffi->type_meta('int[64]');    # array of 64 ints
264        $ffi->type('int[128]' => 'myintarray');
265        my $meta = $ffi->type_meta('myintarray'); # array of 128 ints
266
267   mangler
268        $ffi->mangler(\&mangler);
269
270       Specify a customer mangler to be used for symbol lookup.  This is
271       usually useful when you are writing bindings for a library where all of
272       the functions have the same prefix.  Example:
273
274        $ffi->mangler(sub {
275          my($symbol) = @_;
276          return "foo_$symbol";
277        });
278
279        $ffi->function( get_bar => [] => 'int' );  # attaches foo_get_bar
280
281        my $f = $ffi->function( set_baz => ['int'] => 'void' );
282        $f->call(22); # calls foo_set_baz
283
284   function
285        my $function = $ffi->function($name => \@argument_types => $return_type);
286        my $function = $ffi->function($address => \@argument_types => $return_type);
287        my $function = $ffi->function($name => \@argument_types => $return_type, \&wrapper);
288        my $function = $ffi->function($address => \@argument_types => $return_type, \&wrapper);
289
290       Returns an object that is similar to a code reference in that it can be
291       called like one.
292
293       Caveat: many situations require a real code reference, so at the price
294       of a performance penalty you can get one like this:
295
296        my $function = $ffi->function(...);
297        my $coderef = sub { $function->(@_) };
298
299       It may be better, and faster to create a real Perl function using the
300       attach method.
301
302       In addition to looking up a function by name you can provide the
303       address of the symbol yourself:
304
305        my $address = $ffi->find_symbol('my_functon');
306        my $function = $ffi->function($address => ...);
307
308       Under the covers, function uses find_symbol when you provide it with a
309       name, but it is useful to keep this in mind as there are alternative
310       ways of obtaining a functions address.  Example: a C function could
311       return the address of another C function that you might want to call,
312       or modules such as FFI::TinyCC produce machine code at runtime that you
313       can call from Platypus.
314
315       [version 0.76]
316
317       If the last argument is a code reference, then it will be used as a
318       wrapper around the function when called.  The first argument to the
319       wrapper will be the inner function, or if it is later attached an xsub.
320       This can be used if you need to verify/modify input/output data.
321
322       Examples:
323
324        my $function = $ffi->function('my_function_name', ['int', 'string'] => 'string');
325        my $return_string = $function->(1, "hi there");
326
327       [version 0.91]
328
329        my $function = $ffi->function( $name => \@fixed_argument_types => \@var_argument_types => $return_type);
330        my $function = $ffi->function( $name => \@fixed_argument_types => \@var_argument_types => $return_type, \&wrapper);
331
332       Version 0.91 and later allows you to creat functions for c variadic
333       functions (such as printf, scanf, etc) which can take a variable number
334       of arguments.  The first set of arguments are the fixed set, the second
335       set are the variable arguments to bind with.  The variable argument
336       types must be specified in order to create a function object, so if you
337       need to call variadic function with different set of arguments then you
338       will need to create a new function object each time:
339
340        # int printf(const char *fmt, ...);
341        $ffi->function( printf => ['string'] => ['int'] => 'int' )
342            ->call("print integer %d\n", 42);
343        $ffi->function( printf => ['string'] => ['string'] => 'int' )
344            ->call("print string %s\n", 'platypus');
345
346       Some older versions of libffi and possibly some platforms may not
347       support variadic functions.  If you try to create a one, then an
348       exception will be thrown.
349
350   attach
351        $ffi->attach($name => \@argument_types => $return_type);
352        $ffi->attach([$c_name => $perl_name] => \@argument_types => $return_type);
353        $ffi->attach([$address => $perl_name] => \@argument_types => $return_type);
354        $ffi->attach($name => \@argument_types => $return_type, \&wrapper);
355        $ffi->attach([$c_name => $perl_name] => \@argument_types => $return_type, \&wrapper);
356        $ffi->attach([$address => $perl_name] => \@argument_types => $return_type, \&wrapper);
357
358       Find and attach a C function as a real live Perl xsub.  The advantage
359       of attaching a function over using the function method is that it is
360       much much much faster since no object resolution needs to be done.  The
361       disadvantage is that it locks the function and the FFI::Platypus
362       instance into memory permanently, since there is no way to deallocate
363       an xsub.
364
365       If just one $name is given, then the function will be attached in Perl
366       with the same name as it has in C.  The second form allows you to give
367       the Perl function a different name.  You can also provide an address
368       (the third form), just like with the function method.
369
370       Examples:
371
372        $ffi->attach('my_functon_name', ['int', 'string'] => 'string');
373        $ffi->attach(['my_c_functon_name' => 'my_perl_function_name'], ['int', 'string'] => 'string');
374        my $string1 = my_function_name($int);
375        my $string2 = my_perl_function_name($int);
376
377       [version 0.20]
378
379       If the last argument is a code reference, then it will be used as a
380       wrapper around the attached xsub.  The first argument to the wrapper
381       will be the inner xsub.  This can be used if you need to verify/modify
382       input/output data.
383
384       Examples:
385
386        $ffi->attach('my_function', ['int', 'string'] => 'string', sub {
387          my($my_function_xsub, $integer, $string) = @_;
388          $integer++;
389          $string .= " and another thing";
390          my $return_string = $my_function_xsub->($integer, $string);
391          $return_string =~ s/Belgium//; # HHGG remove profanity
392          $return_string;
393        });
394
395       [version 0.91]
396
397        $ffi->attach($name => \@fixed_argument_types => \@var_argument_types, $return_type);
398        $ffi->attach($name => \@fixed_argument_types => \@var_argument_types, $return_type, \&wrapper);
399
400       As of version 0.91 you can attach a variadic functions, if it is
401       supported by the platform / libffi that you are using.  For details see
402       the "function" documentation.  If not supported by the implementation
403       then an exception will be thrown.
404
405   closure
406        my $closure = $ffi->closure($coderef);
407
408       Prepares a code reference so that it can be used as a FFI closure (a
409       Perl subroutine that can be called from C code).  For details on
410       closures, see FFI::Platypus::Type#Closures and FFI::Platypus::Closure.
411
412   cast
413        my $converted_value = $ffi->cast($original_type, $converted_type, $original_value);
414
415       The "cast" function converts an existing $original_value of type
416       $original_type into one of type $converted_type.  Not all types are
417       supported, so care must be taken.  For example, to get the address of a
418       string, you can do this:
419
420        my $address = $ffi->cast('string' => 'opaque', $string_value);
421
422       Something that won't work is trying to cast an array to anything:
423
424        my $address = $ffi->cast('int[10]' => 'opaque', \@list);  # WRONG
425
426   attach_cast
427        $ffi->attach_cast("cast_name", $original_type, $converted_type);
428        my $converted_value = cast_name($original_value);
429
430       This function attaches a cast as a permanent xsub.  This will make it
431       faster and may be useful if you are calling a particular cast a lot.
432
433   sizeof
434        my $size = $ffi->sizeof($type);
435
436       Returns the total size of the given type in bytes.  For example to get
437       the size of an integer:
438
439        my $intsize = $ffi->sizeof('int');   # usually 4
440        my $longsize = $ffi->sizeof('long'); # usually 4 or 8 depending on platform
441
442       You can also get the size of arrays
443
444        my $intarraysize = $ffi->sizeof('int[64]');  # usually 4*64
445        my $intarraysize = $ffi->sizeof('long[64]'); # usually 4*64 or 8*64
446                                                     # depending on platform
447
448       Keep in mind that "pointer" types will always be the pointer / word
449       size for the platform that you are using.  This includes strings,
450       opaque and pointers to other types.
451
452       This function is not very fast, so you might want to save this value as
453       a constant, particularly if you need the size in a loop with many
454       iterations.
455
456   alignof
457       [version 0.21]
458
459        my $align = $ffi->alignof($type);
460
461       Returns the alignment of the given type in bytes.
462
463   find_lib
464       [version 0.20]
465
466        $ffi->find_lib( lib => $libname );
467
468       This is just a shortcut for calling FFI::CheckLib#find_lib and updating
469       the "lib" attribute appropriately.  Care should be taken though, as
470       this method simply passes its arguments to FFI::CheckLib#find_lib, so
471       if your module or script is depending on a specific feature in
472       FFI::CheckLib then make sure that you update your prerequisites
473       appropriately.
474
475   find_symbol
476        my $address = $ffi->find_symbol($name);
477
478       Return the address of the given symbol (usually function).
479
480   package
481       [version 0.15]
482
483        $ffi->package($package, $file); # usually __PACKAGE__ and __FILE__ can be used
484        $ffi->package;                  # autodetect
485
486       If you use FFI::Build (or the older deprecated Module::Build::FFI to
487       bundle C code with your distribution, you can use this method to tell
488       the FFI::Platypus instance to look for symbols that came with the
489       dynamic library that was built when your distribution was installed.
490
491   abis
492        my $href = $ffi->abis;
493        my $href = FFI::Platypus->abis;
494
495       Get the legal ABIs supported by your platform and underlying
496       implementation.  What is supported can vary a lot by CPU and by
497       platform, or even between 32 and 64 bit on the same CPU and platform.
498       They keys are the "ABI" names, also known as "calling conventions".
499       The values are integers used internally by the implementation to
500       represent those ABIs.
501
502   abi
503        $ffi->abi($name);
504
505       Set the ABI or calling convention for use in subsequent calls to
506       "function" or "attach".  May be either a string name or integer value
507       from the "abis" method above.
508

EXAMPLES

510       Here are some examples.  These examples are provided in full with the
511       Platypus distribution in the "examples" directory.  There are also some
512       more examples in FFI::Platypus::Type that are related to types.
513
514   Integer conversions
515        use FFI::Platypus;
516
517        my $ffi = FFI::Platypus->new;
518        $ffi->lib(undef);
519
520        $ffi->attach(puts => ['string'] => 'int');
521        $ffi->attach(atoi => ['string'] => 'int');
522
523        puts(atoi('56'));
524
525       Discussion: "puts" and "atoi" should be part of the standard C library
526       on all platforms.  "puts" prints a string to standard output, and
527       "atoi" converts a string to integer.  Specifying "undef" as a library
528       tells Platypus to search the current process for symbols, which
529       includes the standard c library.
530
531   libnotify
532        use FFI::CheckLib;
533        use FFI::Platypus;
534
535        # NOTE: I ported this from anoter Perl FFI library and it seems to work most
536        # of the time, but also seems to SIGSEGV sometimes.  I saw the same behavior
537        # in the old version, and am not really familiar with the libnotify API to
538        # say what is the cause.  Patches welcome to fix it.
539
540        my $ffi = FFI::Platypus->new;
541        $ffi->lib(find_lib_or_exit lib => 'notify');
542
543        $ffi->attach(notify_init   => ['string'] => 'void');
544        $ffi->attach(notify_uninit => []       => 'void');
545        $ffi->attach([notify_notification_new    => 'notify_new']    => ['string', 'string', 'string']           => 'opaque');
546        $ffi->attach([notify_notification_update => 'notify_update'] => ['opaque', 'string', 'string', 'string'] => 'void');
547        $ffi->attach([notify_notification_show   => 'notify_show']   => ['opaque', 'opaque']                     => 'void');
548
549        notify_init('FFI::Platypus');
550        my $n = notify_new('','','');
551        notify_update($n, 'FFI::Platypus', 'It works!!!', 'media-playback-start');
552        notify_show($n, undef);
553        notify_uninit();
554
555       Discussion: libnotify is a desktop GUI notification library for the
556       GNOME Desktop environment. This script sends a notification event that
557       should show up as a balloon, for me it did so in the upper right hand
558       corner of my screen.
559
560       The most portable way to find the correct name and location of a
561       dynamic library is via the FFI::CheckLib#find_lib family of functions.
562       If you are putting together a CPAN distribution, you should also
563       consider using FFI::CheckLib#check_lib_or_exit function in your
564       "Build.PL" or "Makefile.PL" file (If you are using Dist::Zilla, check
565       out the Dist::Zilla::Plugin::FFI::CheckLib plugin). This will provide a
566       user friendly diagnostic letting the user know that the required
567       library is missing, and reduce the number of bogus CPAN testers results
568       that you will get.
569
570       Also in this example, we rename some of the functions when they are
571       placed into Perl space to save typing:
572
573        $ffi->attach( [notify_notification_new => 'notify_new']
574          => ['string','string','string']
575          => 'opaque'
576        );
577
578       When you specify a list reference as the "name" of the function the
579       first element is the symbol name as understood by the dynamic library.
580       The second element is the name as it will be placed in Perl space.
581
582       Later, when we call "notify_new":
583
584        my $n = notify_new('','','');
585
586       We are really calling the C function "notify_notification_new".
587
588   Allocating and freeing memory
589        use FFI::Platypus;
590        use FFI::Platypus::Memory qw( malloc free memcpy );
591
592        my $ffi = FFI::Platypus->new;
593        my $buffer = malloc 12;
594
595        memcpy $buffer, $ffi->cast('string' => 'opaque', "hello there"), length "hello there\0";
596
597        print $ffi->cast('opaque' => 'string', $buffer), "\n";
598
599        free $buffer;
600
601       Discussion: "malloc" and "free" are standard memory allocation
602       functions available from the standard c library and.  Interfaces to
603       these and other memory related functions are provided by the
604       FFI::Platypus::Memory module.
605
606   structured data records
607        package My::UnixTime;
608
609        use FFI::Platypus::Record;
610
611        record_layout(qw(
612            int    tm_sec
613            int    tm_min
614            int    tm_hour
615            int    tm_mday
616            int    tm_mon
617            int    tm_year
618            int    tm_wday
619            int    tm_yday
620            int    tm_isdst
621            long   tm_gmtoff
622            string tm_zone
623        ));
624
625        my $ffi = FFI::Platypus->new;
626        $ffi->lib(undef);
627        # define a record class My::UnixTime and alias it to "tm"
628        $ffi->type("record(My::UnixTime)" => 'tm');
629
630        # attach the C localtime function as a constructor
631        $ffi->attach( localtime => ['time_t*'] => 'tm', sub {
632          my($inner, $class, $time) = @_;
633          $time = time unless defined $time;
634          $inner->(\$time);
635        });
636
637        package main;
638
639        # now we can actually use our My::UnixTime class
640        my $time = My::UnixTime->localtime;
641        printf "time is %d:%d:%d %s\n",
642          $time->tm_hour,
643          $time->tm_min,
644          $time->tm_sec,
645          $time->tm_zone;
646
647       Discussion: C and other machine code languages frequently provide
648       interfaces that include structured data records (known as "structs" in
649       C).  They sometimes provide an API in which you are expected to
650       manipulate these records before and/or after passing them along to C
651       functions.  There are a few ways of dealing with such interfaces, but
652       the easiest way is demonstrated here defines a record class using a
653       specific layout.  For more details see FFI::Platypus::Record.
654       (FFI::Platypus::Type includes some other ways of manipulating
655       structured data records).
656
657   libuuid
658        use FFI::CheckLib;
659        use FFI::Platypus;
660        use FFI::Platypus::Memory qw( malloc free );
661
662        my $ffi = FFI::Platypus->new;
663        $ffi->lib(find_lib_or_exit lib => 'uuid');
664        $ffi->type('string(37)' => 'uuid_string');
665        $ffi->type('record(16)' => 'uuid_t');
666
667        $ffi->attach(uuid_generate => ['uuid_t'] => 'void');
668        $ffi->attach(uuid_unparse  => ['uuid_t','uuid_string'] => 'void');
669
670        my $uuid = "\0" x 16;  # uuid_t
671        uuid_generate($uuid);
672
673        my $string = "\0" x 37; # 36 bytes to store a UUID string
674                                # + NUL termination
675        uuid_unparse($uuid, $string);
676
677        print "$string\n";
678
679       Discussion: libuuid is a library used to generate unique identifiers
680       (UUID) for objects that may be accessible beyond the local system.  The
681       library is or was part of the Linux e2fsprogs package.
682
683       Knowing the size of objects is sometimes important.  In this example,
684       we use the sizeof function to get the size of 16 characters (in this
685       case it is simply 16 bytes).  We also know that the strings "deparsed"
686       by "uuid_unparse" are exactly 37 bytes.
687
688   puts and getpid
689        use FFI::Platypus;
690
691        my $ffi = FFI::Platypus->new;
692        $ffi->lib(undef);
693
694        $ffi->attach(puts => ['string'] => 'int');
695        $ffi->attach(getpid => [] => 'int');
696
697        puts(getpid());
698
699       Discussion: "puts" is part of standard C library on all platforms.
700       "getpid" is available on Unix type platforms.
701
702   Math library
703        use FFI::Platypus;
704        use FFI::CheckLib;
705
706        my $ffi = FFI::Platypus->new;
707        $ffi->lib(undef);
708        $ffi->attach(puts => ['string'] => 'int');
709        $ffi->attach(fdim => ['double','double'] => 'double');
710
711        puts(fdim(7.0, 2.0));
712
713        $ffi->attach(cos => ['double'] => 'double');
714
715        puts(cos(2.0));
716
717        $ffi->attach(fmax => ['double', 'double'] => 'double');
718
719        puts(fmax(2.0,3.0));
720
721       Discussion: On UNIX the standard c library math functions are
722       frequently provided in a separate library "libm", so you could search
723       for those symbols in "libm.so", but that won't work on non-UNIX
724       platforms like Microsoft Windows.  Fortunately Perl uses the math
725       library so these symbols are already in the current process so you can
726       use "undef" as the library to find them.
727
728   Strings
729        use FFI::Platypus;
730
731        my $ffi = FFI::Platypus->new;
732        $ffi->lib(undef);
733        $ffi->attach(puts => ['string'] => 'int');
734        $ffi->attach(strlen => ['string'] => 'int');
735
736        puts(strlen('somestring'));
737
738        $ffi->attach(strstr => ['string','string'] => 'string');
739
740        puts(strstr('somestring', 'string'));
741
742        #attach puts => [string] => int;
743
744        puts(puts("lol"));
745
746        $ffi->attach(strerror => ['int'] => 'string');
747
748        puts(strerror(2));
749
750       Discussion: Strings are not a native type to "libffi" but the are
751       handled seamlessly by Platypus.
752
753   Attach function from pointer
754        use FFI::TinyCC;
755        use FFI::Platypus;
756
757        my $ffi = FFI::Platypus->new;
758        my $tcc = FFI::TinyCC->new;
759
760        $tcc->compile_string(q{
761          int
762          add(int a, int b)
763          {
764            return a+b;
765          }
766        });
767
768        my $address = $tcc->get_symbol('add');
769
770        $ffi->attach( [ $address => 'add' ] => ['int','int'] => 'int' );
771
772        print add(1,2), "\n";
773
774       Discussion: Sometimes you will have a pointer to a function from a
775       source other than Platypus that you want to call.  You can use that
776       address instead of a function name for either of the function or attach
777       methods.  In this example we use FFI::TinyCC to compile a short piece
778       of C code and to give us the address of one of its functions, which we
779       then use to create a perl xsub to call it.
780
781       FFI::TinyCC embeds the Tiny C Compiler (tcc) to provide a just-in-time
782       (JIT) compilation service for FFI.
783
784   libzmq
785        use constant ZMQ_IO_THREADS  => 1;
786        use constant ZMQ_MAX_SOCKETS => 2;
787        use constant ZMQ_REQ => 3;
788        use constant ZMQ_REP => 4;
789        use FFI::CheckLib qw( find_lib_or_exit );
790        use FFI::Platypus;
791        use FFI::Platypus::Memory qw( malloc );
792        use FFI::Platypus::Buffer qw( scalar_to_buffer buffer_to_scalar );
793
794        my $endpoint = "ipc://zmq-ffi-$$";
795        my $ffi = FFI::Platypus->new;
796
797        $ffi->lib(undef); # for puts
798        $ffi->attach(puts => ['string'] => 'int');
799
800        $ffi->lib(find_lib_or_exit lib => 'zmq');
801        $ffi->attach(zmq_version => ['int*', 'int*', 'int*'] => 'void');
802
803        my($major,$minor,$patch);
804        zmq_version(\$major, \$minor, \$patch);
805        puts("libzmq version $major.$minor.$patch");
806        die "this script only works with libzmq 3 or better" unless $major >= 3;
807
808        $ffi->type('opaque'       => 'zmq_context');
809        $ffi->type('opaque'       => 'zmq_socket');
810        $ffi->type('opaque'       => 'zmq_msg_t');
811        $ffi->attach(zmq_ctx_new  => [] => 'zmq_context');
812        $ffi->attach(zmq_ctx_set  => ['zmq_context', 'int', 'int'] => 'int');
813        $ffi->attach(zmq_socket   => ['zmq_context', 'int'] => 'zmq_socket');
814        $ffi->attach(zmq_connect  => ['opaque', 'string'] => 'int');
815        $ffi->attach(zmq_bind     => ['zmq_socket', 'string'] => 'int');
816        $ffi->attach(zmq_send     => ['zmq_socket', 'opaque', 'size_t', 'int'] => 'int');
817        $ffi->attach(zmq_msg_init => ['zmq_msg_t'] => 'int');
818        $ffi->attach(zmq_msg_recv => ['zmq_msg_t', 'zmq_socket', 'int'] => 'int');
819        $ffi->attach(zmq_msg_data => ['zmq_msg_t'] => 'opaque');
820        $ffi->attach(zmq_errno    => [] => 'int');
821        $ffi->attach(zmq_strerror => ['int'] => 'string');
822
823        my $context = zmq_ctx_new();
824        zmq_ctx_set($context, ZMQ_IO_THREADS, 1);
825
826        my $socket1 = zmq_socket($context, ZMQ_REQ);
827        zmq_connect($socket1, $endpoint);
828
829        my $socket2 = zmq_socket($context, ZMQ_REP);
830        zmq_bind($socket2, $endpoint);
831
832        do { # send
833          our $sent_message = "hello there";
834          my($pointer, $size) = scalar_to_buffer $sent_message;
835          my $r = zmq_send($socket1, $pointer, $size, 0);
836          die zmq_strerror(zmq_errno()) if $r == -1;
837        };
838
839        do { # recv
840          my $msg_ptr  = malloc 100;
841          zmq_msg_init($msg_ptr);
842          my $size     = zmq_msg_recv($msg_ptr, $socket2, 0);
843          die zmq_strerror(zmq_errno()) if $size == -1;
844          my $data_ptr = zmq_msg_data($msg_ptr);
845          my $recv_message = buffer_to_scalar $data_ptr, $size;
846          print "recv_message = $recv_message\n";
847        };
848
849       Discussion: ØMQ is a high-performance asynchronous messaging library.
850       There are a few things to note here.
851
852       Firstly, sometimes there may be multiple versions of a library in the
853       wild and you may need to verify that the library on a system meets your
854       needs (alternatively you could support multiple versions and configure
855       your bindings dynamically).  Here we use "zmq_version" to ask libzmq
856       which version it is.
857
858       "zmq_version" returns the version number via three integer pointer
859       arguments, so we use the pointer to integer type: "int *".  In order to
860       pass pointer types, we pass a reference. In this case it is a reference
861       to an undefined value, because zmq_version will write into the pointers
862       the output values, but you can also pass in references to integers,
863       floating point values and opaque pointer types.  When the function
864       returns the $major variable (and the others) has been updated and we
865       can use it to verify that it supports the API that we require.
866
867       Notice that we define three aliases for the "opaque" type:
868       "zmq_context", "zmq_socket" and "zmq_msg_t".  While this isn't strictly
869       necessary, since Platypus and C treat all three of these types the
870       same, it is useful form of documentation that helps describe the
871       functionality of the interface.
872
873       Finally we attach the necessary functions, send and receive a message.
874       If you are interested, there is a fully fleshed out ØMQ Perl interface
875       implemented using FFI called ZMQ::FFI.
876
877   libarchive
878        use FFI::Platypus      ();
879        use FFI::Platypus::API ();
880        use FFI::CheckLib      ();
881
882        # This example uses FreeBSD's libarchive to list the contents of any
883        # archive format that it suppors.  We've also filled out a part of
884        # the ArchiveWrite class that could be used for writing archive formats
885        # supported by libarchive
886
887        my $ffi = My::Platypus->new;
888        $ffi->lib(FFI::CheckLib::find_lib_or_exit lib => 'archive');
889
890        $ffi->custom_type(archive => {
891          native_type    => 'opaque',
892          perl_to_native => sub { ${$_[0]} },
893          native_to_perl => sub {
894            # this works because archive_read_new ignores any arguments
895            # and we pass in the class name which we can get here.
896            my $class = FFI::Platypus::API::arguments_get_string(0);
897            bless \$_[0], $class;
898          },
899        });
900
901        $ffi->custom_type(archive_entry => {
902          native_type => 'opaque',
903          perl_to_native => sub { ${$_[0]} },
904          native_to_perl => sub {
905            # works likewise for archive_entry objects
906            my $class = FFI::Platypus::API::arguments_get_string(0);
907            bless \$_[0], $class,
908          },
909        });
910
911        package My::Platypus;
912
913        use base qw( FFI::Platypus );
914
915        sub find_symbol
916        {
917          my($self, $name) = @_;
918          my $prefix = lcfirst caller(2);
919          $prefix =~ s{([A-Z])}{"_" . lc $1}eg;
920          $self->SUPER::find_symbol(join '_', $prefix, $name);
921        }
922
923        package Archive;
924
925        # base class is "abstract" having no constructor or destructor
926
927        $ffi->attach( error_string => ['archive'] => 'string' );
928
929        package ArchiveRead;
930
931        our @ISA = qw( Archive );
932
933        $ffi->attach( new                   => ['string']                    => 'archive' );
934        $ffi->attach( [ free => 'DESTROY' ] => ['archive']                   => 'void' );
935        $ffi->attach( support_filter_all    => ['archive']                   => 'int' );
936        $ffi->attach( support_format_all    => ['archive']                   => 'int' );
937        $ffi->attach( open_filename         => ['archive','string','size_t'] => 'int' );
938        $ffi->attach( next_header2          => ['archive', 'archive_entry' ] => 'int' );
939        $ffi->attach( data_skip             => ['archive']                   => 'int' );
940        # ... define additional read methods
941
942        package ArchiveWrite;
943
944        our @ISA = qw( Archive );
945
946        $ffi->attach( new                   => ['string'] => 'archive' );
947        $ffi->attach( [ free => 'DESTROY' ] => ['archive'] => 'void' );
948        # ... define additional write methods
949
950        package ArchiveEntry;
951
952        $ffi->attach( new => ['string']     => 'archive_entry' );
953        $ffi->attach( [ free => 'DESTROY' ] => ['archive_entry'] => 'void' );
954        $ffi->attach( pathname              => ['archive_entry'] => 'string' );
955        # ... define additional entry methods
956
957        package main;
958
959        use constant ARCHIVE_OK => 0;
960
961        # this is a Perl version of the C code here:
962        # https://github.com/libarchive/libarchive/wiki/Examples#List_contents_of_Archive_stored_in_File
963
964        my $archive_filename = shift @ARGV;
965        unless(defined $archive_filename)
966        {
967          print "usage: $0 archive.tar\n";
968          exit;
969        }
970
971        my $archive = ArchiveRead->new;
972        $archive->support_filter_all;
973        $archive->support_format_all;
974
975        my $r = $archive->open_filename($archive_filename, 1024);
976        die "error opening $archive_filename: ", $archive->error_string
977          unless $r == ARCHIVE_OK;
978
979        my $entry = ArchiveEntry->new;
980
981        while($archive->next_header2($entry) == ARCHIVE_OK)
982        {
983          print $entry->pathname, "\n";
984          $archive->data_skip;
985        }
986
987       Discussion: libarchive is the implementation of "tar" for FreeBSD
988       provided as a library and available on a number of platforms.
989
990       One interesting thing about libarchive is that it provides a kind of
991       object oriented interface via opaque pointers.  This example creates an
992       abstract class "Archive", and concrete classes "ArchiveWrite",
993       "ArchiveRead" and "ArchiveEntry".  The concrete classes can even be
994       inherited from and extended just like any Perl classes because of the
995       way the custom types are implemented.  For more details on custom types
996       see FFI::Platypus::Type and FFI::Platypus::API.
997
998       Another advanced feature of this example is that we extend the
999       FFI::Platypus class to define our own find_symbol method that prefixes
1000       the symbol names depending on the class in which they are defined. This
1001       means we can do this when we define a method for Archive:
1002
1003        $ffi->attach( support_filter_all => ['archive'] => 'int' );
1004
1005       Rather than this:
1006
1007        $ffi->attach(
1008          [ archive_read_support_filter_all => 'support_read_filter_all' ] =>
1009          ['archive'] => 'int' );
1010        );
1011
1012       If you didn't want to create an entire new class just for this little
1013       trick you could also use something like Object::Method to extend
1014       "find_symbol".
1015
1016   bzip2
1017        use FFI::Platypus 0.20 (); # 0.20 required for using wrappers
1018        use FFI::CheckLib qw( find_lib_or_die );
1019        use FFI::Platypus::Buffer qw( scalar_to_buffer buffer_to_scalar );
1020        use FFI::Platypus::Memory qw( malloc free );
1021
1022        my $ffi = FFI::Platypus->new;
1023        $ffi->lib(find_lib_or_die lib => 'bz2');
1024
1025        $ffi->attach(
1026          [ BZ2_bzBuffToBuffCompress => 'compress' ] => [
1027            'opaque',                           # dest
1028            'unsigned int *',                   # dest length
1029            'opaque',                           # source
1030            'unsigned int',                     # source length
1031            'int',                              # blockSize100k
1032            'int',                              # verbosity
1033            'int',                              # workFactor
1034          ] => 'int',
1035          sub {
1036            my $sub = shift;
1037            my($source,$source_length) = scalar_to_buffer $_[0];
1038            my $dest_length = int(length($source)*1.01) + 1 + 600;
1039            my $dest = malloc $dest_length;
1040            my $r = $sub->($dest, \$dest_length, $source, $source_length, 9, 0, 30);
1041            die "bzip2 error $r" unless $r == 0;
1042            my $compressed = buffer_to_scalar($dest, $dest_length);
1043            free $dest;
1044            $compressed;
1045          },
1046        );
1047
1048        $ffi->attach(
1049          [ BZ2_bzBuffToBuffDecompress => 'decompress' ] => [
1050            'opaque',                           # dest
1051            'unsigned int *',                   # dest length
1052            'opaque',                           # source
1053            'unsigned int',                     # source length
1054            'int',                              # small
1055            'int',                              # verbosity
1056          ] => 'int',
1057          sub {
1058            my $sub = shift;
1059            my($source, $source_length) = scalar_to_buffer $_[0];
1060            my $dest_length = $_[1];
1061            my $dest = malloc $dest_length;
1062            my $r = $sub->($dest, \$dest_length, $source, $source_length, 0, 0);
1063            die "bzip2 error $r" unless $r == 0;
1064            my $decompressed = buffer_to_scalar($dest, $dest_length);
1065            free $dest;
1066            $decompressed;
1067          },
1068        );
1069
1070        my $original = "hello compression world\n";
1071        my $compressed = compress($original);
1072        print decompress($compressed, length $original);
1073
1074       Discussion: bzip2 is a compression library.  For simple one shot
1075       attempts at compression/decompression when you expect the original and
1076       the result to fit within memory it provides two convenience functions
1077       "BZ2_bzBuffToBuffCompress" and "BZ2_bzBuffToBuffDecompress".
1078
1079       The first four arguments of both of these C functions are identical,
1080       and represent two buffers.  One buffer is the source, the second is the
1081       destination.  For the destination, the length is passed in as a pointer
1082       to an integer.  On input this integer is the size of the destination
1083       buffer, and thus the maximum size of the compressed or decompressed
1084       data.  When the function returns the actual size of compressed or
1085       compressed data is stored in this integer.
1086
1087       This is normal stuff for C, but in Perl our buffers are scalars and
1088       they already know how large they are.  In this sort of situation,
1089       wrapping the C function in some Perl code can make your interface a
1090       little more Perl like.  In order to do this, just provide a code
1091       reference as the last argument to the "attach" method.  The first
1092       argument to this wrapper will be a code reference to the C function.
1093       The Perl arguments will come in after that.  This allows you to modify
1094       / convert the arguments to conform to the C API.  What ever value you
1095       return from the wrapper function will be returned back to the original
1096       caller.
1097

FAQ

1099   How do I get constants defined as macros in C header files
1100       This turns out to be a challenge for any language calling into C, which
1101       frequently uses "#define" macros to define constants like so:
1102
1103        #define FOO_STATIC  1
1104        #define FOO_DYNAMIC 2
1105        #define FOO_OTHER   3
1106
1107       As macros are expanded and their definitions are thrown away by the C
1108       pre-processor there isn't any way to get the name/value mappings from
1109       the compiled dynamic library.
1110
1111       You can manually create equivalent constants in your Perl source:
1112
1113        use constant FOO_STATIC  => 1;
1114        use constant FOO_DYNAMIC => 2;
1115        use constant FOO_OTHER   => 3;
1116
1117       If there are a lot of these types of constants you might want to
1118       consider using a tool (Convert::Binary::C can do this) that can extract
1119       the constants for you.
1120
1121       See also the "Integer constants" example in FFI::Platypus::Type.
1122
1123   I get seg faults on some platforms but not others with a library using
1124       pthreads.
1125       On some platforms, Perl isn't linked with "libpthreads" if Perl threads
1126       are not enabled.  On some platforms this doesn't seem to matter,
1127       "libpthreads" can be loaded at runtime without much ill-effect.  (Linux
1128       from my experience doesn't seem to mind one way or the other).  Some
1129       platforms are not happy about this, and about the only thing that you
1130       can do about it is to build Perl such that it links with "libpthreads"
1131       even if it isn't a threaded Perl.
1132
1133       This is not really an FFI issue, but a Perl issue, as you will have the
1134       same problem writing XS code for the such libraries.
1135
1136   Doesn't work on Perl 5.10.0.
1137       I try as best as possible to support the same range of Perls as the
1138       Perl toolchain.  That means all the way back to 5.8.1.  Unfortunately,
1139       5.10.0 seems to have a problem that is difficult to diagnose.  Patches
1140       to fix are welcome, if you want to help out on this, please see:
1141
1142       <https://github.com/Perl5-FFI/FFI-Platypus/issues/68>
1143
1144       Since this is an older buggy version of Perl it is recommended that you
1145       instead upgrade to 5.10.1 or later.
1146

CAVEATS

1148       Platypus and Native Interfaces like libffi rely on the availability of
1149       dynamic libraries.  Things not supported include:
1150
1151       Systems that lack dynamic library support
1152           Like MS-DOS
1153
1154       Systems that are not supported by libffi
1155           Like OpenVMS
1156
1157       Languages that do not support using dynamic libraries from other
1158       languages
1159           Like older versions of Google's Go. This is a problem for C / XS
1160           code as well.
1161
1162       Languages that do not compile to machine code
1163           Like .NET based languages and Java.
1164
1165       The documentation has a bias toward using FFI / Platypus with C.  This
1166       is my fault, as my background in mainly in C/C++ programmer (when I am
1167       not writing Perl).  In many places I use "C" as a short form for "any
1168       language that can generate machine code and is callable from C".  I
1169       welcome pull requests to the Platypus core to address this issue.  In
1170       an attempt to ease usage of Platypus by non C programmers, I have
1171       written a number of foreign language plugins for various popular
1172       languages (see the SEE ALSO below).  These plugins come with examples
1173       specific to those languages, and documentation on common issues related
1174       to using those languages with FFI.  In most cases these are available
1175       for easy adoption for those with the know-how or the willingness to
1176       learn.  If your language doesn't have a plugin YET, that is just
1177       because you haven't written it yet.
1178

SUPPORT

1180       IRC: #native on irc.perl.org
1181
1182       (click for instant chat room login)
1183       <http://chat.mibbit.com/#native@irc.perl.org>
1184
1185       If something does not work the way you think it should, or if you have
1186       a feature request, please open an issue on this project's GitHub Issue
1187       tracker:
1188
1189       <https://github.com/perl5-FFI/FFI-Platypus/issues>
1190

CONTRIBUTING

1192       If you have implemented a new feature or fixed a bug then you may make
1193       a pull request on this project's GitHub repository:
1194
1195       <https://github.com/Perl5-FFI/FFI-Platypus/pulls>
1196
1197       This project is developed using Dist::Zilla.  The project's git
1198       repository also comes with the "Makefile.PL" file necessary for
1199       building, testing (and even installing if necessary) without
1200       Dist::Zilla.  Please keep in mind though that these files are generated
1201       so if changes need to be made to those files they should be done
1202       through the project's "dist.ini" file.  If you do use Dist::Zilla and
1203       already have the necessary plugins installed, then I encourage you to
1204       run "dzil test" before making any pull requests.  This is not a
1205       requirement, however, I am happy to integrate especially smaller
1206       patches that need tweaking to fit the project standards.  I may push
1207       back and ask you to write a test case or alter the formatting of a
1208       patch depending on the amount of time I have and the amount of code
1209       that your patch touches.
1210
1211       This project's GitHub issue tracker listed above is not Write-Only.  If
1212       you want to contribute then feel free to browse through the existing
1213       issues and see if there is something you feel you might be good at and
1214       take a whack at the problem.  I frequently open issues myself that I
1215       hope will be accomplished by someone in the future but do not have time
1216       to immediately implement myself.
1217
1218       Another good area to help out in is documentation.  I try to make sure
1219       that there is good document coverage, that is there should be
1220       documentation describing all the public features and warnings about
1221       common pitfalls, but an outsider's or alternate view point on such
1222       things would be welcome; if you see something confusing or lacks
1223       sufficient detail I encourage documentation only pull requests to
1224       improve things.
1225
1226       The Platypus distribution comes with a test library named "libtest"
1227       that is normally automatically built by "./Build test".  If you prefer
1228       to use "prove" or run tests directly, you can use the "./Build libtest"
1229       command to build it.  Example:
1230
1231        % perl Makefile.PL
1232        % make
1233        % make ffi-test
1234        % prove -bv t
1235        # or an individual test
1236        % perl -Mblib t/ffi_platypus_memory.t
1237
1238       The build process also respects these environment variables:
1239
1240       FFI_PLATYPUS_DEBUG_FAKE32
1241           When building Platypus on 32 bit Perls, it will use the Math::Int64
1242           C API and make Math::Int64 a prerequisite.  Setting this
1243           environment variable will force Platypus to build with both of
1244           those options on a 64 bit Perl as well.
1245
1246            % env FFI_PLATYPUS_DEBUG_FAKE32=1 perl Makefile.PL
1247            DEBUG_FAKE32:
1248              + making Math::Int64 a prereq
1249              + Using Math::Int64's C API to manipulate 64 bit values
1250            Generating a Unix-style Makefile
1251            Writing Makefile for FFI::Platypus
1252            Writing MYMETA.yml and MYMETA.json
1253            %
1254
1255       FFI_PLATYPUS_NO_ALLOCA
1256           Platypus uses the non-standard and somewhat controversial C
1257           function "alloca" by default on platforms that support it.  I
1258           believe that Platypus uses it responsibly to allocate small amounts
1259           of memory for argument type parameters, and does not use it to
1260           allocate large structures like arrays or buffers.  If you prefer
1261           not to use "alloca" despite these precautions, then you can turn
1262           its use off by setting this environment variable when you run
1263           "Makefile.PL":
1264
1265            helix% env FFI_PLATYPUS_NO_ALLOCA=1 perl Makefile.PL
1266            NO_ALLOCA:
1267              + alloca() will not be used, even if your platform supports it.
1268            Generating a Unix-style Makefile
1269            Writing Makefile for FFI::Platypus
1270            Writing MYMETA.yml and MYMETA.json
1271
1272       V   When building platypus may hide some of the excessive output when
1273           probing and building, unless you set "V" to a true value.
1274
1275            % env V=1 perl Makefile.PL
1276            % make V=1
1277            ...
1278
1279   Coding Guidelines
1280       ·   Do not hesitate to make code contribution.  Making useful
1281           contributions is more important than following byzantine
1282           bureaucratic coding regulations.  We can always tweak things later.
1283
1284       ·   Please make an effort to follow existing coding style when making
1285           pull requests.
1286
1287       ·   Platypus supports all production Perl releases since 5.8.1.  For
1288           that reason, please do not introduce any code that requires a newer
1289           version of Perl.
1290
1291   Performance Testing
1292       As Mark Twain was fond of saying there are four types of lies: lies,
1293       damn lies, statistics and benchmarks.  That being said, it can
1294       sometimes be helpful to compare the runtime performance of Platypus if
1295       you are making significant changes to the Platypus Core.  For that I
1296       use `FFI-Performance`, which can be found in my GitHub repository here:
1297
1298       <https://github.com/Perl5-FFI/FFI-Performance>
1299
1300   System integrators
1301       This distribution uses Alien::FFI in fallback mode, meaning if the
1302       system doesn't provide "pkg-config" and "libffi" it will attempt to
1303       download "libffi" and build it from source.  If you are including
1304       Platypus in a larger system (for example a Linux distribution) you only
1305       need to make sure to declare "pkg-config" or "pkgconf" and the
1306       development package for "libffi" as prereqs for this module.
1307

SEE ALSO

1309       NativeCall
1310           Promising interface to Platypus inspired by Perl 6.
1311
1312       FFI::Platypus::Type
1313           Type definitions for Platypus.
1314
1315       FFI::Platypus::Record
1316           Define structured data records (C "structs") for use with Platypus.
1317
1318       FFI::Platypus::API
1319           The custom types API for Platypus.
1320
1321       FFI::Platypus::Memory
1322           Memory functions for FFI.
1323
1324       FFI::CheckLib
1325           Find dynamic libraries in a portable way.
1326
1327       Module::Build::FFI
1328           Bundle C code with your FFI extension.
1329
1330       FFI::TinyCC
1331           JIT compiler for FFI.
1332
1333       FFI::Platypus::Lang::C
1334           Documentation and tools for using Platypus with the C programming
1335           language
1336
1337       FFI::Platypus::Lang::CPP
1338           Documentation and tools for using Platypus with the C++ programming
1339           language
1340
1341       FFI::Platypus::Lang::Fortran
1342           Documentation and tools for using Platypus with Fortran
1343
1344       FFI::Platypus::Lang::Pascal
1345           Documentation and tools for using Platypus with Free Pascal
1346
1347       FFI::Platypus::Lang::Rust
1348           Documentation and tools for using Platypus with the Rust
1349           programming language
1350
1351       FFI::Platypus::Lang::ASM
1352           Documentation and tools for using Platypus with the Assembly
1353
1354       Convert::Binary::C
1355           A great interface for decoding C data structures, including
1356           "struct"s, "enum"s, "#define"s and more.
1357
1358       pack and unpack
1359           Native to Perl functions that can be used to decode C "struct"
1360           types.
1361
1362       C::Scan
1363           This module can extract constants and other useful objects from C
1364           header files that may be relevant to an FFI application.  One
1365           downside is that its use may require development packages to be
1366           installed.
1367
1368       Win32::API
1369           Microsoft Windows specific FFI style interface.
1370
1371       Ctypes <https://gitorious.org/perl-ctypes>
1372           Ctypes was intended as a FFI style interface for Perl, but was
1373           never part of CPAN, and at least the last time I tried it did not
1374           work with recent versions of Perl.
1375
1376       FFI Foreign function interface based on (nomenclature is everything)
1377           FSF's "ffcall". It hasn't worked for quite some time, and "ffcall"
1378           is no longer supported or distributed.
1379
1380       C::DynaLib
1381           Another FFI for Perl that doesn't appear to have worked for a long
1382           time.
1383
1384       C::Blocks
1385           Embed a tiny C compiler into your Perl scripts.
1386
1387       Alien::FFI
1388           Provides libffi for Platypus during its configuration and build
1389           stages.
1390
1391       P5NCI
1392           Yet another FFI like interface that does not appear to be supported
1393           or under development anymore.
1394

ACKNOWLEDGMENTS

1396       In addition to the contributors mentioned below, I would like to
1397       acknowledge Brock Wilcox (AWWAIID) and Meredith Howard (MHOWARD) whose
1398       work on FFI::Sweet <https://github.com/merrilymeredith/p5-FFI-Sweet>
1399       not only helped me get started with FFI but significantly influenced
1400       the design of Platypus.
1401
1402       In addition I'd like to thank Alessandro Ghedini (ALEXBIO) whose work
1403       on another Perl FFI library helped drive some of the development ideas
1404       for FFI::Platypus.
1405

AUTHOR

1407       Author: Graham Ollis <plicease@cpan.org>
1408
1409       Contributors:
1410
1411       Bakkiaraj Murugesan (bakkiaraj)
1412
1413       Dylan Cali (calid)
1414
1415       pipcet
1416
1417       Zaki Mughal (zmughal)
1418
1419       Fitz Elliott (felliott)
1420
1421       Vickenty Fesunov (vyf)
1422
1423       Gregor Herrmann (gregoa)
1424
1425       Shlomi Fish (shlomif)
1426
1427       Damyan Ivanov
1428
1429       Ilya Pavlov (Ilya33)
1430
1431       Petr Pisar (ppisar)
1432
1433       Mohammad S Anwar (MANWAR)
1434
1436       This software is copyright (c) 2015,2016,2017,2018,2019 by Graham
1437       Ollis.
1438
1439       This is free software; you can redistribute it and/or modify it under
1440       the same terms as the Perl 5 programming language system itself.
1441
1442
1443
1444perl v5.30.0                      2019-07-26                  FFI::Platypus(3)
Impressum