.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "FFI::Platypus::Bundle 3pm"
.TH FFI::Platypus::Bundle 3pm "2020-11-08" "perl v5.32.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
FFI::Platypus::Bundle \- Bundle foreign code with your Perl module
.SH "VERSION"
.IX Header "VERSION"
version 1.34
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
\&\f(CW\*(C`ffi/foo.c\*(C'\fR:
.PP
.Vb 2
\& #include <ffi_platypus_bundle.h>
\& #include <string.h>
\& 
\& typedef struct {
\&   char *name;
\&   int value;
\& } foo_t;
\& 
\& foo_t*
\& foo_\|_new(const char *class_name, const char *name, int value)
\& {
\&   (void)class_name;
\&   foo_t *self = malloc( sizeof( foo_t ) );
\&   self\->name = strdup(name);
\&   self\->value = value;
\&   return self;
\& }
\& 
\& const char *
\& foo_\|_name(foo_t *self)
\& {
\&   return self\->name;
\& }
\& 
\& int
\& foo_\|_value(foo_t *self)
\& {
\&   return self\->value;
\& }
\& 
\& void
\& foo_\|_DESTROY(foo_t *self)
\& {
\&   free(self\->name);
\&   free(self);
\& }
.Ve
.PP
\&\f(CW\*(C`lib/Foo.pm\*(C'\fR:
.PP
.Vb 1
\& package Foo;
\& 
\& use strict;
\& use warnings;
\& use FFI::Platypus;
\& 
\& {
\&   my $ffi = FFI::Platypus\->new( api => 1 );
\& 
\&   $ffi\->type(\*(Aqobject(Foo)\*(Aq => \*(Aqfoo_t\*(Aq);
\&   $ffi\->mangler(sub {
\&     my $name = shift;
\&     $name =~ s/^/foo_\|_/;
\&     $name;
\&   });
\& 
\&   $ffi\->bundle;
\& 
\&   $ffi\->attach( new =>     [ \*(Aqstring\*(Aq, \*(Aqstring\*(Aq, \*(Aqint\*(Aq ] => \*(Aqfoo_t\*(Aq  );
\&   $ffi\->attach( name =>    [ \*(Aqfoo_t\*(Aq ]                   => \*(Aqstring\*(Aq );
\&   $ffi\->attach( value =>   [ \*(Aqfoo_t\*(Aq ]                   => \*(Aqint\*(Aq    );
\&   $ffi\->attach( DESTROY => [ \*(Aqfoo_t\*(Aq ]                   => \*(Aqvoid\*(Aq   );
\& }
\& 
\& 1;
.Ve
.PP
\&\f(CW\*(C`t/foo.t\*(C'\fR
.PP
.Vb 2
\& use Test::More;
\& use Foo;
\& 
\& my $foo = Foo\->new("platypus", 10);
\& isa_ok $foo, \*(AqFoo\*(Aq;
\& is $foo\->name, "platypus";
\& is $foo\->value, 10;
\& 
\& done_testing;
.Ve
.PP
\&\f(CW\*(C`Makefile.PL\*(C'\fR:
.PP
.Vb 11
\& use ExtUtils::MakeMaker;
\& use FFI::Build::MM;
\& my $fbmm = FFI::Build::MM\->new;
\& WriteMakefile(
\&   $fbmm\->mm_args(
\&     NAME     => \*(AqFoo\*(Aq,
\&     DISTNAME => \*(AqFoo\*(Aq,
\&     VERSION  => \*(Aq1.00\*(Aq,
\&     # ...
\&   )
\& );
\& 
\& sub MY::postamble
\& {
\&   $fbmm\->mm_postamble;
\& }
.Ve
.PP
or \f(CW\*(C`dist.ini\*(C'\fR:
.PP
.Vb 3
\& name    = Foo
\& version = 0.01
\& ...
\& 
\& [FFI::Build]
\& version = 1.04
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This document serves as a tutorial for using the new bundling interface provided
by FFI::Platypus as of api version 1.  It requires FFI::Platypus of at least
1.00.
.PP
Sometimes when writing \s-1FFI\s0 bindings you need to include a little C code (or your
favorite compiled language) to finish things off.  Alternatively, you might just
want to write some C code (or your favorite compiled language) to include with your
Perl module to make a tight loop faster.  The bundling interface has you covered.
.SS "Basic example"
.IX Subsection "Basic example"
To illustrate we will go through the files in the synopsis and explain
how and why they work.  To start with we have some C code which emulates object
oriented code using \f(CW\*(C`foo_\|_\*(C'\fR as a prefix.  We use a C struct that we call
\&\f(CW\*(C`foo_t\*(C'\fR to store our object data.  On the C level the struct acts as a class,
when combined with its functions that act as methods.  The constructor just
allocates the memory it needs for the \f(CW\*(C`foo_t\*(C'\fR instance, fills in the
appropriate fields and returns the pointer:
.PP
.Vb 9
\& foo_t*
\& foo_\|_new(const char *class_name, const char *name, int value)
\& {
\&   (void) class_name;
\&   foo_t *self = malloc( sizeof( foo_t ) );
\&   self\->name = strdup(name);
\&   self\->value = value;
\&   return self;
\& }
.Ve
.PP
We include a class name as the first argument, because Perl will include that
when calling the constructor, but we do not use it here.  An exercise for the
reader would be to add hierarchical inheritance.
.PP
There are also some methods which return member values.  This class has only
read only members, but you could have read/write or other methods depending
on your needs.
.PP
.Vb 5
\& const char *
\& foo_\|_name(foo_t *self)
\& {
\&   return self\->name;
\& }
.Ve
.PP
We also include a destructor so that the memory owned by the object can be
freed when it is no longer needed.
.PP
.Vb 6
\& void
\& foo_\|_DESTROY(foo_t *self)
\& {
\&   free(self\->name);
\&   free(self);
\& }
.Ve
.PP
This might start to look a little like a Perl module, and when we look at the Perl
code that binds to this code, you will see why.  First lets prepare the
FFI::Platypus instance and specify the correct api version:
.PP
.Vb 1
\& my $ffi = FFI::Platypus\->new( api => 1 );
.Ve
.PP
The bundle interface is only supported with api version 1, so if you try to use
version 0 it will not work.  Next we define an object type for \f(CW\*(C`foo_t\*(C'\fR which will
associate it with the Perl class \f(CW\*(C`Foo\*(C'\fR.
.PP
.Vb 1
\& $ffi\->type(\*(Aqobject(Foo)\*(Aq => \*(Aqfoo_t\*(Aq);
.Ve
.PP
As object type is a blessed reference to an opaque (default) or integer type which
can be used as a Perl object.  Platypus does the translating of Perl object to and
from the foo_t pointers that the C code understands.  For more details on Platypus
types see FFI::Platypus::Type.
.PP
Next we set the mangler on the Platypus instance so that we can refer to function
names without the \f(CW\*(C`foo_\|_\*(C'\fR prefix.  You could just not use the prefix in your C
code and skip this step, or you could refer to the function names in their full
in your Perl code, however, this saves extra typing and allows you to bundle more
than one class with your Perl code without having to worry about name conflicts.
.PP
.Vb 5
\& $ffi\->mangler(sub {
\&   my $name = shift;
\&   $name =~ s/^/foo_\|_/;
\&   $name;
\& });
.Ve
.PP
Finally we let Platypus know that we will be bundling code.
.PP
.Vb 1
\& $ffi\->bundle;
.Ve
.PP
By default, this searches for the appropriate place for your dynamic libraries using
the current package.  In some cases you may need to override this, for example if your
dist is named \f(CW\*(C`Foo\-Bar\*(C'\fR but your specific class is named \f(CW\*(C`Foo::Bar::Baz\*(C'\fR, you'd
want something like this:
.PP
.Vb 5
\& package Foo::Bar::Baz;
\& use FFI::Platypus;
\& my $ffi = FFI::Platypus\->new( api => 1 );
\& $ffi\->bundle(\*(AqFoo::Bar\*(Aq);
\& ...
.Ve
.PP
Now, finally we can attach the methods for our class:
.PP
.Vb 4
\& $ffi\->attach( new =>     [ \*(Aqstring\*(Aq, \*(Aqint\*(Aq ] => \*(Aqfoo_t\*(Aq  );
\& $ffi\->attach( name =>    [ \*(Aqfoo_t\*(Aq ]         => \*(Aqstring\*(Aq );
\& $ffi\->attach( value =>   [ \*(Aqfoo_t\*(Aq ]         => \*(Aqint\*(Aq    );
\& $ffi\->attach( DESTROY => [ \*(Aqfoo_t\*(Aq ]         => \*(Aqvoid\*(Aq   );
.Ve
.PP
Note that we do not have to include the \f(CW\*(C`foo_\|_\*(C'\fR prefix because of the way we set up
the mangler.  If we hadn't done that then we could instead attach with the full names:
.PP
.Vb 3
\& $ffi\->attach( [ \*(Aqfoo_\|_new\*(Aq  => \*(Aqnew\*(Aq ]  => [ \*(Aqstring\*(Aq, \*(Aqint\*(Aq ] => \*(Aqfoo_t\*(Aq  );
\& $ffi\->attach( [ \*(Aqfoo_\|_name\*(Aq => \*(Aqname\*(Aq ] => [ \*(Aqfoo_t\*(Aq ]         => \*(Aqstring\*(Aq );
\& ...
.Ve
.PP
You're done!  You can now use this class.  Lets write a test to make sure it works,
.PP
.Vb 4
\& use strict;
\& use warnings;
\& use Test::More;
\& use Foo;
\& 
\& my $foo = Foo\->new("platypus", 10);
\& isa_ok $foo, \*(AqFoo\*(Aq;
\& is $foo\->name, "platypus";
\& is $foo\->value, 10;
\& 
\& done_testing;
.Ve
.PP
and use \f(CW\*(C`prove\*(C'\fR to check that it works:
.PP
.Vb 10
\& % prove \-lvm
\& t/foo.t ..
\& ok 1 \- An object of class \*(AqFoo\*(Aq isa \*(AqFoo\*(Aq
\& ok 2
\& ok 3
\& 1..3
\& ok
\& All tests successful.
\& Files=1, Tests=3,  0 wallclock secs ( 0.02 usr  0.00 sys +  0.14 cusr  0.03 csys =  0.19 CPU)
\& Result: PASS
.Ve
.PP
Platypus automatically compiles and links the dynamic library for you:
.PP
.Vb 2
\& % ls ffi/_build
\& foo.c.o  libFoo.so
.Ve
.PP
The C code will be rebuilt next time if the source code is newer than the object or dynamic libraries
files.  If the source files are not changed, then it won't be rebuilt to save time.  If you are using
the code without MakeMaker, or another build system you are responsible for cleaning up these files.
This is intended as a convenience to allow you to test your code without having to invoke MakeMaker,
or \f(CW\*(C`dzil\*(C'\fR or whatever build system you are using.
.PP
When you distribute your module though, you will want the dynamic library built just once
at build-time and installed correctly so that it can be found at run-time.  You don't need
to make any changes to your C or Perl code, but you do need to tell MakeMaker to build and
install the appropriate files using FFI::Build::MM:
.PP
.Vb 11
\& use ExtUtils::MakeMaker;
\& use FFI::Build::MM;
\& my $fbmm = FFI::Build::MM\->new;
\& WriteMakefile(
\&   $fbmm\->mm_args(
\&     NAME     => \*(AqFoo\*(Aq,
\&     DISTNAME => \*(AqFoo\*(Aq,
\&     VERSION  => \*(Aq1.00\*(Aq,
\&     # ...
\&   )
\& );
\& 
\& sub MY::postamble
\& {
\&   $fbmm\->mm_postamble;
\& }
.Ve
.PP
And we can invoke all the normal MakeMaker style stuff and our C code will be compiled, linked
and installed at the appropriate steps.
.PP
.Vb 10
\& % perl Makefile.PL
\& Generating a Unix\-style Makefile
\& Writing Makefile for Foo
\& Writing MYMETA.yml and MYMETA.json
\& % make
\& cp lib/Foo.pm blib/lib/Foo.pm
\& "/Users/ollisg/perl5/perlbrew/perls/perl\-5.30.0/bin/perl" \-MFFI::Build::MM=cmd \-e fbx_build
\& CC ffi/foo.c
\& LD blib/lib/auto/share/dist/Foo/lib/libFoo.dylib
\& % make test
\& "/Users/ollisg/perl5/perlbrew/perls/perl\-5.30.0/bin/perl" \-MFFI::Build::MM=cmd \-e fbx_build
\& "/Users/ollisg/perl5/perlbrew/perls/perl\-5.30.0/bin/perl" \-MFFI::Build::MM=cmd \-e fbx_test
\& PERL_DL_NONLAZY=1 "/Users/ollisg/perl5/perlbrew/perls/perl\-5.30.0/bin/perl" "\-MExtUtils::Command::MM" "\-MTest::Harness" "\-e" "undef *Test::Harness::Switches; test_harness(0, \*(Aqblib/lib\*(Aq, \*(Aqblib/arch\*(Aq)" t/*.t
\& t/foo.t .. ok
\& All tests successful.
\& Files=1, Tests=3,  0 wallclock secs ( 0.01 usr  0.00 sys +  0.06 cusr  0.01 csys =  0.08 CPU)
\& Result: PASS
.Ve
.PP
If the \f(CW\*(C`Makefile.PL\*(C'\fR file above looks overly complicated, you can use the
Dist::Zilla::Plugin::FFI::Build plugin to simplify your life if you are
using Dist::Zilla:
.PP
.Vb 2
\& [FFI::Build]
\& version = 1.04
.Ve
.PP
Specifying version 1.04 will ensure that any \f(CW\*(C`.o\*(C'\fR or \f(CW\*(C`.so\*(C'\fR files are pruned
from your build tree and not distributed by mistake.
.SS "Initialization example"
.IX Subsection "Initialization example"
The bundle interface also gives you entry points which will be called automatically
when your code is loaded and unloaded if they are found.
.ie n .IP """ffi_pl_bundle_init""" 4
.el .IP "\f(CWffi_pl_bundle_init\fR" 4
.IX Item "ffi_pl_bundle_init"
.Vb 1
\& void ffi_pl_bundle_init(const char *package, int argc, void *argv[]);
.Ve
.Sp
Called when the dynamic library is loaded.  \f(CW\*(C`package\*(C'\fR is the Perl package
that called \f(CW\*(C`bundle\*(C'\fR from Perl space.  \f(CW\*(C`argc\*(C'\fR and \f(CW\*(C`argv\*(C'\fR represents an
array of opaque pointers that can be passed as an array to bundle as the
last argument.  (the count \f(CW\*(C`argc\*(C'\fR is a little redundant because \f(CW\*(C`argv\*(C'\fR
is also \s-1NULL\s0 terminated).
.ie n .IP """ffi_pl_bundle_constant""" 4
.el .IP "\f(CWffi_pl_bundle_constant\fR" 4
.IX Item "ffi_pl_bundle_constant"
.Vb 1
\& void ffi_pl_bundle_constant(const char *package, ffi_platypus_constant_t *c);
.Ve
.Sp
Called immediately after \f(CW\*(C`ffi_pl_bundle_init\*(C'\fR, and is intended to allow
you to set Perl constants from C space.  For details on how this works
and what methods you can call on the \f(CW\*(C`ffi_platypus_constant_t\*(C'\fR instance,
see FFI::Platypus::Constant.
.ie n .IP """ffi_pl_bundle_fini""" 4
.el .IP "\f(CWffi_pl_bundle_fini\fR" 4
.IX Item "ffi_pl_bundle_fini"
.Vb 1
\& void ffi_pl_bundle_fini(const char *package);
.Ve
.Sp
Called when the dynamic library is unloaded.  \f(CW\*(C`package\*(C'\fR is the Perl
package that called \f(CW\*(C`bundle\*(C'\fR from Perl space when the library was
loaded.  \fB\s-1CAVEAT\s0\fR: if you attach any functions then this will
never be called, because attaching functions locks the Platypus
instance into memory along with the libraries which it is using.
.PP
Here is an example that passes the version and a callback back into Perl
space that emulates the Perl 5.10 \f(CW\*(C`say\*(C'\fR feature.
.PP
\&\f(CW\*(C`ffi/init.c\*(C'\fR:
.PP
.Vb 1
\& #include <ffi_platypus_bundle.h>
\& 
\& char buffer[512];
\& const char *version;
\& void (*say)(const char *);
\& 
\& void
\& ffi_pl_bundle_init(const char *package, int argc, void *argv[])
\& {
\&   version = argv[0];
\&   say     = argv[1];
\& 
\&   say("in init!");
\& 
\&   snprintf(buffer, 512, "package = %s, version = %s", package, version);
\&   say(buffer);
\& 
\&   snprintf(buffer, 512, "args = %d", argc);
\&   say(buffer);
\& }
\& 
\& void
\& ffi_pl_bundle_fini(const char *package)
\& {
\&   say("in fini!");
\& }
.Ve
.PP
\&\f(CW\*(C`lib/Init.pm\*(C'\fR:
.PP
.Vb 1
\& package Init;
\& 
\& use strict;
\& use warnings;
\& use FFI::Platypus;
\& 
\& our $VERSION = \*(Aq1.00\*(Aq;
\& 
\& {
\&   my $ffi = FFI::Platypus\->new( api => 1 );
\& 
\&   my $say = $ffi\->closure(sub {
\&     my $string = shift;
\&     print "$string\en";
\&   });
\& 
\&   $ffi\->bundle([
\&     $ffi\->cast( \*(Aqstring\*(Aq => \*(Aqopaque\*(Aq, $VERSION ),
\&     $ffi\->cast( \*(Aq(string)\->void\*(Aq => \*(Aqopaque\*(Aq, $say ),
\&   ]);
\& 
\&   undef $ffi;
\&   undef $say;
\& }
\& 
\& 1;
.Ve
.PP
The deinitialization order for the \f(CW$say\fR callback and the \f(CW$ffi\fR
instance is essential here, so we do it manually with \f(CW\*(C`undef\*(C'\fR:
.PP
.Vb 2
\& undef $ffi;
\& undef $say;
.Ve
.PP
First we deallocate \f(CW$ffi\fR which calls \f(CW\*(C`ffi_pl_bundle_fini\*(C'\fR,
which calls \f(CW$say\fR, so we want to make sure the latter is still
allocated.  Once \f(CW\*(C`ffi_pl_bundle_fini\*(C'\fR is done, we can safely
deallocate \f(CW$say\fR.
.PP
If \f(CW\*(C`ffi_pl_bundle_fini\*(C'\fR didn't call back into Perl space like
this then we don't have to be as careful about deallocating
things in Perl space.
.SH "AUTHOR"
.IX Header "AUTHOR"
Author: Graham Ollis <plicease@cpan.org>
.PP
Contributors:
.PP
Bakkiaraj Murugesan (bakkiaraj)
.PP
Dylan Cali (calid)
.PP
pipcet
.PP
Zaki Mughal (zmughal)
.PP
Fitz Elliott (felliott)
.PP
Vickenty Fesunov (vyf)
.PP
Gregor Herrmann (gregoa)
.PP
Shlomi Fish (shlomif)
.PP
Damyan Ivanov
.PP
Ilya Pavlov (Ilya33)
.PP
Petr Pisar (ppisar)
.PP
Mohammad S Anwar (\s-1MANWAR\s0)
.PP
Håkon Hægland (hakonhagland, \s-1HAKONH\s0)
.PP
Meredith (merrilymeredith, \s-1MHOWARD\s0)
.PP
Diab Jerius (\s-1DJERIUS\s0)
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
This software is copyright (c) 2015,2016,2017,2018,2019,2020 by Graham Ollis.
.PP
This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.