X-Git-Url: http://git.megacz.com/?p=ghc-hetmet.git;a=blobdiff_plain;f=docs%2Fusers_guide%2Fwin32-dlls.xml;h=f00e1e2c388927abcdf3730665841416782f99c1;hp=22a77deef8ebf5d7cbf83521c9d6c2f0ae41c687;hb=a52ff7619e8b7d74a9d933d922eeea49f580bca8;hpb=a8e681c1e8aa4bc602714ff61583cd4e969d7187 diff --git a/docs/users_guide/win32-dlls.xml b/docs/users_guide/win32-dlls.xml index 22a77de..f00e1e2 100644 --- a/docs/users_guide/win32-dlls.xml +++ b/docs/users_guide/win32-dlls.xml @@ -71,7 +71,7 @@ Notice how the "%1" argument is quoted (or not). This problem doesn't just affect GHCi, it affects any GHC-compiled program that wants to catch console events. See the GHC.ConsoleHandler + url="&libraryBaseLocation;/GHC-ConsoleHandler.html">GHC.ConsoleHandler module. @@ -210,8 +210,8 @@ make-sessions running under cygwin. Making Haskell libraries into DLLs doesn't work on Windows at the -moment; however, all the machinery is -still there. If you're interested, contact the GHC team. Note that +moment; we hope to re-instate this facility in the future +(see ). Note that building an entire Haskell application as a single DLL is still supported: it's just multi-DLL Haskell programs that don't work. The Windows distribution of GHC contains static libraries only. @@ -295,7 +295,7 @@ option on all the Haskell modules that make up your application. Creating a Win32 DLL -––mk-dll +–shared Sealing up your Haskell library inside a DLL is straightforward; compile up the object files that make up the library, and then build the DLL by issuing a command of the form: @@ -303,12 +303,12 @@ the DLL by issuing a command of the form: -ghc ––mk-dll -o foo.dll bar.o baz.o wibble.a -lfooble +ghc –shared -o foo.dll bar.o baz.o wibble.a -lfooble -By feeding the ghc compiler driver the option , it +By feeding the ghc compiler driver the option , it will build a DLL rather than produce an executable. The DLL will consist of all the object files and archives given on the command line. @@ -348,12 +348,12 @@ you compile into a DLL must have a common root. By default, the entry points of all the object files will be exported from -the DLL when using . Should you want to constrain +the DLL when using . Should you want to constrain this, you can specify the module definition file to use on the command line as follows: -ghc ––mk-dll -o .... -optdll––def -optdllMyDef.def +ghc –shared -o .... MyDef.def See Microsoft documentation for details, but a module definition file @@ -372,22 +372,22 @@ EXPORTS -In addition to creating a DLL, the option also +In addition to creating a DLL, the option also creates an import library. The import library name is derived from the name of the DLL, as follows: -DLL: HScool.dll ==> import lib: libHScool_imp.a +DLL: HScool.dll ==> import lib: libHScool.dll.a The naming scheme may look a bit weird, but it has the purpose of allowing the co-existence of import libraries with ordinary static libraries (e.g., libHSfoo.a and -libHSfoo_imp.a. +libHSfoo.dll.a. Additionally, when the compiler driver is linking in non-static mode, it will rewrite occurrence of on the command line to -. By doing this for you, switching from +. By doing this for you, switching from non-static to static linking is simply a question of adding to your command line. @@ -403,121 +403,146 @@ non-static to static linking is simply a question of adding Making DLLs to be called from other languages - -If you want to package up Haskell code to be called from other languages, -such as Visual Basic or C++, there are some extra things it is useful to -know. The dirty details are in the Foreign Function -Interface definition, but it can be tricky to work out how to -combine this with DLL building, so here's an example: - + This section describes how to create DLLs to be called from other languages, + such as Visual Basic or C++. This is a special case of + ; we'll deal with the DLL-specific issues that + arise below. Here's an example: - - - - -Use foreign export declarations to export the Haskell -functions you want to call from the outside. For example, - + Use foreign export declarations to export the Haskell functions you want to + call from the outside. For example: + +-- Adder.hs +{-# LANGUAGE ForeignFunctionInterface #-} module Adder where -adder :: Int -> Int -> IO Int –– gratuitous use of IO +adder :: Int -> Int -> IO Int -- gratuitous use of IO adder x y = return (x+y) foreign export stdcall adder :: Int -> Int -> IO Int - - - - -Compile it up: - - -ghc -c adder.hs -fglasgow-exts - - -This will produce two files, adder.o and adder_stub.o + Add some helper code that starts up and shuts down the Haskell RTS: - - - - -compile up a DllMain() that starts up the Haskell -RTS-––a possible implementation is: - -#include <windows.h> +// StartEnd.c #include <Rts.h> -extern void__stginit_Adder(void); - -static char* args[] = { "ghcDll", NULL }; - /* N.B. argv arrays must end with NULL */ -BOOL -STDCALL -DllMain - ( HANDLE hModule - , DWORD reason - , void* reserved - ) +void HsStart() { - if (reason == DLL_PROCESS_ATTACH) { - /* By now, the RTS DLL should have been hoisted in, but we need to start it up. */ - startupHaskell(1, args, __stginit_Adder); - return TRUE; - } - return TRUE; -} - - -Here, Adder is the name of the root module in the module -tree (as mentioned above, there must be a single root module, and hence a -single module tree in the DLL). + int argc = 1; + char* argv[] = {"ghcDll", NULL}; // argv must end with NULL -Compile this up: + // Initialize Haskell runtime + char** args = argv; + hs_init(&argc, &args); +} +void HsEnd() +{ + hs_exit(); +} + + + Here, Adder is the name of the root module in the module + tree (as mentioned above, there must be a single root module, and hence a + single module tree in the DLL). Compile everything up: + -ghc -c dllMain.c +ghc -c Adder.hs +ghc -c StartEnd.c +ghc -shared -o Adder.dll Adder.o Adder_stub.o StartEnd.o + + Now the file Adder.dll can be used from other + programming languages. Before calling any functions in Adder it is necessary + to call HsStart, and at the very end call + HsEnd. - - - -Construct the DLL: - - -ghc ––mk-dll -o adder.dll adder.o adder_stub.o dllMain.o - - + Warning: It may appear tempting to use + DllMain to call + hs_init/hs_exit, but this won't work + (particularly if you compile with -threaded). There are + severe restrictions on which actions can be performed during + DllMain, and hs_init violates these + restrictions, which can lead to your dll freezing during startup (see + bug + #3605). - - - -Start using adder from VBA-––here's how I would -Declare it: + +Using from VBA + + An example of using Adder.dll from VBA is: + -Private Declare Function adder Lib "adder.dll" Alias "adder@8" +Private Declare Function Adder Lib "Adder.dll" Alias "adder@8" _ (ByVal x As Long, ByVal y As Long) As Long - -Since this Haskell DLL depends on a couple of the DLLs that come with GHC, -make sure that they are in scope/visible. +Private Declare Sub HsStart Lib "Adder.dll" () +Private Declare Sub HsEnd Lib "Adder.dll" () + +Private Sub Document_Close() +HsEnd +End Sub + +Private Sub Document_Open() +HsStart +End Sub + +Public Sub Test() +MsgBox "12 + 5 = " & Adder(12, 5) +End Sub + + + This example uses the + Document_Open/Close functions of + Microsoft Word, but provided HsStart is called before the + first function, and HsEnd after the last, then it will + work fine. + + + +Using from C++ -Building statically linked DLLs is the same as in the previous section: it -suffices to add to the commands used to compile up -the Haskell source and build the DLL. + An example of using Adder.dll from C++ is: - + +// Tester.cpp +#include "HsFFI.h" +#include "Adder_stub.h" +#include <stdio.h> + +extern "C" { + void HsStart(); + void HsEnd(); +} - +int main() +{ + HsStart(); + // can now safely call functions from the DLL + printf("12 + 5 = %i\n", adder(12,5)) ; + HsEnd(); + return 0; +} + + + This can be compiled and run with: + + +$ ghc -o tester Tester.cpp Adder.dll.a +$ tester +12 + 5 = 17 + + + @@ -526,7 +551,6 @@ the Haskell source and build the DLL.