[[project @ 2001-08-08 13:19:07 by simonmar]
simonmar**20010808131908
- 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.
] {
hunk ./ghc/docs/users_guide/ffi-chap.sgml 5
+
+ 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.
+
+
+
+
+
+
hunk ./ghc/docs/users_guide/ffi-chap.sgml 61
+
+
+ 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.
+
+
+
hunk ./ghc/docs/users_guide/ffi-chap.sgml 134
+
+
hunk ./ghc/docs/users_guide/glasgow_exts.sgml 619
-
-
- 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.
-
-
-
-
hunk ./ghc/docs/users_guide/sooner.sgml 463
- describes the foreign calling interface.
+ describes the foreign function interface.
}