1.. _win32: 2 3Running GHC on Win32 systems 4============================ 5 6.. _ghc-windows: 7 8Starting GHC on Windows platforms 9--------------------------------- 10 11The installer that installs GHC on Win32 also sets up the file-suffix 12associations for ".hs" and ".lhs" files so that double-clicking them 13starts ``ghci``. 14 15Be aware of that ``ghc`` and ``ghci`` do require filenames containing 16spaces to be escaped using quotes: 17 18.. code-block:: none 19 20 c:\ghc\bin\ghci "c:\\Program Files\\Haskell\\Project.hs" 21 22If the quotes are left off in the above command, ``ghci`` will interpret 23the filename as two, ``c:\\\\Program`` and 24``Files\\\\Haskell\\\\Project.hs``. 25 26.. _ghci-windows: 27 28Running GHCi on Windows 29----------------------- 30 31We recommend running GHCi in a standard Windows console: select the 32``GHCi`` option from the start menu item added by the GHC installer, or 33use ``Start->Run->cmd`` to get a Windows console and invoke ``ghci`` 34from there (as long as it's in your ``PATH``). 35 36If you run GHCi in a Cygwin or MSYS shell, then the Control-C behaviour 37is adversely affected. In one of these environments you should use the 38``ghcii.sh`` script to start GHCi, otherwise when you hit Control-C 39you'll be returned to the shell prompt but the GHCi process will still 40be running. However, even using the ``ghcii.sh`` script, if you hit 41Control-C then the GHCi process will be killed immediately, rather than 42letting you interrupt a running program inside GHCi as it should. This 43problem is caused by the fact that the Cygwin and MSYS shell 44environments don't pass Control-C events to non-Cygwin child processes, 45because in order to do that there needs to be a Windows console. 46 47There's an exception: you can use a Cygwin shell if the ``CYGWIN`` 48environment variable does *not* contain ``tty``. In this mode, the 49Cygwin shell behaves like a Windows console shell and console events are 50propagated to child processes. Note that the ``CYGWIN`` environment 51variable must be set *before* starting the Cygwin shell; changing it 52afterwards has no effect on the shell. 53 54This problem doesn't just affect GHCi, it affects any GHC-compiled 55program that wants to catch console events. See the 56:base-ref:`GHC.ConsoleHandler.` module. 57 58.. _terminal-interaction: 59 60Interacting with the terminal 61----------------------------- 62 63By default GHC builds applications that open a console window when they 64start. If you want to build a GUI-only application, with no console 65window, use the flag ``-optl-mwindows`` in the link step. 66 67.. warning:: 68 Windows GUI-only programs have no stdin, stdout or stderr so 69 using the ordinary Haskell input/output functions will cause your 70 program to fail with an IO exception, such as: 71 72 .. code-block:: none 73 74 Fail: <stdout>: hPutChar: failed (Bad file descriptor) 75 76 However using Debug.Trace.trace is alright because it uses Windows 77 debugging output support rather than ``stderr``. 78 79For some reason, Mingw ships with the ``readline`` library, but not with 80the ``readline`` headers. As a result, GHC (like Hugs) does not use 81``readline`` for interactive input on Windows. You can get a close 82simulation by using an emacs shell buffer! 83 84.. _library-differences: 85 86Differences in library behaviour 87-------------------------------- 88 89Some of the standard Haskell libraries behave slightly differently on 90Windows. 91 92- On Windows, the ``^Z`` character is interpreted as an end-of-file 93 character, so if you read a file containing this character the file 94 will appear to end just before it. To avoid this, use 95 ``IOExts.openFileEx`` to open a file in binary (untranslated) mode or 96 change an already opened file handle into binary mode using 97 ``IOExts.hSetBinaryMode``. The ``IOExts`` module is part of the 98 ``lang`` package. 99 100.. _windows-file-paths: 101 102File paths under Windows 103------------------------ 104 105Windows paths are not all the same. The different kinds of paths each have 106different meanings. The ``MAX_PATH`` limitation is not a limitation of the operating 107system nor the file system. It is a limitation of the default namespace enforced 108by the Win32 API for backwards compatibility. 109 110The NT kernel however allows you ways to opt out of this path preprocessing by 111the Win32 APIs. This is done by explicitly using the desired namespace in the 112path. 113 114The namespaces are: 115 116 - file namespace: ``\\?\`` 117 - device namespace: ``\\.\`` 118 - NT namespace: ``\`` 119 120Each of these turn off path processing completely by the Win32 API and the paths 121are passed untouched to the filesystem. 122 123Paths with a drive letter are *legacy* paths. The drive letters are actually 124meaningless to the kernel. Just like Unix operating systems, drive letters are 125just a mount point. You can view your mount points by using the :command:`mountvol` 126command. 127 128Since GHC 8.6.1, the Haskell I/O manager automatically promotes paths in the legacy 129format to Win32 file namespace. By default the I/O manager will do two things to 130your paths: 131 132 - replace ``\`` with ``\\`` 133 - expand relative paths to absolute paths 134 135If you want to opt out of all preprocessing just expliticly use namespaces in 136your paths. Due to this change, if you need to open raw devices (e.g. COM ports) 137you need to use the device namespace explicitly. (e.g. ``\\.\COM1``). GHC and 138Haskell programs in general no longer support opening devices in the legacy 139format. 140 141See the 142`Windows documentation <https://msdn.microsoft.com/en-us/library/windows/desktop/aa365247.aspx>`_ 143for more details. 144 145 146.. _ghci-cygwin: 147 148Using GHC (and other GHC-compiled executables) with Cygwin 149---------------------------------------------------------- 150 151Background 152~~~~~~~~~~ 153 154The Cygwin tools aim to provide a Unix-style API on top of the windows 155libraries, to facilitate ports of Unix software to windows. To this end, 156they introduce a Unix-style directory hierarchy under some root 157directory (typically ``/`` is ``C:\cygwin\``). Moreover, everything 158built against the Cygwin API (including the Cygwin tools and programs 159compiled with Cygwin's GHC) will see ``/`` as the root of their file system, 160happily pretending to work in a typical unix environment, and finding 161things like ``/bin`` and ``/usr/include`` without ever explicitly 162bothering with their actual location on the windows system (probably 163``C:\cygwin\bin`` and ``C:\cygwin\usr\include``). 164 165The problem 166~~~~~~~~~~~ 167 168GHC, by default, no longer depends on cygwin, but is a native Windows 169program. It is built using mingw, and it uses mingw's GHC while 170compiling your Haskell sources (even if you call it from cygwin's bash), 171but what matters here is that - just like any other normal windows 172program - neither GHC nor the executables it produces are aware of 173Cygwin's pretended unix hierarchy. GHC will happily accept either ``/`` or 174``\\`` as path separators, but it won't know where to find ``/home/joe/Main.hs`` 175or ``/bin/bash`` or the like. This causes all kinds of fun when GHC is used from 176within Cygwin's bash, or in make-sessions running under Cygwin. 177 178Things to do 179~~~~~~~~~~~~ 180 181- Don't use absolute paths in ``make``, ``configure`` & co if there is any 182 chance that those might be passed to GHC (or to GHC-compiled 183 programs). Relative paths are fine because cygwin tools are happy 184 with them and GHC accepts ``/`` as path-separator. And relative paths 185 don't depend on where Cygwin's root directory is located, or on which 186 partition or network drive your source tree happens to reside, as 187 long as you ``cd`` there first. 188 189- If you have to use absolute paths (beware of the innocent-looking 190 ``ROOT=$(pwd)`` in makefile hierarchies or configure scripts), Cygwin 191 provides a tool called ``cygpath`` that can convert Cygwin's 192 Unix-style paths to their actual Windows-style counterparts. Many 193 Cygwin tools actually accept absolute Windows-style paths (remember, 194 though, that you either need to escape ``\\`` or convert ``\\`` to ``/``), 195 so you should be fine just using those everywhere. If you need to use 196 tools that do some kind of path-mangling that depends on unix-style 197 paths (one fun example is trying to interpret ``:`` as a separator in 198 path lists), you can still try to convert paths using ``cygpath`` 199 just before they are passed to GHC and friends. 200 201- If you don't have ``cygpath``, you probably don't have cygwin and 202 hence no problems with it... unless you want to write one build 203 process for several platforms. Again, relative paths are your friend, 204 but if you have to use absolute paths, and don't want to use 205 different tools on different platforms, you can simply write a short 206 Haskell program to print the current directory (thanks to George 207 Russell for this idea): compiled with GHC, this will give you the 208 view of the file system that GHC depends on (which will differ 209 depending on whether GHC is compiled with cygwin's gcc or mingw's gcc 210 or on a real Unix system..) - that little program can also deal with 211 escaping ``\\`` in paths. Apart from the banner and the startup time, 212 something like this would also do: 213 214 .. code-block:: none 215 216 $ echo "Directory.getCurrentDirectory >>= putStrLn . init . tail . show " | ghci 217 218.. _win32-dlls: 219 220Building and using Win32 DLLs 221----------------------------- 222 223Dynamic link libraries, Win32 DLLs, Win32 On Win32 platforms, the 224compiler is capable of both producing and using dynamic link libraries 225(DLLs) containing ghc-compiled code. This section shows you how to make 226use of this facility. 227 228There are two distinct ways in which DLLs can be used: 229 230- You can turn each Haskell package into a DLL, so that multiple 231 Haskell executables using the same packages can share the DLL files. 232 (As opposed to linking the libraries statically, which in effect 233 creates a new copy of the RTS and all libraries for each executable 234 produced.) 235 236 That is the same as the dynamic linking on other platforms, and it is 237 described in :ref:`using-shared-libs`. 238 239- You can package up a complete Haskell program as a DLL, to be called 240 by some external (usually non-Haskell) program. This is usually used 241 to implement plugins and the like, and is described below. 242 243.. _win32-dlls-create: 244 245Creating a DLL 246~~~~~~~~~~~~~~ 247 248Creating a Win32 DLL -shared Sealing up your Haskell library inside a 249DLL is straightforward; compile up the object files that make up the 250library, and then build the DLL by issuing a command of the form: 251 252.. code-block:: none 253 254 ghc -shared -o foo.dll bar.o baz.o wibble.a -lfooble 255 256By feeding the ghc compiler driver the option ``-shared``, it will build 257a DLL rather than produce an executable. The DLL will consist of all the 258object files and archives given on the command line. 259 260A couple of things to notice: 261 262- By default, the entry points of all the object files will be exported 263 from the DLL when using ``-shared``. Should you want to constrain 264 this, you can specify the *module definition file* to use on the 265 command line as follows: 266 267 .. code-block:: none 268 269 ghc -shared -o .... MyDef.def 270 271 See Microsoft documentation for details, but a module definition file 272 simply lists what entry points you want to export. Here's one that's 273 suitable when building a Haskell COM server DLL: 274 275 .. code-block:: none 276 277 EXPORTS 278 DllCanUnloadNow = DllCanUnloadNow@0 279 DllGetClassObject = DllGetClassObject@12 280 DllRegisterServer = DllRegisterServer@0 281 DllUnregisterServer = DllUnregisterServer@0 282 283- In addition to creating a DLL, the ``-shared`` option also creates an 284 import library. The import library name is derived from the name of 285 the DLL, as follows: 286 287 .. code-block:: none 288 289 DLL: HScool.dll ==> import lib: libHScool.dll.a 290 291 The naming scheme may look a bit weird, but it has the purpose of 292 allowing the co-existence of import libraries with ordinary static 293 libraries (e.g., ``libHSfoo.a`` and ``libHSfoo.dll.a``. Additionally, 294 when the compiler driver is linking in non-static mode, it will 295 rewrite occurrence of ``-lHSfoo`` on the command line to 296 ``-lHSfoo.dll``. By doing this for you, switching from non-static to 297 static linking is simply a question of adding ``-static`` to your 298 command line. 299 300.. _win32-dlls-foreign: 301 302Making DLLs to be called from other languages 303~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 304 305This section describes how to create DLLs to be called from other 306languages, such as Visual Basic or C++. This is a special case of 307:ref:`ffi-library`; we'll deal with the DLL-specific issues that arise 308below. Here's an example: 309 310Use foreign export declarations to export the Haskell functions you want 311to call from the outside. For example: 312 313:: 314 315 -- Adder.hs 316 {-# LANGUAGE ForeignFunctionInterface #-} 317 module Adder where 318 319 adder :: Int -> Int -> IO Int -- gratuitous use of IO 320 adder x y = return (x+y) 321 322 foreign export stdcall adder :: Int -> Int -> IO Int 323 324Add some helper code that starts up and shuts down the Haskell RTS: 325 326.. code-block:: c 327 328 // StartEnd.c 329 #include <Rts.h> 330 331 void HsStart() 332 { 333 int argc = 1; 334 char* argv[] = {"ghcDll", NULL}; // argv must end with NULL 335 336 // Initialize Haskell runtime 337 char** args = argv; 338 hs_init(&argc, &args); 339 } 340 341 void HsEnd() 342 { 343 hs_exit(); 344 } 345 346Here, ``Adder`` is the name of the root module in the module tree (as 347mentioned above, there must be a single root module, and hence a single 348module tree in the DLL). Compile everything up: 349 350.. code-block:: none 351 352 ghc -c Adder.hs 353 ghc -c StartEnd.c 354 ghc -shared -o Adder.dll Adder.o Adder_stub.o StartEnd.o 355 356Now the file ``Adder.dll`` can be used from other programming languages. 357Before calling any functions in Adder it is necessary to call 358``HsStart``, and at the very end call ``HsEnd``. 359 360.. warning:: 361 It may appear tempting to use ``DllMain`` to call 362 ``hs_init``/``hs_exit``, but this won't work (particularly if you 363 compile with ``-threaded``). There are severe restrictions on which 364 actions can be performed during ``DllMain``, and ``hs_init`` violates 365 these restrictions, which can lead to your DLL freezing during startup 366 (see :ghc-ticket:`3605`). 367 368.. _win32-dlls-vba: 369 370Using from VBA 371^^^^^^^^^^^^^^ 372 373An example of using ``Adder.dll`` from VBA is: 374 375.. code-block:: none 376 377 Private Declare Function Adder Lib "Adder.dll" Alias "adder@8" _ 378 (ByVal x As Long, ByVal y As Long) As Long 379 380 Private Declare Sub HsStart Lib "Adder.dll" () 381 Private Declare Sub HsEnd Lib "Adder.dll" () 382 383 Private Sub Document_Close() 384 HsEnd 385 End Sub 386 387 Private Sub Document_Open() 388 HsStart 389 End Sub 390 391 Public Sub Test() 392 MsgBox "12 + 5 = " & Adder(12, 5) 393 End Sub 394 395This example uses the ``Document_Open``\/``Close`` functions of Microsoft 396Word, but provided ``HsStart`` is called before the first function, and 397``HsEnd`` after the last, then it will work fine. 398 399.. _win32-dlls-c++: 400 401Using from C++ 402^^^^^^^^^^^^^^ 403 404An example of using ``Adder.dll`` from C++ is: 405 406.. code-block:: c 407 408 // Tester.cpp 409 #include "HsFFI.h" 410 #include "Adder_stub.h" 411 #include <stdio.h> 412 413 extern "C" { 414 void HsStart(); 415 void HsEnd(); 416 } 417 418 int main() 419 { 420 HsStart(); 421 // can now safely call functions from the DLL 422 printf("12 + 5 = %i\n", adder(12,5)) ; 423 HsEnd(); 424 return 0; 425 } 426 427This can be compiled and run with: 428 429.. code-block:: none 430 431 $ ghc -o tester Tester.cpp Adder.dll.a 432 $ tester 433 12 + 5 = 17 434