Permalink
Browse files

Turn README into Markdown; start to improve things.

  • Loading branch information...
1 parent 26a91f4 commit 4b34badb5c8f23b28e99bdef6434c93cd0d38d9b @jnthn committed Jan 14, 2012
Showing with 111 additions and 64 deletions.
  1. +0 −64 README
  2. +111 −0 README.markdown
View
64 README
@@ -1,64 +0,0 @@
-Zavolaj!
-
-This module implements native calling support for Rakudo Perl 6. It builds
-on a set of native calling primitives in NQP, adding mapping of Perl 6
-signatures and various other traits to make working with native libraries
-an easier experience.
-
-The project name is the Slovak translation of the imperative "call!", to
-complement Blizkost, a Rakudo-to-Perl-5 integration project.
-
-Thanks for NQP's underlying use of the dyncall library, Zavolaj can now
-support arbitrary signatures.
-
-MySQL
-
-Initially the MySQL client library is being used as a test case, because
-it is a popular application, is frequently asked about, and because
-Parrot does have all the function signatures. There is a Rakudo project
-http://github.com/mberends/minidbi that wraps these functions with a DBI
-compatible interface.
-
-The /usr/include/mysql.h file defines the mysql client library functions
-and their parameters.
-
-Prepare your system along these lines before trying out the examples:
-
- $ mysql -u root -p
- CREATE DATABASE zavolaj;
- CREATE USER 'testuser'@'localhost' IDENTIFIED BY 'testpass';
- GRANT CREATE ON zavolaj.* TO 'testuser'@'localhost';
- GRANT DROP ON zavolaj.* TO 'testuser'@'localhost';
- GRANT INSERT ON zavolaj.* TO 'testuser'@'localhost';
- GRANT DELETET ON zavolaj.* TO 'testuser'@'localhost';
- GRANT SELECT ON zavolaj.* TO 'testuser'@'localhost';
- GRANT LOCK TABLES ON zavolaj.* TO 'testuser'@'localhost';
- GRANT SELECT ON mysql.* TO 'testuser'@'localhost';
- # or maybe otherwise
- GRANT ALL PRIVILEGES ON zavolaj.* TO 'testuser'@'localhost';
-
-You can look at the results via a normal mysql connection:
-
- $ mysql -utestuser -ptestpass
- USE zavolaj;
- SHOW TABLES;
- SELECT * FROM nom;
-
-SQLite3
-
-This library cannot be called yet because of missing Parrot NCI
-signatures, see the example file for details.
-
-Microsoft Windows
-
-The win32-api-call.p6 script shows the beginning of a GUI application
-written in Perl 6.
-
-Testing
-
-Before running 'make test', you *must* perform this:
-
- sudo apt-get install libmysqlclient-dev
- sudo apt-get install libtest-harness-perl
- export PERL6LIB=lib
-
View
111 README.markdown
@@ -0,0 +1,111 @@
+# Zavolaj!
+
+This module implements native calling support for Rakudo Perl 6. It builds
+on a set of native calling primitives in NQP, adding mapping of Perl 6
+signatures and various other traits to make working with native libraries
+an easier experience.
+
+The project name is the Slovak translation of the imperative "call!", to
+complement Blizkost, a Rakudo-to-Perl-5 integration project.
+
+Thanks to NQP's underlying use of the dyncall library, Zavolaj can now
+support arbitrary signatures.
+
+## Getting Started
+The simplest imaginable use of Zavolaj would look something like this:
+
+ use NativeCall;
+ sub some_argless_function() is native('libsomething') { * }
+ some_argless_function();
+
+The first line imports various traits and types. The next line looks like
+a relatively ordinary Perl 6 sub declaration - with a twist. We use the
+"native" trait in order to specify that the sub is actually defined in a
+native library. The platform-specific extension (e.g. .so or .dll) will be
+added for you.
+
+The first time you call "some_argless_function", the "libsomething" will be
+loaded and the "some_argless_function" will be located in it. A call will then
+be made. Subsequent calls will be faster, since the symbol handle is retained.
+
+Of course, most functions take arguments or return values - but everything else
+that you can do is just adding to this simple pattern of declaring a Perl 6
+sub, naming it after the symbol you want to call and marking it with the "native"
+trait.
+
+## Passing and Returning Values
+Normal Perl 6 signatures and the "returns" trait are used in order to convey
+the type of arguments a native function expects and what it returns. Here is
+an example.
+
+ sub add(int32, int32) returns int32 is native("libcalculator") { * }
+
+Here, we have declared that the function takes two 32-bit integers and returns
+a 32-bit integer. Here are some of the other types that you may pass (this will
+likely grow with time).
+
+ int8 (char in C)
+ int16 (short in C)
+ int32 (int in C)
+ int (32- or 64-bit, depends what long means locally)
+ Int (always 64-bit, long long in C)
+ num32 (float in C)
+ num64 (double in C)
+ num (same as num64)
+ Str (C string)
+
+Note that the lack of a "returns" trait is used to indicate void return type.
+
+For strings, there is an additional "encoded" trait to give some extra hints on
+how to do the marshalling.
+
+ sub message_box(Str is encoded('utf8')) is native('libgui') { * }
+
+To specify how to marshall string return types, just apply this trait to the
+routine itself.
+
+ sub input_box() returns Str is encoded('utf8') is native('libgui') { * }
+
+
+## Running the Examples
+
+The examples directory contains various examples of how to use Zavolaj.
+
+### MySQL
+
+There is an exmaple of using the MySQL client library. There is a Rakudo project
+http://github.com/mberends/minidbi that wraps these functions with a DBI
+compatible interface. You'll need that library to hand; on Debian-esque systems
+it can be installed with something like:
+
+ sudo apt-get install libmysqlclient-dev
+
+Prepare your system along these lines before trying out the examples:
+
+ $ mysql -u root -p
+ CREATE DATABASE zavolaj;
+ CREATE USER 'testuser'@'localhost' IDENTIFIED BY 'testpass';
+ GRANT CREATE ON zavolaj.* TO 'testuser'@'localhost';
+ GRANT DROP ON zavolaj.* TO 'testuser'@'localhost';
+ GRANT INSERT ON zavolaj.* TO 'testuser'@'localhost';
+ GRANT DELETET ON zavolaj.* TO 'testuser'@'localhost';
+ GRANT SELECT ON zavolaj.* TO 'testuser'@'localhost';
+ GRANT LOCK TABLES ON zavolaj.* TO 'testuser'@'localhost';
+ GRANT SELECT ON mysql.* TO 'testuser'@'localhost';
+ # or maybe otherwise
+ GRANT ALL PRIVILEGES ON zavolaj.* TO 'testuser'@'localhost';
+
+You can look at the results via a normal mysql connection:
+
+ $ mysql -utestuser -ptestpass
+ USE zavolaj;
+ SHOW TABLES;
+ SELECT * FROM nom;
+
+## SQLite3
+
+May not be working...let us know if you get success!
+
+## Microsoft Windows
+
+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.