NAME

FFI::Build::File::Cargo

VERSION

version 0.17

SYNOPSIS

Crete a rust project in the "ffi" directory that produces a dynamic library:

 $ cargo new --lib --name my_lib ffi
       Created library `my_lib` package

Add this to your "ffi/Cargo.toml" file to get dynamic libraries:

 [lib]
 crate-type = ["cdylib"]

Add Rust code to "ffi/src/lib.rs" that you want to call from Perl:

 #![crate_type = "cdylib"]
 
 #[no_mangle]
 pub extern "C" fn add(a: i32, b: i32) -> i32 {
     a + b
 }

Your Perl bindings go in a ".pm" file like "lib/MyLib.pm":

 package MyLib;
 
 use FFI::Platypus 2.00;
 
 my $ffi = FFI::Platypus->new( api => 2, lang => 'Rust' );
 # configure platypus to use the bundled Rust code
 $ffi->bundle;
 
 $ffi->attach( 'add' => ['i32','i32'] => 'i32' );

Your "Makefile.PL":

 use ExtUtils::MakeMaker;
 use FFI::Build::MM;
 
 my $fbmm = FFI::Build::MM->new;
 
 WriteMakefile($fbmm->mm_args(
     ABSTRACT       => 'My Lib',
     DISTNAME       => 'MyLib',
     NAME           => 'MyLib',
     VERSION_FROM   => 'lib/MyLib.pm',
     BUILD_REQUIRES => {
         'FFI::Build::MM'          => '1.00',
         'FFI::Build::File::Cargo' => '0.07',
     },
     PREREQ_PM => {
         'FFI::Platypus'             => '1.00',
         'FFI::Platypus::Lang::Rust' => '0.07',
     },
 ));
 
 sub MY::postamble {
     $fbmm->mm_postamble;
 }

or alternatively, your "dist.ini":

 [FFI::Build]
 lang = Rust
 build = Cargo

Write a test:

 use Test2::V0;
 use MyLib;
 
 is MyLib::add(1,2), 3;
 
 done_testing;

DESCRIPTION

This module provides the necessary machinery to bundle rust code with your Perl extension. It uses FFI::Build and "cargo" to do the heavy lifting.

A complete example comes with this distribution in the "examples/Person" directory, including tests. You can browse this example on the web here:

<https://github.com/PerlFFI/FFI-Platypus-Lang-Rust/tree/main/examples/Person>

The distribution that follows the pattern above works just like a regular Pure-Perl or XS distribution, except:

make: Running the "make" step builds the Rust library as a dynamic library using cargo, and runs the crate's tests if any are available. It then moves the resulting dynamic library in to the appropriate location in "blib" so that it can be found at test and runtime.
prove: If you run the tests using "prove -l" (that is, without building the distribution), Platypus will find the rust crate in the "ffi" directory, build that and use it on the fly. This makes it easier to test your distribution with less explicit building.

This module is smart enough to check the timestamps on the appropriate files so the library won't need to be rebuilt if the source files haven't changed.

For more details using Perl + Rust with FFI, see FFI::Platypus::Lang::Rust.

ENVIRONMENT

"PERL_FFI_CARGO_FLAGS"

This environment variable changes the flags that are passed into "cargo test" and "cargo build".

By default this module passes "--release" into both "cargo test" and "cargo build". It does this so that you will get optimized libraries when your Perl extension is installed. You may require a different profile when testing so you can, for example, set this environment variable to something else:

 $ export PERL_FFI_CARGO_FLAGS='--profile test'
 $ ...

AUTHOR

Author: Graham Ollis <plicease@cpan.org>

Contributors:

Andrew Grangaard (SPAZM)

COPYRIGHT AND LICENSE

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.