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.