Skip to content
This repository
Browse code

Turn README into Markdown; start to improve things.

  • Loading branch information...
commit 4b34badb5c8f23b28e99bdef6434c93cd0d38d9b 1 parent 26a91f4
Jonathan Worthington authored

Showing 2 changed files with 111 additions and 64 deletions. Show diff stats Hide diff stats

  1. +0 64 README
  2. +111 0 README.markdown
64 README
... ... @@ -1,64 +0,0 @@
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 for NQP's underlying use of the dyncall library, Zavolaj can now
12   -support arbitrary signatures.
13   -
14   -MySQL
15   -
16   -Initially the MySQL client library is being used as a test case, because
17   -it is a popular application, is frequently asked about, and because
18   -Parrot does have all the function signatures. There is a Rakudo project
19   -http://github.com/mberends/minidbi that wraps these functions with a DBI
20   -compatible interface.
21   -
22   -The /usr/include/mysql.h file defines the mysql client library functions
23   -and their parameters.
24   -
25   -Prepare your system along these lines before trying out the examples:
26   -
27   - $ mysql -u root -p
28   - CREATE DATABASE zavolaj;
29   - CREATE USER 'testuser'@'localhost' IDENTIFIED BY 'testpass';
30   - GRANT CREATE ON zavolaj.* TO 'testuser'@'localhost';
31   - GRANT DROP ON zavolaj.* TO 'testuser'@'localhost';
32   - GRANT INSERT ON zavolaj.* TO 'testuser'@'localhost';
33   - GRANT DELETET ON zavolaj.* TO 'testuser'@'localhost';
34   - GRANT SELECT ON zavolaj.* TO 'testuser'@'localhost';
35   - GRANT LOCK TABLES ON zavolaj.* TO 'testuser'@'localhost';
36   - GRANT SELECT ON mysql.* TO 'testuser'@'localhost';
37   - # or maybe otherwise
38   - GRANT ALL PRIVILEGES ON zavolaj.* TO 'testuser'@'localhost';
39   -
40   -You can look at the results via a normal mysql connection:
41   -
42   - $ mysql -utestuser -ptestpass
43   - USE zavolaj;
44   - SHOW TABLES;
45   - SELECT * FROM nom;
46   -
47   -SQLite3
48   -
49   -This library cannot be called yet because of missing Parrot NCI
50   -signatures, see the example file for details.
51   -
52   -Microsoft Windows
53   -
54   -The win32-api-call.p6 script shows the beginning of a GUI application
55   -written in Perl 6.
56   -
57   -Testing
58   -
59   -Before running 'make test', you *must* perform this:
60   -
61   - sudo apt-get install libmysqlclient-dev
62   - sudo apt-get install libtest-harness-perl
63   - export PERL6LIB=lib
64   -
111 README.markdown
Source Rendered
... ... @@ -0,0 +1,111 @@
  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.

0 comments on commit 4b34bad

Please sign in to comment.
Something went wrong with that request. Please try again.