X-Git-Url: http://git.megacz.com/?a=blobdiff_plain;f=docs%2Fusers_guide%2Fffi-chap.xml;h=358c5a84da1135ebe30e21a71c16c0627112b906;hb=c6e9a86f03efb4fdef5ed10fcb93b64439fdec60;hp=988f95dc1d3ffec74164f94ccf1eb3a7d393e044;hpb=5263c9ab4408e3b62dbf7505ab40a81946d4e49b;p=ghc-hetmet.git
diff --git a/docs/users_guide/ffi-chap.xml b/docs/users_guide/ffi-chap.xml
index 988f95d..358c5a8 100644
--- a/docs/users_guide/ffi-chap.xml
+++ b/docs/users_guide/ffi-chap.xml
@@ -7,13 +7,10 @@ Foreign function interface (FFI)
GHC (mostly) conforms to the Haskell 98 Foreign Function Interface
- Addendum 1.0, whose definition is available from http://haskell.org/.
+ Addendum 1.0, whose definition is available from http://www.haskell.org/.
- To enable FFI support in GHC, give the
- flag, or
-the
- flag which implies
-.
+ To enable FFI support in GHC, give the
+ flag.GHC implements a number of GHC-specific extensions to the FFI
Addendum. These extensions are described in , but please note that programs using
@@ -254,7 +251,8 @@ int main(int argc, char *argv[])
hs_exit()The outermost
hs_exit() will actually de-initialise the
system. NOTE that currently GHC's runtime cannot reliably
- re-initialise after this has happened.
+ re-initialise after this has happened,
+ see .
.
NOTE: when linking the final program, it is normally
@@ -354,86 +352,29 @@ int main(int argc, char *argv[])
C calls, function headers
- When generating C (using the
- flag), 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 the H98 FFI
- Addendum.
-
- 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.
-
-
-What if you are importing a module from another package, and
-a cross-module inlining exposes a foreign call that needs a supporting
-? If the imported module is from the same package as
-the module being compiled, you should supply all the
-that you supplied when compiling the imported module. If the imported module comes
-from another package, you won't necessarily know what the appropriate
- options are; but they should be in the package
-configuration, which GHC knows about. So if you are building a package using
- Cabal, remember to put all those include files in the package
- description (see the includes field in the Cabal
- documentation).
-
-
-It is also possible, according the FFI specification, to put the
- option in the foreign import
-declaration itself:
-
- foreign import "foo.h f" f :: Int -> IO Int
-
-When compiling this module, GHC will generate a C file that includes
-the specified . However, GHC
-disables cross-module inlining for such foreign
-calls, because it doesn't transport the
-information across module boundaries. (There is no fundamental reason for this;
-it was just tiresome to implement. The wrapper, which unboxes the arguments
-etc, is still inlined across modules.) So if you want the foreign call itself
-to be inlined across modules, use the command-line and package-configuration
- mechanism.
-
-
-
- Finding Header files
-
- Header files named by the
- option or in a foreign import declaration
- are searched for using the C compiler's usual search path.
- You can add directories to this search path using the
- option (see ).
-
- Note: header files are ignored unless compiling via C.
- If you had been compiling your code using the native code
- generator (the default) and suddenly switch to compiling via
- C, then you can get unexpected errors about missing include
- files. Compiling via C is enabled automatically when certain
- options are given (eg. and
- both enable
- ).
-
+ C functions are normally declared using prototypes in a C
+ header file. Earlier versions of GHC (6.8.3 and
+ earlier) #included the header file in
+ the C source file generated from the Haskell code, and the C
+ compiler could therefore check that the C function being
+ called via the FFI was being called at the right type.
+
+ GHC no longer includes external header files when
+ compiling via C, so this checking is not performed. The
+ change was made for compatibility with the native code backend
+ (-fasm) and to comply strictly with the FFI
+ specification, which requires that FFI calls are not subject
+ to macro expansion and other CPP conversions that may be
+ applied when using C header files. This approach also
+ simplifies the inlining of foreign calls across module and
+ package boundaries: there's no need for the header file to be
+ available when compiling an inlined version of a foreign call,
+ so the compiler is free to inline foreign calls in any
+ context.
+
+ The -#include option is now
+ deprecated, and the include-files field
+ in a Cabal package specification is ignored.