<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html><head><title>GreenCard for nhc98</title></head>
<body bgcolor='#ffffff'>
<table><tr><td width=500>
<center><h1>GreenCard for nhc98</h1></center>
<hr>
<p>
<em>GreenCard</em> is a preprocessor for Haskell which allows Haskell
functions to call C. (For the really brave, <b>nhc98</b> also has the
ability to <a href="CcallingHaskell.html">call Haskell code from C</a>
using <em>GreenCard</em> to set up the interface.)
<p>
A paper (now superseded, see below) published in
the Haskell Workshop 97 proceedings describes the design goals, input
language, and translation mechanism. <em>GreenCard</em> was supposed
to be standard across implementations of Haskell - however the
<em>Hugs</em>/<em>ghc</em> version has now diverged somewhat.
A new, more flexible but lower-level, primitive FFI is now common
to <em>Hugs/ghc</em> and <em>nhc98</em>, and it provides a
greater degree of cross-compiler portability than <em>GreenCard</em>.
However, <em>GreenCard</em> is still useful for many small tasks, and
you may find it is just the right tool for your particular application.
<p>
Since the Haskell Workshop paper, several improvements have been
made to the input language and DIS macros. <em>GreenCard</em>
for <b>nhc98</b> follows the design agreed with the Glasgow and
Hugs implementors (although the Glasgow implementation does not!).
Here is <a href="greencard.html">the best extant description of
<em>GreenCard</em></a> closely matching the <b>nhc98</b> version.
<p>
There are just a few differences specific to the <b>nhc98</b> version
of the tool.
<dl>
<dt>Some features are not implemented.</dt>
<dd><tt>%fail</tt> is currently ignored
silently; <tt>%const</tt> generates a warning and terminates processing;
you cannot yet use named fields (sometimes known as records) in DIS
definitions.</dd>
<dt>Import clause needed.</dt>
<dd>The code generated by <em>GreenCard</em> uses certain library
functions, which may not be visible in the source submitted to
<em>GreenCard</em>. To make things easier, we have collected these
functions together into a single library module, which should always
be imported when you use <em>GreenCard</em>. Simply add the line
<pre>
import GreenCard
</pre>
to your source file. <em>GreenCard</em> cannot add this line for
you automatically.</dd>
<dt>Filename conventions.</dt>
<dd>Source files containing GreenCard directives should have a
<tt>.gc</tt> extension. Both <tt>nhc98</tt> and <tt>hmake</tt>
recognise the <tt>.gc</tt> extension and call <em>GreenCard</em>
automatically. When <em>GreenCard</em> is run on a file
<tt>Module.gc</tt> it generates two new files <tt>Module_.hs</tt>
and <tt>Module_.c</tt> which are processed separately by
<tt>nhc98</tt> proper and <tt>gcc</tt>. The end result however is
still a single object file called <tt>Module.o</tt>. (We thought it
would be useful to expose the generated files to the user, since
any compilation errors will refer to these rather than to the
original source (although of course the error must be fixed in the
original <tt>.gc</tt> file)).</dd>
<dt>Calling Haskell from C.</dt>
<dd>The Haskell Workshop paper said that "in practice there is zero demand"
for calling Haskell from C. We disagree. Using "stable pointers"
however, it is possible to go some distance towards providing such a
facility. See the document
<a href="CcallingHaskell.html">CcallingHaskell</a> and
file <tt>$NHC98DIR/lib/greencard.h</tt> for details.
<em>(Note: the newer <a href="ffi.html">primitive FFI</a> makes this
very much easier - we recommend you use it instead.)</em>
</dd>
<dt>DIS variable scope.</dt>
<dd>The original paper said: "All the C variables bound in the
%call statement, and all those bound in declarations at the start of
the body scope over all the result-marshalling statements (%result and
%fail)". However, it did not say anything about the scope of
variables bound by a %result statement. We say that variables bound
in a %result statement are always declared implicitly and scope over
the whole body. For example, from the paper:
<pre>
%fun foo :: (Age,Age) -> Age
%call (Age (int x), Age (int y))
%code r = foo(x,y);
%result (Age (int r))
</pre>
This example is correct, and indicates that the three variables x y and r
are all declared as "int"s prior to the %code body, and scope over the
body.
<pre>
%fun f :: This -> This
%call (MkThis (int p) (float q, float r))
%code int a,b,c;
% f( p, q, r, &a, &b, &c);
%result (this a b c)
</pre>
But this example is incorrect, because the user's definitions of a b and c
conflict with the automatic definition from the %result statement. (The
variables b and c are "float"s, but the user has tried to declare them as
"int"s.</dd>
</dl>
<hr>
<p>
The latest updates to these pages are available on the WWW from
<a href="http://www.haskell.org/nhc98/">
<tt>http://www.haskell.org/nhc98/</tt></a>
<p>
22 December 1999<br>
<a href="http://www.cs.york.ac.uk/fp/">
York Functional Programming Group</a><br>
</td></tr></table>
</body></html>
|
