From c52eb69bb2f51fed830db42f22bab74c6ff05565 Mon Sep 17 00:00:00 2001 From: Simon Marlow Date: Tue, 15 Jul 2008 10:11:19 +0000 Subject: [PATCH] update the text about header files and -#include --- docs/users_guide/ffi-chap.xml | 103 +++++++++-------------------------------- 1 file changed, 23 insertions(+), 80 deletions(-) diff --git a/docs/users_guide/ffi-chap.xml b/docs/users_guide/ffi-chap.xml index 12aea55..a016f10 100644 --- a/docs/users_guide/ffi-chap.xml +++ b/docs/users_guide/ffi-chap.xml @@ -351,86 +351,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. -- 1.7.10.4