From: simonmar Date: Wed, 8 Aug 2001 13:19:08 +0000 (+0000) Subject: [project @ 2001-08-08 13:19:07 by simonmar] X-Git-Tag: Approximately_9120_patches~1319 X-Git-Url: http://git.megacz.com/?a=commitdiff_plain;h=14d65c3fe2850c98a1eeb7f62c59b1dddf15e56a;p=ghc-hetmet.git [project @ 2001-08-08 13:19:07 by simonmar] - Rearrange the FFI documentation: put it all in chapter 8. - Add a section "Using the FFI with GHC", and add some information about the stub files generated by GHC for foreign export dynamic. --- diff --git a/ghc/docs/users_guide/ffi-chap.sgml b/ghc/docs/users_guide/ffi-chap.sgml index 869c901..1bcc717 100644 --- a/ghc/docs/users_guide/ffi-chap.sgml +++ b/ghc/docs/users_guide/ffi-chap.sgml @@ -2,5 +2,138 @@ Foreign function interface + + The foreign interface consists of the following components: + + + + The Foreign Function Interface language specification + (which constitutes most of this Chapter, beginning with ). You must use the + command-line option to make GHC + understand the foreign declarations defined + by the FFI. + + + + The Foreign module (see ) collects together several interfaces + which are useful in specifying foreign language interfaces, + including the following: + + + + The ForeignObj module (see ), for managing pointers from + Haskell into the outside world. + + + + The StablePtr module (see ), for managing pointers into + Haskell from the outside world. + + + + The CTypes module (see ) gives Haskell equivalents for the + standard C datatypes, for use in making Haskell bindings to + existing C libraries. + + + + The CTypesISO module (see ) gives Haskell equivalents for C + types defined by the ISO C standard. + + + + The Storable library, for primitive + marshalling of data types between Haskell and the foreign + language. + + + + + + &ffi-body; + + + Using the FFI with GHC + + The following sections also give some hints and tips on the + use of the foreign function interface in GHC. + + + Using <literal>foreign export dynamic</literal> with + GHC + + foreign export + dynamicwith GHC + + + When GHC compiles a module (say M.hs) + which uses foreign export dynamic, it + generates two additional files, M_stub.c + and M_stub.h. GHC will automatically + compile M_stub.c to generate + M_stub.o at the same time. + + The C file M_stub.c contains small + helper functions used by the code generated for the + foreign export dynamic, so it must be linked + in to the final program. When linking the program, remember to + include M_stub.o in the final link command + line, or you'll get link errors for the missing function(s) + (this isn't necessary when building your program with + ghc --make, as GHC will automatically link in + the correct bits). + + + + Using function headers + + C calls, function headers + + When generating C (using the + + directive), one can assist the C compiler in detecting type + errors by using the directive + () to provide + .h files containing function + headers. + + For example, + + +#include "HsFFI.h" + +void initialiseEFS (HsInt size); +HsInt terminateEFS (void); +HsForeignObj emptyEFS(void); +HsForeignObj updateEFS (HsForeignObj a, HsInt i, HsInt x); +HsInt lookupEFS (HsForeignObj a, HsInt i); + + + The types HsInt, + HsForeignObj etc. are described in . + + Note that this approach is only + essential for returning + floats (or if sizeof(int) != + sizeof(int *) on your architecture) but is a Good + Thing for anyone who cares about writing solid code. You're + crazy not to do it. + + + + + diff --git a/ghc/docs/users_guide/glasgow_exts.sgml b/ghc/docs/users_guide/glasgow_exts.sgml index 97e02cf..abe513a 100644 --- a/ghc/docs/users_guide/glasgow_exts.sgml +++ b/ghc/docs/users_guide/glasgow_exts.sgml @@ -617,111 +617,6 @@ qualifier list has just one element, a boolean expression. - - The foreign interface - - The foreign interface consists of the following components: - - - - The Foreign Function Interface language specification - (included in this manual, in ). - You must use the command-line option - to make GHC understand the foreign declarations - defined by the FFI. - - - - The Foreign module (see ) collects together several interfaces - which are useful in specifying foreign language - interfaces, including the following: - - - - The ForeignObj module (see ), for managing pointers from - Haskell into the outside world. - - - - The StablePtr module (see ), for managing pointers - into Haskell from the outside world. - - - - The CTypes module (see ) gives Haskell equivalents for the - standard C datatypes, for use in making Haskell bindings - to existing C libraries. - - - - The CTypesISO module (see ) gives Haskell equivalents for C - types defined by the ISO C standard. - - - - The Storable library, for - primitive marshalling of data types between Haskell and - the foreign language. - - - - - - -The following sections also give some hints and tips on the use -of the foreign function interface in GHC. - - -Using function headers - - - -C calls, function headers - - - -When generating C (using the directive), one can assist the -C compiler in detecting type errors by using the directive -() to provide .h files containing function headers. - - - -For example, - - - - - -#include "HsFFI.h" - -void initialiseEFS (HsInt size); -HsInt terminateEFS (void); -HsForeignObj emptyEFS(void); -HsForeignObj updateEFS (HsForeignObj a, HsInt i, HsInt x); -HsInt lookupEFS (HsForeignObj a, HsInt i); - - - - The types HsInt, - HsForeignObj etc. are described in . - - Note that this approach is only - essential for returning - floats (or if sizeof(int) != - sizeof(int *) on your architecture) but is a Good - Thing for anyone who cares about writing solid code. You're - crazy not to do it. - - - - - Multi-parameter type classes diff --git a/ghc/docs/users_guide/sooner.sgml b/ghc/docs/users_guide/sooner.sgml index 07a4e4b..76682d5 100644 --- a/ghc/docs/users_guide/sooner.sgml +++ b/ghc/docs/users_guide/sooner.sgml @@ -460,7 +460,7 @@ to compete with it, but link with it. - describes the foreign calling interface. + describes the foreign function interface.