Skip to content
Newer
Older
100644 147 lines (105 sloc) 5.45 KB
4b34bad @jnthn Turn README into Markdown; start to improve things.
authored Jan 15, 2012
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
81ff0e4 @jnthn Document working with pointers.
authored Jan 15, 2012
70 ## Opaque Pointers
71 Sometimes you need to get a pointer (for example, a library handle) back from a
72 C library. You don't care about what it points to - you just need to keep hold
73 of it. The OpaquePointer type provides for this.
74
75 sub Foo_init() returns OpaquePointer is native("libfoo") { * }
76 sub Foo_free(OpaquePointer) is native("libfoo") { * }
77
78 This works out OK, but you may fancy working with a type named something better
79 than OpaquePointer. It turns out that any class with the representation "CPointer"
80 can serve this role. This means you can expose libraries that work on handles
81 by writing a class like this:
82
83 class FooHandle is repr('CPointer') {
84 # Here are the actual Zavolaj functions.
85 sub Foo_init() returns FooPointer is native("libfoo") { * }
86 sub Foo_free(FooPointer) is native("libfoo") { * }
87
88 # Here are the methods we use to expose it to the outside world.
89 method new() { Foo_init() }
90 method free() { Foo_free(self) }
91 }
92
93 Note that the CPointer representation can do nothing more than hold a C pointer.
94 This means that your class cannot have extra attributes. However, for simple
95 libraries this may be a neat way to expose an object oriented interface to it.
96
97 Of course, you can always have an empty class:
98
99 class DoorHandle is repr('CPointer') { }
100
101 And just use the class as you would use OpaquePointer, but with potential for
102 better type safety and more readable code.
103
104
4b34bad @jnthn Turn README into Markdown; start to improve things.
authored Jan 14, 2012
105 ## Running the Examples
106
107 The examples directory contains various examples of how to use Zavolaj.
108
109 ### MySQL
110
111 There is an exmaple of using the MySQL client library. There is a Rakudo project
112 http://github.com/mberends/minidbi that wraps these functions with a DBI
113 compatible interface. You'll need that library to hand; on Debian-esque systems
114 it can be installed with something like:
115
116 sudo apt-get install libmysqlclient-dev
117
118 Prepare your system along these lines before trying out the examples:
119
120 $ mysql -u root -p
121 CREATE DATABASE zavolaj;
122 CREATE USER 'testuser'@'localhost' IDENTIFIED BY 'testpass';
123 GRANT CREATE ON zavolaj.* TO 'testuser'@'localhost';
124 GRANT DROP ON zavolaj.* TO 'testuser'@'localhost';
125 GRANT INSERT ON zavolaj.* TO 'testuser'@'localhost';
126 GRANT DELETET ON zavolaj.* TO 'testuser'@'localhost';
127 GRANT SELECT ON zavolaj.* TO 'testuser'@'localhost';
128 GRANT LOCK TABLES ON zavolaj.* TO 'testuser'@'localhost';
129 GRANT SELECT ON mysql.* TO 'testuser'@'localhost';
130 # or maybe otherwise
131 GRANT ALL PRIVILEGES ON zavolaj.* TO 'testuser'@'localhost';
132
133 You can look at the results via a normal mysql connection:
134
135 $ mysql -utestuser -ptestpass
136 USE zavolaj;
137 SHOW TABLES;
138 SELECT * FROM nom;
139
140 ## SQLite3
141
142 May not be working...let us know if you get success!
143
144 ## Microsoft Windows
145
146 The win32-api-call.p6 script shows a Windows API call done from Perl 6.
Something went wrong with that request. Please try again.