Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 112 lines (80 sloc) 4.12 kb
4b34bad @jnthn Turn README into Markdown; start to improve things.
authored
1 # Zavolaj!
2
3 This module implements native calling support for Rakudo Perl 6. It builds
4 on a set of native calling primitives in NQP, adding mapping of Perl 6
5 signatures and various other traits to make working with native libraries
6 an easier experience.
7
8 The project name is the Slovak translation of the imperative "call!", to
9 complement Blizkost, a Rakudo-to-Perl-5 integration project.
10
11 Thanks to NQP's underlying use of the dyncall library, Zavolaj can now
12 support arbitrary signatures.
13
14 ## Getting Started
15 The simplest imaginable use of Zavolaj would look something like this:
16
17 use NativeCall;
18 sub some_argless_function() is native('libsomething') { * }
19 some_argless_function();
20
21 The first line imports various traits and types. The next line looks like
22 a relatively ordinary Perl 6 sub declaration - with a twist. We use the
23 "native" trait in order to specify that the sub is actually defined in a
24 native library. The platform-specific extension (e.g. .so or .dll) will be
25 added for you.
26
27 The first time you call "some_argless_function", the "libsomething" will be
28 loaded and the "some_argless_function" will be located in it. A call will then
29 be made. Subsequent calls will be faster, since the symbol handle is retained.
30
31 Of course, most functions take arguments or return values - but everything else
32 that you can do is just adding to this simple pattern of declaring a Perl 6
33 sub, naming it after the symbol you want to call and marking it with the "native"
34 trait.
35
36 ## Passing and Returning Values
37 Normal Perl 6 signatures and the "returns" trait are used in order to convey
38 the type of arguments a native function expects and what it returns. Here is
39 an example.
40
41 sub add(int32, int32) returns int32 is native("libcalculator") { * }
42
43 Here, we have declared that the function takes two 32-bit integers and returns
44 a 32-bit integer. Here are some of the other types that you may pass (this will
45 likely grow with time).
46
47 int8 (char in C)
48 int16 (short in C)
49 int32 (int in C)
50 int (32- or 64-bit, depends what long means locally)
51 Int (always 64-bit, long long in C)
52 num32 (float in C)
53 num64 (double in C)
54 num (same as num64)
55 Str (C string)
56
57 Note that the lack of a "returns" trait is used to indicate void return type.
58
59 For strings, there is an additional "encoded" trait to give some extra hints on
60 how to do the marshalling.
61
62 sub message_box(Str is encoded('utf8')) is native('libgui') { * }
63
64 To specify how to marshall string return types, just apply this trait to the
65 routine itself.
66
67 sub input_box() returns Str is encoded('utf8') is native('libgui') { * }
68
69
70 ## Running the Examples
71
72 The examples directory contains various examples of how to use Zavolaj.
73
74 ### MySQL
75
76 There is an exmaple of using the MySQL client library. There is a Rakudo project
77 http://github.com/mberends/minidbi that wraps these functions with a DBI
78 compatible interface. You'll need that library to hand; on Debian-esque systems
79 it can be installed with something like:
80
81 sudo apt-get install libmysqlclient-dev
82
83 Prepare your system along these lines before trying out the examples:
84
85 $ mysql -u root -p
86 CREATE DATABASE zavolaj;
87 CREATE USER 'testuser'@'localhost' IDENTIFIED BY 'testpass';
88 GRANT CREATE ON zavolaj.* TO 'testuser'@'localhost';
89 GRANT DROP ON zavolaj.* TO 'testuser'@'localhost';
90 GRANT INSERT ON zavolaj.* TO 'testuser'@'localhost';
91 GRANT DELETET ON zavolaj.* TO 'testuser'@'localhost';
92 GRANT SELECT ON zavolaj.* TO 'testuser'@'localhost';
93 GRANT LOCK TABLES ON zavolaj.* TO 'testuser'@'localhost';
94 GRANT SELECT ON mysql.* TO 'testuser'@'localhost';
95 # or maybe otherwise
96 GRANT ALL PRIVILEGES ON zavolaj.* TO 'testuser'@'localhost';
97
98 You can look at the results via a normal mysql connection:
99
100 $ mysql -utestuser -ptestpass
101 USE zavolaj;
102 SHOW TABLES;
103 SELECT * FROM nom;
104
105 ## SQLite3
106
107 May not be working...let us know if you get success!
108
109 ## Microsoft Windows
110
111 The win32-api-call.p6 script shows a Windows API call done from Perl 6.
Something went wrong with that request. Please try again.