Document using the FBX interface

[plicease]

The intent of this PR is to address #221

[plicease]

This new section in FFI::Platypus::Bundle on compiler flags renders like this, once all of the examples are inserted:

compiler or linker flags example

There are times when you will want to specify your own compiler and linker flags for the C code that you are bundling. The TL;DR is that you can put a .fbx file in your ffi directory. This is a Perl script that returns a hash reference that is passed into the FFI::Build constructor. This allows you to set a number of options, including compiler and linker flags. A more detailed example follows:

You may want or need to set compiler and linker flags for your bundled C code. For example, say we have a header file, but instead of putting it in the ffi directory we want to put it in a separate directory called include.

include/answer.h:

#ifndef ANSWER_H
#define ANSWER_H

int answer(void);

#endif

ffi/answer.c:

#include <answer.h>

int
answer(void)
{
  /* the answer to life the universe and everything */
  return 42;
}

lib/Answer.pm:

package Answer;

use strict;
use warnings;
use FFI::Platypus 1.00;
use base qw( Exporter );

our @EXPORT = qw( answer );

my $ffi = FFI::Platypus->new( api => 1 );
$ffi->bundle;
$ffi->attach( answer => [] => 'int' );

1;

If you try to use this module just as-is you will get an error, about not being able to find the header file. Probably something like this:

ffi/answer.c:1:10: fatal error: 'answer.h' file not found

So we put a answer.fbx file in the ffi directory. (In case you are wondering FBX stands for "Ffi Build and file eXtensions should whenever possible be three characters long"). The name of the file can be anything so long as it ends in .fbx, we just choose answer here because that is the name of the project.

ffi/answer.fbx:

our $DIR;

return {
  cflags => "-I/include",
  source => "$DIR/*.c",
}

The $DIR variable is provided by the builder code. It is the root of the distribution, and is helpful if you need a fully qualified path. In this case you could have also used ffi/*.c.

The script returns a hash reference which is passed into the FFI::Build constructor, so you can use any of the options supported by that class. Now we should be able to use our bundled module:

% perl -Ilib -MAnswer=answer -E 'say answer'
42

[plicease]

Here is the section on using with Alien:

Using bundled code with Alien.

A useful technique is to use Platypus with Alien technology. The Alien namespace is reserved for providing external non-Perl dependencies for CPAN modules. The nominal Alien module when installed looks for the library locally, and if it can't be found it fetches it from the internet, builds it, and installs it in a private directory so that it can be used by other CPAN modules. For Aliens that provide shared libraries, and that have simple interfaces that do not require additional C code you can easily just pass the shared libraries to Platypus directly. For modules that require some bundled C code and an Alien you have to link the Alien library with your bundled code. If the Alien uses the Alien::Base interface then all you have to do is give the name of the Alien to FFI::Build.

For example, the bzip2 librariy provides an interface that requires the caller to allocate a C struct and then pass it to its various functions. The struct is actually pretty simple and you could use FFI::C or FFI::Platypus::Record, but here is an example of how you would connect bundled C code with an Alien.

ffi/compress.c:

#include <bzlib.h>
#include <stdlib.h>

int
bzip2__new(bz_stream **stream, int blockSize100k, int verbosity, int workFactor )
{
  *stream = malloc(sizeof(bz_stream));
  (*stream)->bzalloc = NULL;
  (*stream)->bzfree  = NULL;
  (*stream)->opaque  = NULL;

  return BZ2_bzCompressInit(*stream, blockSize100k, verbosity, workFactor );
}

lib/Bzip2.pm:

package Bzip2;

use strict;
use warnings;
use FFI::Platypus 1.00;
use FFI::Platypus::Memory qw( free );

my $ffi = FFI::Platypus->new( api => 1 );
$ffi->bundle;

$ffi->mangler(sub {
  my $name = shift;
  $name =~ s/^/bzip2__/ unless $name =~ /^BZ2_/;
  $name;
});

=head2 new

 my $bzip2 = Bzip2->new($block_size_100k, $verbosity, $work_flow);

=cut

$ffi->attach( new => ['opaque*', 'int', 'int', 'int'] => 'int' => sub {
  my $xsub = shift;
  my $class = shift;
  my $ptr;
  my $ret = $xsub->(\$ptr, @_);
  return bless \$ptr, $class;
});

$ffi->attach( [ BZ2_bzCompressEnd => 'DESTROY' ] => ['opaque'] => 'int' => sub {
  my $xsub = shift;
  my $self = shift;
  my $ret = $xsub->($$self);
  free $$self;
});

1;

The .fbx file that goes with this to make it work with Alien::Libbz2 is now pretty trivial:

ffi/bz2.fbx:

{
  alien => ['Alien::Libbz2'],
  source => ['ffi/*.c'],
};