docs/users_guide/installing.xml

   1 <?xml version="1.0" encoding="iso-8859-1"?>
   2 <chapter id="installing-bin-distrib">
   3   <title>Installing GHC</title>
   4 <indexterm><primary>binary installations</primary></indexterm>
   5 <indexterm><primary>installation, of binaries</primary></indexterm>
   6
   7 <para>
   8 Installing from binary distributions is easiest, and recommended!
   9 (Why binaries? Because GHC is a Haskell compiler written in Haskell,
  10 so you've got to bootstrap it somehow.  We provide machine-generated
  11 C-files-from-Haskell for this purpose, but it's really quite a pain to
  12 use them.  If you must build GHC from its sources, using a
  13 binary-distributed GHC to do so is a sensible way to proceed.)
  14 </para>
  15
  16 <para>This guide is in several parts:</para>
  17
  18   <itemizedlist>
  19     <listitem>
  20       <para> Installing on Unix-a-likes (<xref
  21       linkend="unix-a-likes"/>). </para>
  22     </listitem>
  23     <listitem>
  24       <para> Installing on Windows (<xref
  25       linkend="install-windows"/>).  </para>
  26     </listitem>
  27     <listitem>
  28       <para> The layout of installed files (<xref
  29       linkend="install-files"/>).  You don't need to know this to
  30       install GHC, but it's useful if you are changing the
  31       implementation.</para>
  32     </listitem>
  33   </itemizedlist>
  34
  35   <sect1 id="unix-a-likes"><title>Installing on Unix-a-likes</title>
  36
  37     <sect2>
  38       <title>When a platform-specific package is available</title>
  39
  40       <para>For certain platforms, we provide GHC binaries packaged
  41       using the native package format for the platform.  This is
  42       likely to be by far the best way to install GHC for your
  43       platform if one of these packages is available, since
  44       dependencies will automatically be handled and the package
  45       system normally provides a way to uninstall the package at a
  46       later date.</para>
  47
  48       <para>We generally provide the following packages:</para>
  49
  50       <variablelist>
  51         <varlistentry>
  52           <term>RedHat or SuSE Linux/x86</term>
  53           <listitem>
  54             <para>RPM source &amp; binary packages for RedHat and SuSE
  55             Linux (x86 only) are available for most major
  56             releases.</para>
  57           </listitem>
  58         </varlistentry>
  59
  60         <varlistentry>
  61           <term>Debian Linux/x86</term>
  62           <listitem>
  63             <para>Debian packages for Linux (x86 only), also for most
  64             major releases.</para>
  65           </listitem>
  66         </varlistentry>
  67
  68         <varlistentry>
  69           <term>FreeBSD/x86</term>
  70           <listitem>
  71             <para>On FreeBSD/x86, GHC can be installed using either
  72             the ports tree (<literal>cd /usr/ports/lang/ghc &amp;&amp; make
  73             install</literal>) or from a pre-compiled package
  74             available from your local FreeBSD mirror.</para>
  75           </listitem>
  76         </varlistentry>
  77       </variablelist>
  78
  79       <para>Other platform-specific packages may be available, check
  80       the GHC download page for details.</para>
  81     </sect2>
  82
  83 <sect2>
  84 <title>GHC binary distributions</title>
  85
  86 <para>
  87 <indexterm><primary>bundles of binary stuff</primary></indexterm>
  88 </para>
  89
  90 <para>
  91 Binary distributions come in &ldquo;bundles,&rdquo; one bundle per file called
  92 <literal><replaceable>bundle</replaceable>-<replaceable>platform</replaceable>.tar.gz</literal>.  (See the <ulink url="http://hackage.haskell.org/trac/ghc/wiki/Building">building guide</ulink> for the definition of a platform.)  Suppose that you untar a binary-distribution bundle, thus:
  93 </para>
  94
  95 <para>
  96
  97 <screen>
  98 % cd /your/scratch/space
  99 % gunzip &#60; ghc-x.xx-sun-sparc-solaris2.tar.gz | tar xvf -</screen>
 100
 101 </para>
 102
 103 <para>
 104 Then you should find a single directory,
 105 <literal>ghc-<replaceable>version</replaceable></literal>, with the
 106 following structure:
 107 </para>
 108
 109 <para>
 110 <indexterm><primary>binary distribution, layout</primary></indexterm>
 111 <indexterm><primary>directory layout (binary distributions)</primary></indexterm>
 112 <variablelist>
 113
 114 <varlistentry>
 115 <term><literal>Makefile.in</literal></term>
 116 <listitem>
 117 <para>
 118 the raw material from which the <literal>Makefile</literal>
 119 will be made (<xref linkend="install"/>).
 120 </para>
 121 </listitem></varlistentry>
 122 <varlistentry>
 123 <term><literal>configure</literal></term>
 124 <listitem>
 125 <para>
 126 the configuration script (<xref linkend="install"/>).
 127 </para>
 128 </listitem></varlistentry>
 129 <varlistentry>
 130 <term><literal>README</literal></term>
 131 <listitem>
 132 <para>
 133 Contains this file summary.
 134 </para>
 135 </listitem></varlistentry>
 136 <varlistentry>
 137 <term><literal>INSTALL</literal></term>
 138 <listitem>
 139 <para>
 140 Contains this description of how to install
 141 the bundle.
 142 </para>
 143 </listitem></varlistentry>
 144 <varlistentry>
 145 <term><literal>ANNOUNCE</literal></term>
 146 <listitem>
 147 <para>
 148 The announcement message for the bundle.
 149 </para>
 150 </listitem></varlistentry>
 151 <varlistentry>
 152 <term><literal>NEWS</literal></term>
 153 <listitem>
 154 <para>
 155 release notes for the bundle&mdash;a longer version
 156 of <literal>ANNOUNCE</literal>.  For GHC, the release notes are contained in the User
 157 Guide and this file isn't present.
 158 </para>
 159 </listitem></varlistentry>
 160 <varlistentry>
 161             <term><literal>bin/<replaceable>platform</replaceable></literal></term>
 162 <listitem>
 163 <para>
 164 contains platform-specific executable
 165 files to be invoked directly by the user.  These are the files that
 166 must end up in your path.
 167 </para>
 168 </listitem></varlistentry>
 169 <varlistentry>
 170 <term><literal>lib/<replaceable>platform</replaceable>/</literal></term>
 171 <listitem>
 172 <para>
 173 contains platform-specific support
 174 files for the installation.  Typically there is a subdirectory for
 175 each <literal>fptools</literal> project, whose name is the name of the project with its
 176 version number.  For example, for GHC there would be a sub-directory
 177 <literal>ghc-x.xx</literal>/ where <literal>x.xx</literal> is the version number of GHC in the bundle.
 178 </para>
 179
 180 <para>
 181 These sub-directories have the following general structure:
 182 </para>
 183
 184 <para>
 185 <variablelist>
 186
 187 <varlistentry>
 188 <term><literal>libHSstd.a</literal> etc:</term>
 189 <listitem>
 190 <para>
 191 supporting library archives.
 192 </para>
 193 </listitem></varlistentry>
 194 <varlistentry>
 195 <term><literal>ghc-iface.prl</literal> etc:</term>
 196 <listitem>
 197 <para>
 198 support scripts.
 199 </para>
 200 </listitem></varlistentry>
 201 <varlistentry>
 202 <term><literal>import/</literal></term>
 203 <listitem>
 204 <para>
 205 <indexterm><primary>Interface files</primary></indexterm> (<literal>.hi</literal>) for the prelude.
 206 </para>
 207 </listitem></varlistentry>
 208 <varlistentry>
 209 <term><literal>include/</literal></term>
 210 <listitem>
 211 <para>
 212 A few C <literal>&num;include</literal> files.
 213 </para>
 214 </listitem></varlistentry>
 215 </variablelist>
 216 </para>
 217 </listitem></varlistentry>
 218 <varlistentry>
 219 <term><literal>share/</literal></term>
 220 <listitem>
 221 <para>
 222 contains platform-independent support files
 223 for the installation.  Again, there is a sub-directory for each
 224 <literal>fptools</literal> project.
 225 </para>
 226 </listitem></varlistentry>
 227 <varlistentry>
 228 <term><literal>html/</literal></term>
 229 <listitem>
 230 <para>
 231 contains HTML documentation files (one
 232 sub-directory per project).
 233 </para>
 234 </listitem></varlistentry>
 235 </variablelist>
 236 </para>
 237
 238 <sect3 id="install">
 239 <title>Installing</title>
 240
 241 <para>
 242 OK, so let's assume that you have unpacked your chosen bundles. What
 243 next? Well, you will at least need to run the
 244 <literal>configure</literal><indexterm><primary>configure</primary></indexterm>
 245 script by changing directory into the top-level directory for the
 246 bundle and typing <literal>./configure</literal>.  That should convert
 247 <literal>Makefile.in</literal> to <literal>Makefile</literal>.
 248 </para>
 249
 250 <para>
 251 <indexterm><primary>installing in-place</primary></indexterm>
 252 <indexterm><primary>in-place installation</primary></indexterm>
 253 You can now either start using the tools <emphasis>in-situ</emphasis> without going
 254 through any installation process, just type <literal>make in-place</literal> to set the
 255 tools up for this. You'll also want to add the path which <literal>make</literal> will
 256 now echo to your <literal>PATH</literal> environment variable. This option is useful if
 257 you simply want to try out the package and/or you don't have the
 258 necessary privileges (or inclination) to properly install the tools
 259 locally. Note that if you do decide to install the package `properly'
 260 at a later date, you have to go through the installation steps that
 261 follow.
 262 </para>
 263
 264 <para>
 265 To install a package, you'll have to do the following:
 266 </para>
 267
 268 <para>
 269
 270 <orderedlist>
 271 <listitem>
 272
 273 <para>
 274  Edit the <literal>Makefile</literal> and check the settings of the following variables:
 275
 276 <indexterm><primary>directories, installation</primary></indexterm>
 277 <indexterm><primary>installation directories</primary></indexterm>
 278
 279 <variablelist>
 280
 281 <varlistentry>
 282 <term><literal>platform</literal></term>
 283 <listitem>
 284 <para>
 285 the platform you are going to install for.
 286 </para>
 287 </listitem></varlistentry>
 288 <varlistentry>
 289 <term><literal>bindir</literal></term>
 290 <listitem>
 291 <para>
 292 the directory in which to install user-invokable
 293 binaries.
 294 </para>
 295 </listitem></varlistentry>
 296 <varlistentry>
 297 <term><literal>libdir</literal></term>
 298 <listitem>
 299 <para>
 300 the directory in which to install
 301 platform-dependent support files.
 302 </para>
 303 </listitem></varlistentry>
 304 <varlistentry>
 305 <term><literal>datadir</literal></term>
 306 <listitem>
 307 <para>
 308 the directory in which to install
 309 platform-independent support files.
 310 </para>
 311 </listitem></varlistentry>
 312 <varlistentry>
 313 <term><literal>infodir</literal></term>
 314 <listitem>
 315 <para>
 316 the directory in which to install Emacs info
 317 files.
 318 </para>
 319 </listitem></varlistentry>
 320 <varlistentry>
 321 <term><literal>htmldir</literal></term>
 322 <listitem>
 323 <para>
 324 the directory in which to install HTML
 325 documentation.
 326 </para>
 327 </listitem></varlistentry>
 328 <varlistentry>
 329 <term><literal>dvidir</literal></term>
 330 <listitem>
 331 <para>
 332 the directory in which to install DVI
 333 documentation.
 334 </para>
 335 </listitem></varlistentry>
 336 </variablelist>
 337
 338 The values for these variables can be set through invocation of the
 339 <command>configure</command><indexterm><primary>configure</primary></indexterm>
 340 script that comes with the distribution, but doing an optical diff to
 341 see if the values match your expectations is always a Good Idea.
 342 </para>
 343
 344 <para>
 345 <emphasis>Instead of running <command>configure</command>, it is
 346 perfectly OK to copy <filename>Makefile.in</filename> to
 347 <filename>Makefile</filename> and set all these variables directly
 348 yourself.  But do it right!</emphasis>
 349 </para>
 350
 351 </listitem>
 352 <listitem>
 353
 354 <para>
 355 Run <literal>make install</literal>.  This <emphasis>
 356 should</emphasis> work with ordinary Unix
 357 <literal>make</literal>&mdash;no need for fancy stuff like GNU
 358 <literal>make</literal>.
 359
 360 </para>
 361 </listitem>
 362 <listitem>
 363
 364 <para>
 365 <literal>rehash</literal> (t?csh or zsh users), so your shell will see the new
 366 stuff in your bin directory.
 367
 368 </para>
 369 </listitem>
 370 <listitem>
 371
 372 <para>
 373  Once done, test your &ldquo;installation&rdquo; as suggested in
 374 <xref linkend="GHC-test"/>.  Be sure to use a <literal>-v</literal>
 375 option, so you can see exactly what pathnames it's using.
 376
 377 If things don't work as expected, check the list of known pitfalls in
 378 the <ulink url="http://hackage.haskell.org/trac/ghc/wiki/Building">building guide</ulink>.
 379 </para>
 380 </listitem>
 381
 382 </orderedlist>
 383
 384 </para>
 385
 386 <para>
 387 <indexterm><primary>link, installed as ghc</primary></indexterm>
 388 When installing the user-invokable binaries, this installation
 389 procedure will install GHC as <literal>ghc-x.xx</literal> where <literal>x.xx</literal> is the version
 390 number of GHC.  It will also make a link (in the binary installation
 391 directory) from <literal>ghc</literal> to <literal>ghc-x.xx</literal>.  If you install multiple versions
 392 of GHC then the last one &ldquo;wins&rdquo;, and &ldquo;<literal>ghc</literal>&rdquo; will invoke the last
 393 one installed.  You can change this manually if you want.  But
 394 regardless, <literal>ghc-x.xx</literal> should always invoke GHC version <literal>x.xx</literal>.
 395 </para>
 396
 397 </sect3>
 398
 399
 400 <sect3>
 401 <title>What bundles there are</title>
 402
 403 <para>
 404 <indexterm><primary>bundles, binary</primary></indexterm> There are
 405 plenty of &ldquo;non-basic&rdquo; GHC bundles.  The files for them are
 406 called
 407 <literal>ghc-x.xx-<replaceable>bundle</replaceable>-<replaceable>platform</replaceable>.tar.gz</literal>,
 408 where the <replaceable>platform</replaceable> is as above, and
 409 <replaceable>bundle</replaceable> is one of these:
 410 </para>
 411
 412 <para>
 413 <variablelist>
 414
 415 <varlistentry>
 416 <term><literal>prof</literal>:</term>
 417 <listitem>
 418 <para>
 419 Profiling with cost-centres.  You probably want this.
 420 <indexterm><primary>profiling bundles</primary></indexterm>
 421 <indexterm><primary>bundles, profiling</primary></indexterm>
 422 </para>
 423 </listitem></varlistentry>
 424 <varlistentry>
 425 <term><literal>par</literal>:</term>
 426 <listitem>
 427 <para>
 428 Parallel Haskell features (sits on top of PVM).
 429 You'll want this if you're into that kind of thing.
 430 <indexterm><primary>parallel bundles</primary></indexterm>
 431 <indexterm><primary>bundles, parallel</primary></indexterm>
 432 </para>
 433 </listitem></varlistentry>
 434 <varlistentry>
 435 <term><literal>gran</literal>:</term>
 436 <listitem>
 437 <para>
 438 The &ldquo;GranSim&rdquo; parallel-Haskell simulator
 439 (hmm&hellip; mainly for implementors).
 440 <indexterm><primary>bundles, gransim</primary></indexterm>
 441 <indexterm><primary>gransim bundles</primary></indexterm>
 442 </para>
 443 </listitem></varlistentry>
 444 <varlistentry>
 445 <term><literal>ticky</literal>:</term>
 446 <listitem>
 447 <para>
 448 &ldquo;Ticky-ticky&rdquo; profiling; very detailed
 449 information about &ldquo;what happened when I ran this program&rdquo;&mdash;really
 450 for implementors.
 451 <indexterm><primary>bundles, ticky-ticky</primary></indexterm>
 452 <indexterm><primary>ticky-ticky bundles</primary></indexterm>
 453 </para>
 454 </listitem></varlistentry>
 455 </variablelist>
 456 </para>
 457
 458 <para>
 459 One likely scenario is that you will grab <emphasis>two</emphasis>
 460 binary bundles&mdash;basic, and profiling.  We don't usually make the
 461 rest, although you can build them yourself from a source distribution.
 462 </para>
 463
 464 <para>The various GHC bundles are designed to be unpacked into the
 465 same directory; then installing as per the directions above will
 466 install the whole lot in one go.  Note: you <emphasis>must</emphasis>
 467 at least have the basic GHC binary distribution bundle, these extra
 468 bundles won't install on their own.</para>
 469
 470 </sect3>
 471
 472 <sect3 id="GHC-test">
 473 <title>Testing that GHC seems to be working
 474 </title>
 475
 476 <para>
 477 <indexterm><primary>testing a new GHC</primary></indexterm>
 478 </para>
 479
 480 <para>
 481 The way to do this is, of course, to compile and run <emphasis>this</emphasis> program
 482 (in a file <literal>Main.hs</literal>):
 483 </para>
 484
 485 <para>
 486
 487 <programlisting>
 488 main = putStr "Hello, world!\n"
 489 </programlisting>
 490
 491 </para>
 492
 493 <para>
 494 Compile the program, using the <literal>-v</literal> (verbose) flag to verify that
 495 libraries, etc., are being found properly:
 496
 497 <screen>
 498 % ghc -v -o hello Main.hs</screen>
 499
 500 </para>
 501
 502 <para>
 503 Now run it:
 504
 505 <screen>
 506 % ./hello
 507 Hello, world!</screen>
 508
 509 </para>
 510
 511 <para>
 512 Some simple-but-profitable tests are to compile and run the notorious
 513 <literal>nfib</literal><indexterm><primary>nfib</primary></indexterm> program, using different numeric types.  Start with
 514 <literal>nfib :: Int -&gt; Int</literal>, and then try <literal>Integer</literal>, <literal>Float</literal>, <literal>Double</literal>,
 515 <literal>Rational</literal> and perhaps the overloaded version.  Code for this is
 516 distributed in <literal>ghc/misc/examples/nfib/</literal> in a source distribution.
 517 </para>
 518
 519 <para>For more information on how to &ldquo;drive&rdquo; GHC, read
 520 on...</para>
 521
 522 </sect3>
 523
 524 </sect2>
 525
 526 </sect1>
 527
 528
 529 <sect1 id="install-windows"><title>Installing on Windows</title>
 530
 531 <para>
 532 Getting the Glasgow Haskell Compiler (post 5.02) to run on Windows platforms is
 533 a snap: the installer does everything you need.
 534 </para>
 535
 536 <sect2><title>Installing GHC on Windows</title>
 537
 538 <para>
 539 To install GHC, use the following steps:
 540 </para>
 541 <itemizedlist>
 542 <listitem><para>Download the installer
 543 from the
 544 <ulink
 545 url="http://www.haskell.org/ghc/download.html">GHC download page</ulink>.
 546 </para></listitem>
 547
 548 <listitem><para>Run the installer.
 549 On Windows, all of GHC's files are installed in a single directory.
 550 You can override it, but by default this directory is
 551 <filename>c:/ghc/<replaceable>ghc-version</replaceable></filename>.
 552 The executable binary for GHC will be installed in the
 553 <filename>bin/</filename> sub-directory of the installation directory.
 554 If you want to invoke GHC from a command line, add this
 555 to your PATH environment variable.
 556 </para>
 557 <para>
 558 When installation is complete, you should find GHCi and the GHC
 559 documentation are available in your Start menu under
 560 "Start/All Programs/GHC/<replaceable>ghc-version</replaceable>".
 561 </para>
 562 </listitem>
 563
 564 <listitem><para>
 565 GHC needs a directory in which to create, and later delete, temporary files.
 566 It uses the standard Windows procedure <literal>GetTempPath()</literal> to
 567 find a suitable directory.  This procedure returns:
 568 <itemizedlist>
 569 <listitem><para>The path in environment variable TMP,
 570 if TMP is set.</para></listitem>
 571 <listitem><para>Otherwise, the path in environment variable TEMP,
 572 if TEMP is set.</para></listitem>
 573 <listitem><para>Otherwise, there is a per-user default which varies
 574 between versions of Windows. On NT and XP-ish versions, it might
 575 be:
 576 <filename>c:\Documents and Settings\&lt;username&gt;\Local Settings\Temp</filename>
 577 </para></listitem>
 578 </itemizedlist>
 579 The main point is that if you don't do anything GHC will work fine;
 580 but if you want to control where the directory is, you can do so by
 581 setting TMP or TEMP.
 582 </para></listitem>
 583
 584 <listitem>
 585 <para>
 586 To test the fruits of your labour, try now to compile a simple
 587 Haskell program:
 588 </para>
 589
 590 <screen>
 591 bash$ cat main.hs
 592 module Main(main) where
 593
 594 main = putStrLn "Hello, world!"
 595 bash$ ghc -o main main.hs
 596 ..
 597 bash$ ./main
 598 Hello, world!
 599 bash$</screen>
 600 </listitem>
 601 </itemizedlist>
 602
 603 <para>
 604 You do <emphasis>not</emphasis> need the Cygwin toolchain, or anything
 605 else, to install and run GHC.
 606 </para>
 607 <para>
 608 An installation of GHC requires about 340M of disk space.
 609 To run GHC comfortably, your machine should have at least
 610 64M of memory.
 611 </para>
 612 </sect2>
 613
 614 <sect2><title>Moving GHC around</title>
 615 <para>
 616 Once GHC is installed, you can freely move the entire GHC tree just by copying
 617 the <filename>c:/ghc/<replaceable>ghc-version</replaceable></filename>
 618 directory. (You will need to fix up
 619 the links in "Start/All Programs/GHC/<replaceable>ghc-version</replaceable>"
 620 if you do this.)
 621 </para>
 622 <para>
 623 It is OK to put GHC tree in a directory whose path involves spaces.  However,
 624 don't do this if you use want to use GHC with the Cygwin tools,
 625 because Cygwin can get confused when this happens.
 626 We havn't quite got to the bottom of this, but so far as we know it's not
 627 a problem with GHC itself.  Nevertheless, just to keep life simple we usually
 628 put GHC in a place with a space-free path.
 629 </para>
 630 </sect2>
 631
 632 <sect2 id="winfaq">
 633 <title>Installing ghc-win32 FAQ</title>
 634
 635       <variablelist>
 636         <varlistentry>
 637           <term>I'm having trouble with symlinks.</term>
 638           <listitem>
 639             <para>Symlinks only work under Cygwin (<xref linkend="install" />),
 640           so binaries not linked to the Cygwin
 641               DLL, in particular those built for Mingwin, will not work with
 642               symlinks.</para>
 643           </listitem>
 644         </varlistentry>
 645
 646         <varlistentry>
 647           <term>I'm getting &ldquo;permission denied&rdquo; messages from the
 648             <command>rm</command> or <command>mv</command>.</term>
 649           <listitem>
 650             <para>This can have various causes: trying to rename a directory
 651               when an Explorer window is open on it tends to fail. Closing the
 652               window generally cures the problem, but sometimes its cause is
 653               more mysterious, and logging off and back on or rebooting may be
 654               the quickest cure.</para>
 655           </listitem>
 656         </varlistentry>
 657       </variablelist>
 658 </sect2>
 659
 660 </sect1>
 661
 662
 663 <sect1 id="install-files"><title>The layout of installed files</title>
 664
 665 <para>
 666 This section describes what files get installed where.  You don't need to know it
 667 if you are simply installing GHC, but it is vital information if you are changing
 668 the implementation.
 669 </para>
 670 <para> GHC is installed in two directory trees:</para>
 671 <variablelist>
 672 <varlistentry>
 673 <term>Library directory,</term>
 674 <listitem> <para> known as <filename>$(libdir)</filename>, holds all the
 675 support files needed to run GHC.  On Unix, this
 676 directory is usually something like <filename>/usr/lib/ghc/ghc-5.02</filename>. </para>
 677 </listitem>
 678 </varlistentry>
 679 <varlistentry>
 680 <term>Binary directory</term>
 681 <listitem> <para> known as <filename>$(bindir)</filename>, holds executables that
 682 the user is expected to invoke.
 683 Notably, it contains
 684 <filename>ghc</filename> and <filename>ghci</filename>.  On Unix, this directory
 685 can be anywhere, but is typically something like <filename>/usr/local/bin</filename>.  On Windows,
 686 however, this directory <emphasis>must be</emphasis> <filename>$(libdir)/bin</filename>.
 687 </para>
 688 </listitem>
 689 </varlistentry>
 690 </variablelist>
 691
 692 <para>
 693 When GHC runs, it must know where its library directory is.
 694 It finds this out in one of two ways:
 695 </para>
 696 <itemizedlist>
 697 <listitem>
 698 <para>
 699 <filename>$(libdir)</filename> is passed to GHC using the <option>-B</option> flag.
 700 On Unix (but not Windows), the installed <filename>ghc</filename> is just a one-line
 701 shell script that invokes the real GHC, passing a suitable <option>-B</option> flag.
 702 [All the user-supplied flags
 703 follow, and a later <option>-B</option> flag overrides an earlier one, so a user-supplied
 704 one wins.]
 705 </para>
 706 </listitem>
 707 <listitem>
 708 <para> On Windows (but not Unix), if no <option>-B</option> flag is given, GHC uses a system
 709 call to find the directory in which the running GHC executable lives, and derives
 710 <filename>$(libdir)</filename> from that. [Unix lacks such a system call.]
 711 That is why <filename>$(bindir)</filename> must be <filename>$(libdir)/bin</filename>.
 712 </para>
 713 </listitem>
 714 </itemizedlist>
 715
 716 <sect2> <title>The binary directory</title>
 717
 718 <para>The binary directory, <filename>$(bindir)</filename> contains user-visible
 719 executables, notably <filename>ghc</filename> and <filename>ghci</filename>.
 720 You should add it to your <literal>$PATH</literal>
 721 </para>
 722
 723 <para>On Unix, the user-invokable <filename>ghc</filename> invokes <filename>$(libdir)/ghc-<replaceable>version</replaceable></filename>,
 724 passing a suitable <option>-B</option> flag to tell <filename>ghc-<replaceable>version</replaceable></filename> where
 725 <filename>$(libdir)</filename> is.
 726 Similarly <filename>ghci</filename>, except the extra flag <literal>--interactive</literal> is passed.
 727 </para>
 728
 729 <para>On Win32, the user-invokable <filename>ghc</filename> binary
 730 is the Real Thing (no intervening
 731 shell scripts or <filename>.bat</filename> files).
 732 Reason: we sometimes invoke GHC with very long command lines,
 733 and <filename>cmd.exe</filename> (which executes <filename>.bat</filename> files)
 734 truncates them.  Similarly <filename>ghci</filename> is a C wrapper program that invokes <filename>ghc --interactive</filename>
 735 (passing on all other arguments), not a <filename>.bat</filename> file.
 736 </para>
 737
 738
 739 </sect2>
 740
 741 <sect2> <title>The library directory</title>
 742
 743 <para>The layout of the library directory, <filename>$(libdir)</filename> is almost identical on
 744 Windows and Unix, as follows.  Differences between Windows and Unix
 745 are noted thus <literal>[Win32 only]</literal> and are commented below.</para>
 746
 747 <programlisting>
 748   $(libdir)/
 749     package.conf           GHC package configuration
 750     ghc-usage.txt          Message displayed by ghc &ndash;&ndash;help
 751
 752     bin/                   [Win32 only]  User-visible binaries
 753          ghc.exe
 754          ghci.exe
 755
 756     unlit                  Remove literate markup
 757
 758     touchy.exe             [Win32 only]
 759     perl.exe               [Win32 only]
 760     gcc.exe                [Win32 only]
 761
 762     ghc-x.xx               GHC executable [Unix only]
 763
 764     ghc-split              Asm code splitter
 765     ghc-asm                Asm code mangler
 766
 767     gcc-lib/               [Win32 only] Support files for gcc
 768         specs              gcc configuration
 769
 770         cpp0.exe           gcc support binaries
 771         as.exe
 772         ld.exe
 773
 774         crt0.o              Standard
 775            ..etc..          binaries
 776
 777         libmingw32.a        Standard
 778            ..etc..          libraries
 779
 780         *.h                 Include files
 781
 782     imports/                GHC interface files
 783         std/*.hi              'std' library
 784         lang/*.hi             'lang' library
 785         ..etc..
 786
 787     include/                 C header files
 788         StgMacros.h           GHC-specific
 789         ..etc...              header files
 790
 791         mingw/*.h            [Win32 only] Mingwin header files
 792
 793     libHSrts.a              GHC library archives
 794     libHSstd.a
 795     libHSlang.a
 796       ..etc..
 797
 798     HSstd1.o                GHC library linkables
 799     HSstd2.o                  (used by ghci, which does
 800     HSlang.o                  not grok .a files yet)
 801 </programlisting>
 802
 803 <para>Note that:
 804 <itemizedlist>
 805
 806         <listitem>
 807           <para><filename>$(libdir)</filename> also contains support
 808           binaries.  These are <emphasis>not</emphasis> expected to be
 809           on the user's <filename>PATH</filename>, but and are invoked
 810           directly by GHC.  In the Makefile system, this directory is
 811           also called <filename>$(libexecdir)</filename>, but
 812           <emphasis>you are not free to change it</emphasis>.  It must
 813           be the same as <filename>$(libdir)</filename>.</para>
 814         </listitem>
 815
 816 <listitem>
 817 <para>We distribute <filename>gcc</filename> with the Win32 distribution of GHC, so that users
 818 don't need to install <filename>gcc</filename>, nor need to care about which version it is.
 819 All <filename>gcc</filename>'s support files are kept in  <filename>$(libdir)/gcc-lib/</filename>.
 820 </para>
 821 </listitem>
 822
 823 <listitem>
 824 <para>Similarly, we distribute <filename>perl</filename> and a <filename>touch</filename>
 825 replacement (<filename>touchy.exe</filename>)
 826 with the Win32 distribution of GHC. </para>
 827 </listitem>
 828
 829         <listitem>
 830           <para>The support programs <filename>ghc-split</filename>
 831           and <filename>ghc-asm</filename> are Perl scripts.  The
 832           first line says <literal>#!/bin/perl</literal>; on Unix, the
 833           script is indeed invoked as a shell script, which invokes
 834           Perl; on Windows, GHC invokes
 835           <filename>$(libdir)/perl.exe</filename> directly, which
 836           treats the <literal>#!/bin/perl</literal> as a comment.
 837           Reason: on Windows we want to invoke the Perl distributed
 838           with GHC, rather than assume some installed one.  </para>
 839         </listitem>
 840 </itemizedlist>
 841 </para>
 842
 843 </sect2>
 844
 845 </sect1>
 846
 847 </chapter>
 848
 849 <!-- Emacs stuff:
 850      ;;; Local Variables: ***
 851      ;;; mode: xml ***
 852      ;;; sgml-parent-document: ("users_guide.xml" "book" "chapter") ***
 853      ;;; End: ***
 854  -->