X-Git-Url: http://git.megacz.com/?a=blobdiff_plain;f=ghc%2Fdocs%2Fusers_guide%2Fwin32-dlls.sgml;h=cdaad9cd605ee179c6c8e57cc7315654e33ea246;hb=ed1703f0decbe5dc01a3c90c698dc72a946bc4fd;hp=8c3090bea2788a0185133ba27f85ea9477985993;hpb=765a26370069896a1537f8a52675308246102fad;p=ghc-hetmet.git

diff --git a/ghc/docs/users_guide/win32-dlls.sgml b/ghc/docs/users_guide/win32-dlls.sgml
index 8c3090b..cdaad9c 100644
--- a/ghc/docs/users_guide/win32-dlls.sgml
+++ b/ghc/docs/users_guide/win32-dlls.sgml
@@ -1,31 +1,192 @@
-%************************************************************************
-%*                                                                      *
-<sect>Building and using Win32 DLLs
-<label id="win32-dlls">
-<p>
-<nidx>Dynamic link libraries, Win32</nidx>
-<nidx>DLLs, Win32</nidx>
-%*                                                                      *
-%************************************************************************
+<chapter id="win32">
+<title>Running GHC on Win32 systems</title>
 
+<sect1>
+<title>
+Starting GHC on Win32 platforms</title>
+
+<para>
+The installer that installs GHC on Win32 also sets up the file-suffix associations
+for ".hs" and ".lhs" files so that double-clicking them starts <command>ghci</command>.
+</para>
+<para>
+Be aware of that <command>ghc</command> and <command>ghci</command> do
+require filenames containing spaces to be escaped using quotes:
+<programlisting>
+  c:\ghc\bin\ghci "c:\\Program Files\\Haskell\\Project.hs"
+</programlisting>
+If the quotes are left off in the above command, <command>ghci</command> will
+interpret the filename as two, "c:\\Program" and "Files\\Haskell\\Project.hs".
+</para>
+
+<!-- not clear whether there are current editions of Win32 OSes that
+     doesn't do this by default.
+
+<para> Solution: don't use "Open With...", avoid spaces in file names, 
+or fiddle with the appropriate registry setting:
+<programlisting>
+  HKEY_CLASSES_ROOT\Unknown\shell\openas\command
+</programlisting>
+Notice how the "%1" argument is quoted (or not).
+</para>
+<para> This problem doesn't occur when double-clicking.
+</para>
+-->
+
+</sect1>
+
+<sect1>
+<title>
+Interacting with the terminal</title>
+
+<para>By default GHC builds applications that open a console window when they start.
+If you want to build a GUI-only application, with no console window, use the flag
+<literal>-optl-mwindows</literal> in the link step.
+</para>
+
+<para>For some reason, Mingw ships with the <literal>readline</literal> library,
+but not with the <literal>readline</literal> headers. As a result, GHC (like Hugs) does not
+use <literal>readline</literal> for interactive input on Windows.
+You can get a close simulation by using an emacs shell buffer!
+</para>
+
+</sect1>
+
+<sect1>
+<title>
+Differences in library behaviour </title>
+
+<para>
+Some of the standard Haskell libraries behave slightly differently on Windows.
+
+<itemizedlist>
+<listitem> <para>
+On Windows, the '<literal>^Z</literal>' character is interpreted as an
+end-of-file character, so if you read a file containing this character
+the file will appear to end just before it. To avoid this,
+use <literal>IOExts.openFileEx</literal> to open a file in binary
+(untranslated) mode or change an already opened file handle into
+binary mode using <literal>IOExts.hSetBinaryMode</literal>. The
+<literal>IOExts</literal> module is part of the
+<literal>lang</literal> package.
+</para>
+</listitem>
+</itemizedlist>
+</para>
+</sect1>
+
+<sect1>
+<title>
+Using GHC (and other GHC-compiled executables) with cygwin</title>
+
+<sect2>
+<title>Background</title> <para>The cygwin tools aim to provide a
+unix-style API on top of the windows libraries, to facilitate ports of
+unix software to windows. To this end, they introduce a unix-style
+directory hierarchy under some root directory (typically
+<filename>/</filename> is <filename>C:\cygwin\</filename>). Moreover,
+everything built against the cygwin API (including the cygwin tools
+and programs compiled with cygwin's ghc) will see / as the root of
+their file system, happily pretending to work in a typical unix
+environment, and finding things like <filename>/bin</filename> and <filename>/usr/include</filename> without
+ever explicitly bothering with their actual location on the windows
+system (probably <filename>C:\cygwin\bin</filename> and <filename>C:\cygwin\usr\include</filename>).
+</para>
+</sect2>
+
+<sect2><title>The problem</title>
+<para>GHC, by default, no longer depends on cygwin, but is a native
+windows program. It is built using mingw, and it uses mingw's ghc
+while compiling your Haskell sources (even if you call it from
+cygwin's bash), but what matters here is that - just like any other
+normal windows program - neither GHC nor the executables it produces
+are aware of cygwin's pretended unix hierarchy. GHC will happily
+accept either '/' or '\' as path separators, but it won't know where
+to find <filename>/home/joe/Main.hs</filename> or <filename>/bin/bash</filename> 
+or the like. This causes all
+kinds of fun when GHC is used from within cygwin's bash, or in
+make-sessions running under cygwin.
+</para>
+</sect2>
+
+<sect2><title>Things to do</title>
+<itemizedlist>
+<listitem>
+<para> Don't use absolute paths in make, configure & co if there is any chance 
+  that those might be passed to GHC (or to GHC-compiled programs). Relative
+  paths are fine because cygwin tools are happy with them and GHC accepts 
+  '/' as path-separator. And relative paths don't depend on where cygwin's
+  root directory is located, or on which partition or network drive your source
+  tree happens to reside, as long as you 'cd' there first.
+</para></listitem>
+
+<listitem>
+<para> If you have to use absolute paths (beware of the innocent-looking
+  <literal>ROOT=`pwd`</literal> in makefile hierarchies or configure scripts), cygwin provides
+  a tool called <command>cygpath</command> that can convert cygwin's unix-style paths to their
+  actual windows-style counterparts. Many cygwin tools actually accept
+  absolute windows-style paths (remember, though, that you either need 
+  to escape '\' or convert '\' to '/'), so you should be fine just using those 
+  everywhere. If you need to use tools that do some kind of path-mangling 
+  that depends on unix-style paths (one fun example is trying to interpret ':' 
+  as a separator in path lists..), you can still try to convert paths using 
+  <command>cygpath</command> just before they are passed to GHC and friends.
+</para></listitem>
+  
+<listitem>
+<para> If you don't have <command>cygpath</command>, you probably don't have cygwin and hence
+  no problems with it... unless you want to write one build process for several
+  platforms. Again, relative paths are your friend, but if you have to use
+  absolute paths, and don't want to use different tools on different platforms,
+  you can simply write a short Haskell program to print the current directory
+   (thanks to George Russell for this idea): compiled with GHC, this will give 
+  you the view of the file system that GHC depends on (which will differ 
+  depending on whether GHC is compiled with cygwin's gcc or mingw's
+  gcc or on a real unix system..) - that little program can also deal with 
+  escaping '\' in paths. Apart from the banner and the startup time, 
+  something like this would also do:
+<programlisting>
+  $ echo "Directory.getCurrentDirectory >>= putStrLn . init . tail . show " | ghci
+</programlisting>
+</para></listitem>
+</itemizedlist>
+</sect2>
+</sect1>
+
+
+<sect1 id="win32-dlls">
+<Title>Building and using Win32 DLLs
+</Title>
+
+<Para>
+<IndexTerm><Primary>Dynamic link libraries, Win32</Primary></IndexTerm>
+<IndexTerm><Primary>DLLs, Win32</Primary></IndexTerm>
 On Win32 platforms, the compiler is capable of both producing and using
 dynamic link libraries (DLLs) containing ghc-compiled code. This
 section shows you how to make use of this facility.
+</Para>
+
+<Para>
+Until recently, <Command>strip</Command> didn't work reliably on DLLs, so you
+should test your version with care, or make sure you have the latest
+binutils. Unfortunately, we don't know exactly which version of binutils
+cured the problem (it was supposedly fixed some years ago).
+</Para>
 
-%************************************************************************
-%*                                                                      *
-<sect1>Linking with DLLs
-<label id="win32-dlls:link">
-<p>
-%*                                                                      *
-%************************************************************************
 
+<Sect2 id="win32-dlls-link">
+<Title>Linking with DLLs
+</Title>
+
+<Para>
 The default on Win32 platforms is to link applications in such a way
 that the executables will use the Prelude and system libraries DLLs,
 rather than contain (large chunks of) them. This is transparent at the
 command-line, so 
+</Para>
 
-<tscreen><verb>
+<Para>
+<Screen>
 sh$ cat main.hs
 module Main where
 main = putStrLn "hello, world!"
@@ -33,137 +194,282 @@ sh$ ghc -o main main.hs
 ghc: module version changed to 1; reason: no old .hi file
 sh$ strip main.exe
 sh$ ls -l main.exe
--rwxr-xr-x   1 544      everyone     6144 May  3 17:11 main.exe*
+-rwxr-xr-x   1 544      everyone     4608 May  3 17:11 main.exe*
 sh$ ./main
 hello, world!
 sh$ 
-</verb></tscreen>
+</Screen>
+</Para>
+
+<Para>
+will give you a binary as before, but the <Filename>main.exe</Filename>
+generated will use the Prelude and RTS DLLs instead of linking them in
+statically.
+</Para>
 
-will give you a binary as before, but the <tt>main.exe</tt> generated
-will use the Prelude and RTS DLLs instead.
+<Para>
+4K for a <Literal>"hello, world"</Literal> application&mdash;not bad, huh? :-)
+</Para>
 
-6K for a <tt>"hello, world"</tt> application - not bad, huh? :-)
+</Sect2>
 
-%************************************************************************
-%*                                                                      *
-<sect1>Not linking with DLLs
-<label id="win32-dlls:linking-static">
-<nidx>-static option (Win32)</nidx>
-<p>
-%*                                                                      *
-%************************************************************************
+<Sect2 id="win32-dlls-linking-static">
+<Title>Not linking with DLLs
+<IndexTerm><Primary>-static option (Win32)</Primary></IndexTerm></Title>
 
+<Para>
 If you want to build an executable that doesn't depend on any
-ghc-compiled DLLs, use the <tt>-static</tt> option to link in
+ghc-compiled DLLs, use the <Option>-static</Option> option to link in
 the code statically.
+</Para>
 
+<Para>
 Notice that you cannot mix code that has been compiled with
-<tt>-static</tt> and not, so you have to use the <tt>-static</tt>
+<Option>-static</Option> and not, so you have to use the <Option>-static</Option>
 option on all the Haskell modules that make up your application.
+</Para>
+
+</Sect2>
+
+<Sect2 id="win32-dlls-create">
+<Title>Creating a DLL
+</Title>
 
-%************************************************************************
-%*                                                                      *
-<sect1>Creating a DLL
-<label id="win32-dlls:create">
-<p>
-<nidx>Creating a Win32 DLL</nidx>
-<nidx>--mk-dll</nidx>
-%*                                                                      *
-%************************************************************************
-
-Sealing up your Haskell library inside a DLL is quite straightforward;
+<Para>
+<emphasis>Making libraries into DLLs doesn't work on Windows at the
+moment (and is no longer supported); however, all the machinery is
+still there. If you're interested, contact the GHC team. Note that
+building an entire Haskell application as a DLL is still supported
+(it's just inter-DLL Haskell calls that don't work).</emphasis>
+<IndexTerm><Primary>Creating a Win32 DLL</Primary></IndexTerm>
+<IndexTerm><Primary>&ndash;&ndash;mk-dll</Primary></IndexTerm>
+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 the following command:
+the DLL by issuing a command of the form:
+</Para>
 
-<tscreen><verb>
-sh$ ghc --mk-dll -o HSsuper.dll A.o Super.o B.o libmine.a -lgdi32
-</verb></tscreen>
+<Para>
+<Screen>
+ghc &ndash;&ndash;mk-dll -o foo.dll bar.o baz.o wibble.a -lfooble
+</Screen>
+</Para>
 
-By feeding the ghc compiler driver the option <tt>--mk-dll</tt>, it
+<Para>
+By feeding the ghc compiler driver the option <Option>&ndash;&ndash;mk-dll</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.
+</Para>
 
+<Para>
+To create a `static' DLL, i.e. one that does not depend on the GHC DLLs,
+use the <Option>-static</Option> when compiling up your Haskell code and
+building the DLL.
+</Para>
+
+<Para>
 A couple of things to notice:
+</Para>
+
+<Para>
+
+<ItemizedList>
+<ListItem>
+<Para>
+Since DLLs correspond to packages (see <XRef LinkEnd="packages">) you need
+to use <Option>-package-name dll-name</Option> when compiling modules that
+belong to a DLL if you're going to call them from Haskell. Otherwise, Haskell
+code that calls entry points in that DLL will do so incorrectly, and crash.
+For similar reasons, you can only compile a single module tree into a DLL,
+as <Function>startupHaskell</Function> needs to be able to call its
+initialisation function, and only takes one such argument (see <XRef
+LinkEnd="win32-dlls-foreign">). Hence the modules
+you compile into a DLL must have a common root.
+</Para>
+</ListItem>
+
+<ListItem>
+<Para>
+By default, the entry points of all the object files will be exported from
+the DLL when using <Option>&ndash;&ndash;mk-dll</Option>. Should you want to constrain
+this, you can specify the <Emphasis>module definition file</Emphasis> to use
+on the command line as follows:
 
-<itemize>
-<item>
-When compiling the module <tt>A</tt>, the code emitted by the compiler
-differs depending on whether or not the functions and data it is
-importing from other Haskell modules correspond to symbols that are
-packaged up in a ghc-compiled DLL. To resolve whether such imports are
-'DLL imports' or not, the following rules are used:
-
-<itemize>
-<item>
-If the compiler imports from a module that's in the same directory as
-the one being compiled, it is assumed to not belong to a different DLL
-(or executable) than the module being processed, so none of the
-same-directory imports are considered 'DLL imports'.
-
-<item>
-If a directory contains the (probably empty) file
-<tt>dLL_ifs.hi</tt>, the code corresponding to the interface
-files found in that directory are assumed to live in a DLL
-separate from the one being compiled. 
-
-Notice that the first rule takes precedence over this one, so if
-you're compiling a module that imports from a Haskell module whose
-interface file live in the same directory, <em>and</em> that directory
-also contains the file <tt>dLL_ifs.hi</tt>, the import is still not
-being considered to be a 'DLL import'.
-
-<item>
-If compiling with the option <tt>-static</tt>, the previous rule
-is disabled.
-</itemize>
-
-So, in short, after having built your Haskell DLL, make sure you
-create the file <tt>dLL_ifs.hi</tt> in the directory that contains
-its interface files. If you don't, Haskell code that calls upon entry
-points in that DLL, will do so incorrectly, and a crash will result.
-(it is unfortunate that this isn't currently caught at compile-time).
-
-<item>
-By default, the entry points of all the object files will
-be exported from the DLL when using <tt>--mk-dll</tt>. Should you want
-to constrain this, you can specify the <em>module definition file</em>
-to use on the command line as follows:
-
-<tscreen><verb>
-sh$ ghc --mk-dll -o .... -optdll--def -optdllMyDef.def
-</verb></tscreen>
+<Screen>
+ghc &ndash;&ndash;mk-dll -o .... -optdll--def -optdllMyDef.def
+</Screen>
 
 See Microsoft documentation for details, but a module definition file
 simply lists what entry points you want to export. Here's one that's
 suitable when building a Haskell COM server DLL:
 
-<tscreen><verb>
+<ProgramListing>
 EXPORTS
  DllCanUnloadNow     = DllCanUnloadNow@0
  DllGetClassObject   = DllGetClassObject@12
  DllRegisterServer   = DllRegisterServer@0
  DllUnregisterServer = DllUnregisterServer@0
+</ProgramListing>
+</Para>
+</ListItem>
 
-</verb></tscreen>
-
-<item>
-In addition to creating a DLL, the <tt>--mk-dll</tt> option will also
-create an import library. The import library name is derived from the
+<ListItem>
+<Para>
+In addition to creating a DLL, the <Option>&ndash;&ndash;mk-dll</Option> option also
+creates an import library. The import library name is derived from the
 name of the DLL, as follows:
 
-<tscreen><verb>
-  DLL: HScool.dll  ==> import lib: libHScool_imp.a
-</verb></tscreen>
+<ProgramListing>
+DLL: HScool.dll  ==&#62; import lib: libHScool_imp.a
+</ProgramListing>
+
+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.,
+<Filename>libHSfoo.a</Filename> and
+<Filename>libHSfoo&lowbar;imp.a</Filename>.
+
+Additionally, when the compiler driver is linking in non-static mode, it
+will rewrite occurrence of <Option>-lHSfoo</Option> on the command line to
+<Option>-lHSfoo&lowbar;imp</Option>. By doing this for you, switching from
+non-static to static linking is simply a question of adding
+<Option>-static</Option> to your command line.
+
+</Para>
+</ListItem>
+</ItemizedList>
+</Para>
+
+</Sect2>
+
+
+<Sect2 id="win32-dlls-foreign">
+<Title>Making DLLs to be called from other languages</Title>
+
+<Para>
+
+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 <Emphasis>Foreign Function
+Interface</Emphasis> definition, but it can be tricky to work out how to
+combine this with DLL building, so here's an example:
+
+</Para>
+
+<ItemizedList>
+
+<ListItem>
+<Para>
+Use <Literal>foreign export</Literal> declarations to export the Haskell
+functions you want to call from the outside. For example,
+
+<ProgramListing>
+module Adder where
+
+adder :: Int -> Int -> IO Int  -- gratuitous use of IO
+adder x y = return (x+y)
+
+foreign export stdcall adder :: Int -> Int -> IO Int
+</ProgramListing>
+</Para>
+</ListItem>
+
+<ListItem>
+<Para>
+Compile it up:
+
+<Screen>
+ghc -c adder.hs -fglasgow-exts
+</Screen>
+  
+This will produce two files, adder.o and adder_stub.o
+</Para>
+</ListItem>
+
+<ListItem>
+<Para>
+compile up a <Function>DllMain()</Function> that starts up the Haskell
+RTS-&ndash;&ndash;a possible implementation is:
+
+<ProgramListing>
+#include &lt;windows.h&gt;
+#include &lt;Rts.h&gt;
+
+EXTFUN(__stginit_Adder);
+
+static char* args[] = { "ghcDll", NULL };
+                       /* N.B. argv arrays must end with NULL */
+BOOL
+STDCALL
+DllMain
+   ( HANDLE hModule
+   , DWORD reason
+   , void* reserved
+   )
+{
+  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;
+}
+</ProgramListing>
+
+Here, <Literal>Adder</Literal> 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 this up:
+
+<Screen>
+ghc -c dllMain.c
+</Screen>
+</Para>
+</ListItem>
+
+<ListItem>
+<Para>
+Construct the DLL:
+
+<Screen>
+ghc &ndash;&ndash;mk-dll -o adder.dll adder.o adder_stub.o dllMain.o
+</Screen>
+
+</Para>
+</ListItem>
+
+<ListItem>
+<Para>
+Start using <Function>adder</Function> from VBA-&ndash;&ndash;here's how I would
+<Constant>Declare</Constant> it:
+
+<ProgramListing>
+Private Declare Function adder Lib "adder.dll" Alias "adder@8"
+      (ByVal x As Long, ByVal y As Long) As Long
+</ProgramListing>
+
+Since this Haskell DLL depends on a couple of the DLLs that come with GHC,
+make sure that they are in scope/visible.
+</Para>
+
+<Para>
+Building statically linked DLLs is the same as in the previous section: it
+suffices to add <Option>-static</Option> to the commands used to compile up
+the Haskell source and build the DLL.
+</Para>
+
+</ListItem>
+
+</ItemizedList>
 
-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., <tt>libHSfoo.a</tt> and <tt>libHSfoo_imp.a</tt>.
+</Sect2>
 
-Additionally, when the compiler driver is linking in non-static mode,
-it will rewrite occurrence of <tt>-lHSfoo</tt> on the command line to
-<tt>-lHSfoo_imp</tt>. By doing this for you, switching from non-static
-to static linking is simply a question of adding <tt>-static</tt> to
-your command line.
+</sect1>
+</Chapter>
 
-</itemize>
+<!-- Emacs stuff:
+     ;;; Local Variables: ***
+     ;;; mode: sgml ***
+     ;;; sgml-parent-document: ("users_guide.sgml" "book" "chapter") ***
+     ;;; End: ***
+ -->