From 25ee7c9eda18dbf3ccc37298dbba1f5fbbf64a30 Mon Sep 17 00:00:00 2001 From: chak Date: Wed, 21 Jun 2000 09:13:09 +0000 Subject: [PATCH] [project @ 2000-06-21 09:13:09 by chak] As suggested by SimonM, moved an overview over the three components of the FFI into the FFI document included as Chapter 7 into the GHC user guide. Open questions: * How can I make cross references to the doc in hslibs/? There are already references to hslibs sections in other parts of ghc's user guide, but they are not correctly resolved when I generate html from the sgml files. * There is now a (little) overlap with material in 6.5 (GHC Language Features: The foreign interface). I would say, we could actually leave this as it is, as 6.5 goes on to describe GHC specifics. --- docs/ffi.sgml | 80 +++++++++++++++++++++++++++++++++++++++++++++------------ 1 file changed, 64 insertions(+), 16 deletions(-) diff --git a/docs/ffi.sgml b/docs/ffi.sgml index 35e6d76..74fd348 100644 --- a/docs/ffi.sgml +++ b/docs/ffi.sgml @@ -3,28 +3,76 @@ -The motivation behind this foreign function interface(FFI) -specification is to make it possible to describe in Haskell source -code the interface to foreign functionality in a Haskell system -independent manner. It builds on experiences made with the previous -foreign function interfaces provided by GHC and Hugs. +The motivation behind this foreign function interface (FFI) specification is +to make it possible to describe in Haskell source code +the interface to foreign functionality in a Haskell system independent +manner. It builds on experiences made with the previous foreign function +interfaces provided by GHC and Hugs. However, the FFI specified in this +document is not in the market of trying to completely bridge the gap between +the actual type of an external function, and what is a +convenient type for that function to the Haskell +programmer. That is the domain of tools like HaskellDirect or Green Card, both +of which are capable of generating Haskell code that uses this FFI. -The FFI specified in this document is not in the market of trying to -completely bridge the gap between the actual type of an external -function, and what is a convenient type for that function to the -Haskell programmer. That is the domain of tools like HaskellDirect or -Green Card, both of which are capable of generating Haskell code that -uses this FFI. +Generally, the FFI consists of three parts: + + + + +extensions to the base language Haskell 98 (most notably foreign +import and foreign export declarations), which +are specified in the present document, + + + + + +a low-level marshalling library, which is part of the +Language part of the Haskell Extension +Library (see ), and a + + + + + +a high-level marshalling library, which is still under development. + + + + +Before diving into the details of the language extension coming with the FFI, +let us briefly outline the two other components of the interface. + + + +The low-level marshalling library consists of a portion that is independent of +the targeted foreign language and dedicated support for Haskell bindings to C +libraries (special support for other languages may be added in the future). +The language independent part is given by the module +Foreign module (see ). It +provides support for handling references to foreign structures, for passing +references to Haskell structures out to foreign routines, and for storing +primitive data types in raw memory blocks in a portable manner. The support +for C libraries essentially provides Haskell representations for all basic +types of C (see and ). + + + +The high-level library, of which the interface definition is not yet +finalised, provides routines for marshalling complex Haskell structures as +well as handling out and in-out parameters in a convenient, yet protable way. -The FFI can be split up into two complementary halves; one half that -provides Haskell constructs for importing foreign functionality into -Haskell, the other which lets you expose Haskell functions to the -outside world. We start with the former, how to import external -functionality into Haskell. +In the following, we will discuss the language extensions of the FFI (ie, the +first point above). They can be split up into two complementary halves; one +half that provides Haskell constructs for importing foreign functionality into +Haskell, the other which lets you expose Haskell functions to the outside +world. We start with the former, how to import external functionality into +Haskell. -- 1.7.10.4