File Coverage

blib/lib/FFI/Platypus/Lang/Rust.pm
Criterion Covered Total %
statement 24 24 100.0
branch n/a
condition n/a
subroutine 7 7 100.0
pod 1 1 100.0
total 32 32 100.0


line stmt bran cond sub pod time code
1             package FFI::Platypus::Lang::Rust;
2              
3 3     3   24812 use strict;
  3         7  
  3         82  
4 3     3   16 use warnings;
  3         5  
  3         105  
5 3     3   15 use File::Glob qw( bsd_glob );
  3         5  
  3         359  
6 3     3   2334 use File::Which qw( which );
  3         2842  
  3         158  
7 3     3   16 use File::Spec;
  3         6  
  3         112  
8 3     3   3655 use Env qw( @PATH );
  3         9164  
  3         18  
9              
10             our $VERSION = '0.04';
11              
12             =head1 NAME
13              
14             FFI::Platypus::Lang::Rust - Documentation and tools for using Platypus with
15             the Rust programming language
16              
17             =head1 SYNOPSIS
18              
19             Rust:
20              
21             #![crate_type = "dylib"]
22            
23             // compile with: rustc add.rs
24            
25             #[no_mangle]
26             pub extern "C" fn add(a:i32, b:i32) -> i32 {
27             a+b
28             }
29              
30             Perl:
31              
32             use FFI::Platypus;
33             my $ffi = FFI::Platypus->new;
34             $ffi->lang('Rust');
35             $ffi->lib('./libadd.so');
36            
37             $ffi->attach( add => ['i32', 'i32'] => 'i32' );
38            
39             print add(1,2), "\n"; # prints 3
40              
41             =head1 DESCRIPTION
42              
43             This module provides native Rust types for L in order to
44             reduce cognitive load and concentrate on Rust and forget about C types.
45             This document also documents issues and caveats that I have discovered
46             in my attempts to work with Rust and FFI.
47              
48             This module is somewhat experimental. It is also available for adoption
49             for anyone either sufficiently knowledgable about Rust or eager enough
50             to learn enough about Rust. If you are interested, please send me a
51             pull request or two on the project's GitHub.
52              
53             Note that in addition to using pre-compiled Rust libraries, you can
54             bundle Rust code with your Perl distribution using
55             L.
56              
57             =head1 CAVEATS
58              
59             In doing my testing I have been using the pre-release 1.0.0 Alpha
60             version of Rust. Rust is a very fast moving target! I have rarely
61             found examples on the internet that still work by the time I get around
62             to trying them. Fast times. Hopefully when it becomes stable things
63             will change.
64              
65             =head2 name mangling
66              
67             Rust names are "mangled" to handle features such as modules and the fact
68             that some characters in Rust names are illegal machine code symbol
69             names. For now that means that you have to tell Rust not to mangle the
70             names of functions that you are going to call from Perl. You can
71             accomplish that lke this:
72              
73             #[no_mangle]
74             pub extern "C" fn foo() {
75             }
76              
77             You do not need to add this decoration to functions that you do not
78             directly call from Perl. For example:
79              
80             fn bar() {
81             }
82            
83             #[no_mangle]
84             pub extern "C" fn foo() {
85             bar();
86             }
87              
88             In the future we may add support for name mangling so that you can use
89             the Rust names, as we attempt to do for L.
90             In fact we may be able to use the same technique, as it appears that
91             Rust uses the same mangling format.
92              
93             =head1 METHODS
94              
95             Generally you will not use this class directly, instead interacting with
96             the L instance. However, the public methods used by
97             Platypus are documented here.
98              
99             =head2 native_type_map
100              
101             my $hashref = FFI::Platypus::Lang::Rust->native_type_map;
102              
103             This returns a hash reference containing the native aliases for the Rust
104             programming languages. That is the keys are native Rust types and the
105             values are libffi native types.
106              
107             =cut
108              
109             sub native_type_map
110             {
111 16     16 1 1345 require FFI::Platypus;
112             {
113             u8 => 'uint8',
114             u16 => 'uint16',
115             u32 => 'uint32',
116             u64 => 'uint64',
117             i8 => 'sint8',
118             i16 => 'sint16',
119             i32 => 'sint32',
120             i64 => 'sint64',
121             binary32 => 'float', # need to check this is right
122             binary64 => 'double', # " " " " " "
123             f32 => 'float',
124             f64 => 'double',
125 16         48 usize => do { FFI::Platypus->type_meta('size_t')->{ffi_type} },
126 16         5979 isize => do {
127 16         16246 my $ffi_type = FFI::Platypus->type_meta('size_t')->{ffi_type};
128 16         10184 $ffi_type =~ s{^u}{s};
129 16         146 $ffi_type;
130             },
131             },
132             }
133              
134             1;
135              
136             =head1 EXAMPLES
137              
138             See the above L or the C directory that came with
139             this distribution.
140              
141             =head1 SUPPORT
142              
143             If something does not work as advertised, or the way that you think it
144             should, or if you have a feature request, please open an issue on this
145             project's GitHub issue tracker:
146              
147             L
148              
149             =head1 CONTRIBUTING
150              
151             If you have implemented a new feature or fixed a bug then you may make a
152             pull reequest on this project's GitHub repository:
153              
154             L
155              
156             Caution: if you do this too frequently I may nominate you as the new
157             maintainer. Extreme caution: if you like that sort of thing.
158              
159             This project's GitHub issue tracker listed above is not Write-Only. If
160             you want to contribute then feel free to browse through the existing
161             issues and see if there is something you feel you might be good at and
162             take a whack at the problem. I frequently open issues myself that I
163             hope will be accomplished by someone in the future but do not have time
164             to immediately implement myself.
165              
166             Another good area to help out in is documentation. I try to make sure
167             that there is good document coverage, that is there should be
168             documentation describing all the public features and warnings about
169             common pitfalls, but an outsider's or alternate view point on such
170             things would be welcome; if you see something confusing or lacks
171             sufficient detail I encourage documentation only pull requests to
172             improve things.
173              
174             =head1 SEE ALSO
175              
176             =over 4
177              
178             =item L
179              
180             The Core Platypus documentation.
181              
182             =item L
183              
184             Bundle Rust code with your FFI / Perl extension.
185              
186             =back
187              
188             =head1 AUTHOR
189              
190             Graham Ollis Eplicease@cpan.orgE
191              
192             =head1 COPYRIGHT AND LICENSE
193              
194             This software is copyright (c) 2015 by Graham Ollis.
195              
196             This is free software; you can redistribute it and/or modify it under
197             the same terms as the Perl 5 programming language system itself.
198              
199             =cut
200