ghc/docs/users_guide/installing.sgml

   1 <Chapter id="sec-installing-bin-distrib">
   2   <Title>Installing GHC</Title>
   3 <IndexTerm><Primary>binary installations</Primary></IndexTerm>
   4 <IndexTerm><Primary>installation, of binaries</Primary></IndexTerm>
   5
   6 <Para>
   7 Installing from binary distributions is easiest, and recommended!
   8 (Why binaries? Because GHC is a Haskell compiler written in Haskell,
   9 so you've got to bootstrap it somehow.  We provide machine-generated
  10 C-files-from-Haskell for this purpose, but it's really quite a pain to
  11 use them.  If you must build GHC from its sources, using a
  12 binary-distributed GHC to do so is a sensible way to proceed. For the
  13 other <Literal>fptools</Literal> programs, many are written in
  14 Haskell, so binary distributions allow you to install them without
  15 having a Haskell compiler.)
  16 </Para>
  17
  18 <Para>This guide is in several parts:</para>
  19 <itemizedlist>
  20 <listitem> <para> Installing on Unix-a-likes (<Xref LinkEnd="sec-unix-a-likes">). </para>  </listitem>
  21 <listitem> <para> Installing on Windows  (<Xref LinkEnd="sec-install-windows">).   </para> </listitem>
  22 <listitem> <para> The layout of installed files  (<Xref LinkEnd="sec-install-files">).
  23 You don't need to know this to install GHC,
  24 but it's useful if you are changing the implementation.   </para>  </listitem>
  25 <listitem> <para> Installing or building the documentation (<Xref LinkEnd="building-docs">).  </para> </listitem>
  26 </itemizedlist>
  27
  28
  29
  30   <Sect1 id="sec-unix-a-likes"><Title>Installing on Unix-a-likes</Title>
  31
  32     <sect2>
  33       <title>When a platform-specific package is available</title>
  34
  35       <para>For certain platforms, we provide GHC binaries packaged
  36       using the native package format for the platform.  This is
  37       likely to be by far the best way to install GHC for your
  38       platform if one of these packages is available, since
  39       dependencies will automatically be handled and the package
  40       system normally provides a way to uninstall the package at a
  41       later date.</para>
  42
  43       <para>We generally provide the following packages:</para>
  44
  45       <variablelist>
  46         <varlistentry>
  47           <term>RedHat Linux/x86</term>
  48           <listitem>
  49             <para>RPM source & binary packages for RedHat Linux (x86
  50             only) are available for most major releases.</para>
  51           </listitem>
  52         </varlistentry>
  53
  54         <varlistentry>
  55           <term>Debian Linux/x86</term>
  56           <listitem>
  57             <para>Debian packages for Linux (x86 only), also for most
  58             major releases.</para>
  59           </listitem>
  60         </varlistentry>
  61
  62         <varlistentry>
  63           <term>FreeBSD/x86</term>
  64           <listitem>
  65             <para>On FreeBSD/x86, GHC can be installed using either
  66             the ports tree (<literal>cd /usr/ports/lang/ghc && make
  67             install</literal>) or from a pre-compiled package
  68             available from your local FreeBSD mirror.</para>
  69           </listitem>
  70         </varlistentry>
  71       </variablelist>
  72
  73       <para>Other platform-specific packages may be available, check
  74       the GHC download page for details.</para>
  75     </sect2>
  76
  77 <Sect2>
  78 <Title>GHC binary distributions</Title>
  79
  80 <Para>
  81 <IndexTerm><Primary>bundles of binary stuff</Primary></IndexTerm>
  82 </Para>
  83
  84 <Para>
  85 Binary distributions come in &ldquo;bundles,&rdquo; one bundle per file called
  86 <literal><replaceable>bundle</replaceable>-<replaceable>platform</replaceable>.tar.gz</Literal>.  (See the building guide for the definition of a platform.)  Suppose that you untar a binary-distribution bundle, thus:
  87 </Para>
  88
  89 <Para>
  90
  91 <Screen>
  92 % cd /your/scratch/space
  93 % gunzip &#60; ghc-x.xx-sun-sparc-solaris2.tar.gz | tar xvf -</Screen>
  94
  95 </Para>
  96
  97 <Para>
  98 Then you should find a single directory, <Literal>fptools</Literal>, with the following
  99 structure:
 100 </Para>
 101
 102 <Para>
 103 <IndexTerm><Primary>binary distribution, layout</Primary></IndexTerm>
 104 <IndexTerm><Primary>directory layout (binary distributions)</Primary></IndexTerm>
 105 <VariableList>
 106
 107 <VarListEntry>
 108 <Term><Literal>Makefile.in</Literal></Term>
 109 <ListItem>
 110 <Para>
 111 the raw material from which the <Literal>Makefile</Literal>
 112 will be made (<Xref LinkEnd="sec-install">).
 113 </Para>
 114 </ListItem></VarListEntry>
 115 <VarListEntry>
 116 <Term><Literal>configure</Literal></Term>
 117 <ListItem>
 118 <Para>
 119 the configuration script (<Xref LinkEnd="sec-install">).
 120 </Para>
 121 </ListItem></VarListEntry>
 122 <VarListEntry>
 123 <Term><Literal>README</Literal></Term>
 124 <ListItem>
 125 <Para>
 126 Contains this file summary.
 127 </Para>
 128 </ListItem></VarListEntry>
 129 <VarListEntry>
 130 <Term><Literal>INSTALL</Literal></Term>
 131 <ListItem>
 132 <Para>
 133 Contains this description of how to install
 134 the bundle.
 135 </Para>
 136 </ListItem></VarListEntry>
 137 <VarListEntry>
 138 <Term><Literal>ANNOUNCE</Literal></Term>
 139 <ListItem>
 140 <Para>
 141 The announcement message for the bundle.
 142 </Para>
 143 </ListItem></VarListEntry>
 144 <VarListEntry>
 145 <Term><Literal>NEWS</Literal></Term>
 146 <ListItem>
 147 <Para>
 148 release notes for the bundle&mdash;a longer version
 149 of <Literal>ANNOUNCE</Literal>.  For GHC, the release notes are contained in the User
 150 Guide and this file isn't present.
 151 </Para>
 152 </ListItem></VarListEntry>
 153 <VarListEntry>
 154             <Term><Literal>bin/<replaceable>platform</replaceable></Literal></Term>
 155 <ListItem>
 156 <Para>
 157 contains platform-specific executable
 158 files to be invoked directly by the user.  These are the files that
 159 must end up in your path.
 160 </Para>
 161 </ListItem></VarListEntry>
 162 <VarListEntry>
 163 <Term><Literal>lib/<replaceable>platform</replaceable>/</Literal></Term>
 164 <ListItem>
 165 <Para>
 166 contains platform-specific support
 167 files for the installation.  Typically there is a subdirectory for
 168 each <Literal>fptools</Literal> project, whose name is the name of the project with its
 169 version number.  For example, for GHC there would be a sub-directory
 170 <Literal>ghc-x.xx</Literal>/ where <Literal>x.xx</Literal> is the version number of GHC in the bundle.
 171 </Para>
 172
 173 <Para>
 174 These sub-directories have the following general structure:
 175 </Para>
 176
 177 <Para>
 178 <VariableList>
 179
 180 <VarListEntry>
 181 <Term><Literal>libHSstd.a</Literal> etc:</Term>
 182 <ListItem>
 183 <Para>
 184 supporting library archives.
 185 </Para>
 186 </ListItem></VarListEntry>
 187 <VarListEntry>
 188 <Term><Literal>ghc-iface.prl</Literal> etc:</Term>
 189 <ListItem>
 190 <Para>
 191 support scripts.
 192 </Para>
 193 </ListItem></VarListEntry>
 194 <VarListEntry>
 195 <Term><Literal>import/</Literal></Term>
 196 <ListItem>
 197 <Para>
 198 <IndexTerm><Primary>Interface files</Primary></IndexTerm> (<Literal>.hi</Literal>) for the prelude.
 199 </Para>
 200 </ListItem></VarListEntry>
 201 <VarListEntry>
 202 <Term><Literal>include/</Literal></Term>
 203 <ListItem>
 204 <Para>
 205 A few C <Literal>&num;include</Literal> files.
 206 </Para>
 207 </ListItem></VarListEntry>
 208 </VariableList>
 209 </Para>
 210 </ListItem></VarListEntry>
 211 <VarListEntry>
 212 <Term><Literal>share/</Literal></Term>
 213 <ListItem>
 214 <Para>
 215 contains platform-independent support files
 216 for the installation.  Again, there is a sub-directory for each
 217 <Literal>fptools</Literal> project.
 218 </Para>
 219 </ListItem></VarListEntry>
 220 <VarListEntry>
 221 <Term><Literal>html/</Literal></Term>
 222 <ListItem>
 223 <Para>
 224 contains HTML documentation files (one
 225 sub-directory per project).
 226 </Para>
 227 </ListItem></VarListEntry>
 228 <VarListEntry>
 229 <Term><Literal>man/</Literal></Term>
 230 <ListItem>
 231 <Para>
 232 contains Unix manual pages.
 233 </Para>
 234 </ListItem></VarListEntry>
 235 </VariableList>
 236 </Para>
 237
 238 <Sect3 id="sec-install">
 239 <Title>Installing</Title>
 240
 241 <Para>
 242 OK, so let's assume that you have unpacked your chosen bundles into a
 243 scratch directory <Literal>fptools</Literal>. What next? Well, you will at least need
 244 to run the <Literal>configure</Literal><IndexTerm><Primary>configure</Primary></IndexTerm> script by changing your
 245 directory to <Literal>fptools</Literal> and typing <Literal>./configure</Literal>.  That should convert
 246 <Literal>Makefile.in</Literal> to <Literal>Makefile</Literal>.
 247 </Para>
 248
 249 <Para>
 250 <IndexTerm><Primary>installing in-place</Primary></IndexTerm>
 251 <IndexTerm><Primary>in-place installation</Primary></IndexTerm>
 252 You can now either start using the tools <Emphasis>in-situ</Emphasis> without going
 253 through any installation process, just type <Literal>make in-place</Literal> to set the
 254 tools up for this. You'll also want to add the path which <Literal>make</Literal> will
 255 now echo to your <Literal>PATH</Literal> environment variable. This option is useful if
 256 you simply want to try out the package and/or you don't have the
 257 necessary privileges (or inclination) to properly install the tools
 258 locally. Note that if you do decide to install the package `properly'
 259 at a later date, you have to go through the installation steps that
 260 follow.
 261 </Para>
 262
 263 <Para>
 264 To install an <Literal>fptools</Literal> package, you'll have to do the following:
 265 </Para>
 266
 267 <Para>
 268
 269 <OrderedList>
 270 <ListItem>
 271
 272 <Para>
 273  Edit the <Literal>Makefile</Literal> and check the settings of the following variables:
 274
 275 <IndexTerm><Primary>directories, installation</Primary></IndexTerm>
 276 <IndexTerm><Primary>installation directories</Primary></IndexTerm>
 277
 278 <VariableList>
 279
 280 <VarListEntry>
 281 <Term><Literal>platform</Literal></Term>
 282 <ListItem>
 283 <Para>
 284 the platform you are going to install for.
 285 </Para>
 286 </ListItem></VarListEntry>
 287 <VarListEntry>
 288 <Term><Literal>bindir</Literal></Term>
 289 <ListItem>
 290 <Para>
 291 the directory in which to install user-invokable
 292 binaries.
 293 </Para>
 294 </ListItem></VarListEntry>
 295 <VarListEntry>
 296 <Term><Literal>libdir</Literal></Term>
 297 <ListItem>
 298 <Para>
 299 the directory in which to install
 300 platform-dependent support files.
 301 </Para>
 302 </ListItem></VarListEntry>
 303 <VarListEntry>
 304 <Term><Literal>datadir</Literal></Term>
 305 <ListItem>
 306 <Para>
 307 the directory in which to install
 308 platform-independent support files.
 309 </Para>
 310 </ListItem></VarListEntry>
 311 <VarListEntry>
 312 <Term><Literal>infodir</Literal></Term>
 313 <ListItem>
 314 <Para>
 315 the directory in which to install Emacs info
 316 files.
 317 </Para>
 318 </ListItem></VarListEntry>
 319 <VarListEntry>
 320 <Term><Literal>htmldir</Literal></Term>
 321 <ListItem>
 322 <Para>
 323 the directory in which to install HTML
 324 documentation.
 325 </Para>
 326 </ListItem></VarListEntry>
 327 <VarListEntry>
 328 <Term><Literal>dvidir</Literal></Term>
 329 <ListItem>
 330 <Para>
 331 the directory in which to install DVI
 332 documentation.
 333 </Para>
 334 </ListItem></VarListEntry>
 335 </VariableList>
 336
 337 The values for these variables can be set through invocation of the
 338 <Command>configure</Command><IndexTerm><Primary>configure</Primary></IndexTerm>
 339 script that comes with the distribution, but doing an optical diff to
 340 see if the values match your expectations is always a Good Idea.
 341 </para>
 342
 343 <para>
 344 <Emphasis>Instead of running <Command>configure</Command>, it is
 345 perfectly OK to copy <Filename>Makefile.in</Filename> to
 346 <Filename>Makefile</Filename> and set all these variables directly
 347 yourself.  But do it right!</Emphasis>
 348 </Para>
 349
 350 </ListItem>
 351 <ListItem>
 352
 353 <Para>
 354 Run <Literal>make install</Literal>.  This <Emphasis>
 355 should</Emphasis> work with ordinary Unix
 356 <Literal>make</Literal>&mdash;no need for fancy stuff like GNU
 357 <Literal>make</Literal>.
 358
 359 </Para>
 360 </ListItem>
 361 <ListItem>
 362
 363 <Para>
 364 <Literal>rehash</Literal> (t?csh or zsh users), so your shell will see the new
 365 stuff in your bin directory.
 366
 367 </Para>
 368 </ListItem>
 369 <ListItem>
 370
 371 <Para>
 372  Once done, test your &ldquo;installation&rdquo; as suggested in
 373 <XRef LinkEnd="sec-GHC-test">.  Be sure to use a <Literal>-v</Literal>
 374 option, so you can see exactly what pathnames it's using.
 375
 376 If things don't work as expected, check the list of known pitfalls in
 377 the building guide.
 378 </Para>
 379 </ListItem>
 380
 381 </OrderedList>
 382
 383 </Para>
 384
 385 <Para>
 386 <IndexTerm><Primary>link, installed as ghc</Primary></IndexTerm>
 387 When installing the user-invokable binaries, this installation
 388 procedure will install GHC as <Literal>ghc-x.xx</Literal> where <Literal>x.xx</Literal> is the version
 389 number of GHC.  It will also make a link (in the binary installation
 390 directory) from <Literal>ghc</Literal> to <Literal>ghc-x.xx</Literal>.  If you install multiple versions
 391 of GHC then the last one &ldquo;wins&rdquo;, and &ldquo;<Literal>ghc</Literal>&rdquo; will invoke the last
 392 one installed.  You can change this manually if you want.  But
 393 regardless, <Literal>ghc-x.xx</Literal> should always invoke GHC version <Literal>x.xx</Literal>.
 394 </Para>
 395
 396 </Sect3>
 397
 398
 399 <Sect3>
 400 <Title>What bundles there are</Title>
 401
 402 <Para>
 403 <IndexTerm><Primary>bundles, binary</Primary></IndexTerm> There are
 404 plenty of &ldquo;non-basic&rdquo; GHC bundles.  The files for them are
 405 called
 406 <Literal>ghc-x.xx-<replaceable>bundle</replaceable>-<replaceable>platform</replaceable>.tar.gz</Literal>,
 407 where the <replaceable>platform</replaceable> is as above, and
 408 <replaceable>bundle</replaceable> is one of these:
 409 </Para>
 410
 411 <Para>
 412 <VariableList>
 413
 414 <VarListEntry>
 415 <Term><Literal>prof</Literal>:</Term>
 416 <ListItem>
 417 <Para>
 418 Profiling with cost-centres.  You probably want this.
 419 <IndexTerm><Primary>profiling bundles</Primary></IndexTerm>
 420 <IndexTerm><Primary>bundles, profiling</Primary></IndexTerm>
 421 </Para>
 422 </ListItem></VarListEntry>
 423 <VarListEntry>
 424 <Term><Literal>par</Literal>:</Term>
 425 <ListItem>
 426 <Para>
 427 Parallel Haskell features (sits on top of PVM).
 428 You'll want this if you're into that kind of thing.
 429 <IndexTerm><Primary>parallel bundles</Primary></IndexTerm>
 430 <IndexTerm><Primary>bundles, parallel</Primary></IndexTerm>
 431 </Para>
 432 </ListItem></VarListEntry>
 433 <VarListEntry>
 434 <Term><Literal>gran</Literal>:</Term>
 435 <ListItem>
 436 <Para>
 437 The &ldquo;GranSim&rdquo; parallel-Haskell simulator
 438 (hmm&hellip; mainly for implementors).
 439 <IndexTerm><Primary>bundles, gransim</Primary></IndexTerm>
 440 <IndexTerm><Primary>gransim bundles</Primary></IndexTerm>
 441 </Para>
 442 </ListItem></VarListEntry>
 443 <VarListEntry>
 444 <Term><Literal>ticky</Literal>:</Term>
 445 <ListItem>
 446 <Para>
 447 &ldquo;Ticky-ticky&rdquo; profiling; very detailed
 448 information about &ldquo;what happened when I ran this program&rdquo;&mdash;really
 449 for implementors.
 450 <IndexTerm><Primary>bundles, ticky-ticky</Primary></IndexTerm>
 451 <IndexTerm><Primary>ticky-ticky bundles</Primary></IndexTerm>
 452 </Para>
 453 </ListItem></VarListEntry>
 454 </VariableList>
 455 </Para>
 456
 457 <Para>
 458 One likely scenario is that you will grab <Emphasis>two</Emphasis>
 459 binary bundles&mdash;basic, and profiling.  We don't usually make the
 460 rest, although you can build them yourself from a source distribution.
 461 </Para>
 462
 463 <para>The various GHC bundles are designed to be unpacked into the
 464 same directory; then installing as per the directions above will
 465 install the whole lot in one go.  Note: you <emphasis>must</emphasis>
 466 at least have the basic GHC binary distribution bundle, these extra
 467 bundles won't install on their own.</para>
 468
 469 </Sect3>
 470
 471 <Sect3 id="sec-GHC-test">
 472 <Title>Testing that GHC seems to be working
 473 </Title>
 474
 475 <Para>
 476 <IndexTerm><Primary>testing a new GHC</Primary></IndexTerm>
 477 </Para>
 478
 479 <Para>
 480 The way to do this is, of course, to compile and run <Emphasis>this</Emphasis> program
 481 (in a file <Literal>Main.hs</Literal>):
 482 </Para>
 483
 484 <Para>
 485
 486 <ProgramListing>
 487 main = putStr "Hello, world!\n"
 488 </ProgramListing>
 489
 490 </Para>
 491
 492 <Para>
 493 Compile the program, using the <Literal>-v</Literal> (verbose) flag to verify that
 494 libraries, etc., are being found properly:
 495
 496 <Screen>
 497 % ghc -v -o hello Main.hs</Screen>
 498
 499 </Para>
 500
 501 <Para>
 502 Now run it:
 503
 504 <Screen>
 505 % ./hello
 506 Hello, world!</Screen>
 507
 508 </Para>
 509
 510 <Para>
 511 Some simple-but-profitable tests are to compile and run the notorious
 512 <Literal>nfib</Literal><IndexTerm><Primary>nfib</Primary></IndexTerm> program, using different numeric types.  Start with
 513 <Literal>nfib :: Int -&gt; Int</Literal>, and then try <Literal>Integer</Literal>, <Literal>Float</Literal>, <Literal>Double</Literal>,
 514 <Literal>Rational</Literal> and perhaps the overloaded version.  Code for this is
 515 distributed in <Literal>ghc/misc/examples/nfib/</Literal> in a source distribution.
 516 </Para>
 517
 518 <para>For more information on how to &ldquo;drive&rdquo; GHC, read
 519 on...</para>
 520
 521 </Sect3>
 522
 523 </Sect2>
 524
 525 </Sect1>
 526
 527
 528 <Sect1 id="sec-install-windows"><Title>Installing on Windows</Title>
 529
 530 <para>
 531 Getting the Glasgow Haskell Compiler (post 5.02) to run on Windows platforms is
 532 a snap: the Installshield does everything you need.
 533 </para>
 534
 535 <Sect2><Title>Installing GHC on Windows</Title>
 536
 537 <para>
 538 To install GHC, use the following steps:
 539 </para>
 540 <itemizedlist>
 541 <listitem><para>Download the Installshield <Filename>setup.exe</Filename>
 542 from the GHC download page
 543 <ULink
 544 URL="http://www.haskell.org/ghc">haskell.org</ULink>.
 545 </para></listitem>
 546
 547 <listitem><para>Run <Filename>setup.exe</Filename>.
 548 (If you have a previous version of GHC, Installshield will offer to "modify",
 549 or "remove" GHC.  Choose "remove"; then run <Filename>setup.exe</Filename> a
 550 second time.  This time it should offer to install.)
 551 </para>
 552 <para>
 553 At this point you should find GHCi and the GHC documentation are
 554 available in your Start menu under "Start/Programs/Glasgow Haskell Compiler".
 555 </para>
 556 </listitem>
 557
 558 <listitem><para>
 559 The final dialogue box from the install process tells you where GHC has
 560 been installed.  If you want to invoke GHC from a command line, add this
 561 to your PATH environment variable.  Usually, GHC installs into
 562 <Filename>c:/ghc/ghc-5.02</Filename>, though the last part of this path
 563 depends on which version of GHC you are installing, of course.
 564 You need to add <Filename>c:/ghc/ghc-5.02/bin</Filename> to your path if yo
 565 </para></listitem>
 566
 567 <listitem><para>
 568 GHC needs a directory in which to create, and later delete, temporary files.
 569 It uses the standard Windows procedure <literal>GetTempPath()</literal> to
 570 find a suitable directory.  This procedure returns:
 571 <itemizedlist>
 572 <listitem><para>The path in environment variable TMP,
 573 if TMP is set.</para></listitem>
 574 <listitem><para>Otherwise, the path in environment variable TEMP,
 575 if TEMP is set.</para></listitem>
 576 <listitem><para>Otherwise, there is a per-user default which varies
 577 between versions of Windows. On NT and XP-ish versions, it might
 578 be:
 579 <Filename>c:\Documents and Settings\&lt;username&gt;\Local Settings\Temp</filename>
 580 </para></listitem>
 581 </itemizedlist>
 582 The main point is that if you don't do anything GHC will work fine;
 583 but if you want to control where the directory is, you can do so by
 584 setting TMP or TEMP.
 585 </para></listitem>
 586
 587 <listitem>
 588 <Para>
 589 To test the fruits of your labour, try now to compile a simple
 590 Haskell program:
 591 </Para>
 592
 593 <Screen>
 594 bash$ cat main.hs
 595 module Main(main) where
 596
 597 main = putStrLn "Hello, world!"
 598 bash$ ghc -o main main.hs
 599 ..
 600 bash$ ./main
 601 Hello, world!
 602 bash$ </Screen>
 603 </listitem>
 604 </itemizedlist>
 605
 606 <para>
 607 You do <emphasis>not</emphasis> need the Cygwin toolchain, or anything
 608 else, to install and run GHC.
 609 </para>
 610 <Para>
 611 An installation of GHC requires about 140M of disk space.
 612 To run GHC comfortably, your machine should have at least
 613 64M of memory.
 614 </Para>
 615 </sect2>
 616
 617 <Sect2><title>Moving GHC around</title>
 618 <Para>
 619 At the moment, GHC installs in a fixed place (<Filename>c:/ghc/ghc-x.yy</Filename>,
 620 but once it is installed, you can freely move the entire GHC tree just by copying
 621 the <Filename>ghc-x.yy</Filename> directory.   (You may need to fix up
 622 the links in "Start/Programs/Glasgow Haskell Compiler" if you do this.)
 623 </para>
 624 <para>
 625 It is OK to put GHC tree in a directory whose path involves spaces.  However,
 626 don't do this if you use want to use GHC with the Cygwin tools,
 627 because Cygwin can get confused when this happpens.
 628 We havn't quite got to the bottom of this, but so far as we know it's not
 629 a problem with GHC itself.  Nevertheless, just to keep life simple we usually
 630 put GHC in a place with a space-free path.
 631 </Para>
 632 </sect2>
 633
 634 <Sect2 id="winfaq"><title>Installing ghc-win32 FAQ</title>
 635
 636 <QandASet>
 637
 638 <QandAEntry>
 639
 640 <Question>
 641 <Para>
 642 I'm having trouble with symlinks.
 643 </Para>
 644 </Question>
 645
 646 <Answer>
 647 <Para>
 648 Symlinks only work under Cygwin (<Xref LinkEnd="sec-install">), so binaries
 649 not linked to the Cygwin DLL, in particular those built for Mingwin, will not
 650 work with symlinks.
 651 </Para>
 652 </Answer>
 653
 654 </QandAEntry>
 655
 656 <QandAEntry>
 657
 658 <Question>
 659 <Para>
 660 I'm getting &ldquo;permission denied&rdquo; messages from the <Command>rm</Command> or
 661 <Command>mv</Command>.
 662 </Para>
 663 </Question>
 664
 665 <Answer>
 666 <Para>
 667 This can have various causes: trying to rename a directory when an Explorer
 668 window is open on it tends to fail. Closing the window generally cures the
 669 problem, but sometimes its cause is more mysterious, and logging off and back
 670 on or rebooting may be the quickest cure.
 671 </Para>
 672 </Answer>
 673
 674 </QandAEntry>
 675
 676 </QandASet>
 677
 678 <Para>
 679 Further information on using GHC under Windows can be found in <ULink
 680 URL="http://www.dcs.gla.ac.uk/~sof/ghc-win32.html">Sigbj&oslash;rn Finne's
 681 pages</ULink>. Note: ignore the installation instructions, which are rather
 682 out of date; the <Emphasis>Miscellaneous</Emphasis> section at the bottom of
 683 the page is of most interest, covering topics beyond the scope of this
 684 manual.
 685 </Para>
 686 </Sect2>
 687
 688 </Sect1>
 689
 690
 691 <Sect1 id="sec-install-files"><Title>The layout of installed files</Title>
 692
 693 <para>
 694 This section describes what files get installed where.  You don't need to know it
 695 if you are simply installing GHC, but it is vital information if you are changing
 696 the implementation.
 697 </para>
 698 <para> GHC is installed in two directory trees:</para>
 699 <variablelist>
 700 <varlistentry>
 701 <term>Binary directory</term>
 702 <listitem> <para> known as <Filename>$(bindir)</Filename>, holds executables that
 703 the user is expected to invoke.  Notably,
 704 <Filename>ghc</Filename> and <Filename>ghci</FileName>.  On Unix, this directory
 705 is typically something like <Filename>/usr/local/bin</Filename>.  On Windows,
 706 however, this directory is always <Filename>$(libdir)/bin</Filename>.
 707 </para>
 708 </listitem>
 709 </varlistentry>
 710 <varlistentry>
 711 <term>Library directory,</term>
 712 <listitem> <para> known as <Filename>$(libdir)</Filename>, holds all the
 713 support files needed to run GHC.  On Unix, this
 714 directory is usually something like <Filename>/usr/lib/ghc/ghc-5.02</Filename>. </para>
 715 </listitem>
 716 </varlistentry>
 717 </variablelist>
 718
 719 <para>
 720 When GHC runs, it must know where its library directory is.
 721 It finds this out in one of two ways:
 722 </para>
 723 <itemizedlist>
 724 <listitem>
 725 <para>
 726 <Filename>$(libdir)</Filename> is passed to GHC using the <option>-B</option> flag.
 727 On Unix (but not Windows), the installed <filename>ghc</filename> is just a one-line
 728 shell script that invokes the real GHC, passing a suitable <option>-B</option> flag.
 729 [All the user-supplied flags
 730 follow, and a later <option>-B</option> flag overrides an earlier one, so a user-supplied
 731 one wins.]
 732 </para>
 733 </listitem>
 734 <listitem>
 735 <para> On Windows (but not Unix), if no <option>-B</option> flag is given, GHC uses a system
 736 call to find the directory in which the running GHC executable lives, and derives
 737 <Filename>$(libdir)</Filename> from that. [Unix lacks such a system call.]
 738 </para>
 739 </listitem>
 740 </itemizedlist>
 741
 742 <sect2> <title>Layout of the library directory</title>
 743
 744 <para>The layout of the library directory is almost identical on
 745 Windows and Unix, as follows: layout:</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.bat
 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:</para>
 804 <itemizedlist>
 805 <listitem>
 806 <para>On Win32, the <filename>$(libdir)/bin</filename> directory contains user-visible binaries;
 807 add it to your <filename>PATH</filename>.  The <filename>ghci</filename> executable is a <filename>.bat</filename>
 808 file which invokes <filename>ghc</filename>.   </para>
 809
 810 <para>The GHC executable is the Real Thing (no intervening
 811 shell scripts or <filename>.bat</filename> files).
 812 Reason: we sometimes invoke GHC with very long command lines,
 813 and <filename>cmd.exe</filename> (which executes <filename>.bat</filename> files)
 814 truncates them.  [We assume people won't invoke ghci with very long
 815 command lines.]</para>
 816
 817 <para>On Unix, the user-invokable <filename>ghc</filename> invokes <filename>$(libdir)/ghc-<replaceable>version</replaceable></filename>,
 818 passing a suitable <option>-B</option> flag.
 819 </para>
 820 </listitem>
 821
 822         <listitem>
 823           <para><filename>$(libdir)</filename> also contains support
 824           binaries.  These are <emphasis>not</emphasis> expected to be
 825           on the user's <filename>PATH</filename>, but and are invoked
 826           directly by GHC.  In the Makefile system, this directory is
 827           also called <filename>$(libexecdir)</filename>, but
 828           <emphasis>you are not free to change it</emphasis>.  It must
 829           be the same as <filename>$(libdir)</filename>.</para>
 830         </listitem>
 831
 832 <listitem>
 833 <para>We distribute <filename>gcc</filename> with the Win32 distribution of GHC, so that users
 834 don't need to install <filename>gcc</filename>, nor need to care about which version it is.
 835 All <filename>gcc</filename>'s support files are kept in  <filename>$(libdir)/gcc-lib/</filename>.
 836 </para>
 837 </listitem>
 838
 839 <listitem>
 840 <para>Similarly, we distribute <filename>perl</filename> and a <filename>touch</filename>
 841 replacement (<filename>touchy.exe</filename>)
 842 with the Win32 distribution of GHC. </para>
 843 </listitem>
 844
 845         <listitem>
 846           <para>The support programs <filename>ghc-split</filename>
 847           and <filename>ghc-asm</filename> are Perl scripts.  The
 848           first line says <literal>#!/bin/perl</literal>; on Unix, the
 849           script is indeed invoked as a shell script, which invokes
 850           Perl; on Windows, GHC invokes
 851           <filename>$(libdir)/perl.exe</filename> directly, which
 852           treats the <literal>#!/bin/perl</literal> as a comment.
 853           Reason: on Windows we want to invoke the Perl distributed
 854           with GHC, rather than assume some installed one.  </para>
 855         </listitem>
 856 </itemizedlist>
 857
 858 </sect2>
 859
 860 </sect1>
 861
 862
 863 <Sect1 id="building-docs">
 864 <Title>Building the documentation</Title>
 865
 866 <Para>We use the DocBook DTD, which is widely used. Most shrink-wrapped
 867 distributions seem to be broken in one way or another; thanks to
 868 heroic efforts by Sven Panne and Manuel Chakravarty, we now support
 869 most of them, plus properly installed versions.
 870 </Para>
 871
 872 <Para>Instructions on installing and configuring the DocBook tools follow.
 873 </Para>
 874
 875 <Sect2>
 876 <Title>Installing the DocBook tools from RPMs</Title>
 877
 878 <Para>If you're using a system that can handle RedHat RPM packages,
 879 you can probably use the <ULink
 880 URL="http://sourceware.cygnus.com/docbook-tools/">Cygnus DocBook
 881 tools</ULink>, which is the most shrink-wrapped SGML suite that we
 882 could find. You need all the RPMs except for psgml (i.e.
 883 <Filename>docbook</Filename>, <Filename>jade</Filename>,
 884 <Filename>jadetex</Filename>, <Filename>sgmlcommon</Filename> and
 885 <Filename>stylesheets</Filename>). Note that most of these RPMs are
 886 architecture neutral, so are likely to be found in a
 887 <Filename>noarch</Filename> directory. The SuSE RPMs also work; the
 888 RedHat ones <Emphasis>don't</Emphasis> in RedHat 6.2 (7.0 and later
 889 should be OK), but they are easy to fix: just make a symlink from
 890 <Filename>/usr/lib/sgml/stylesheets/nwalsh-modular/lib/dblib.dsl</Filename>
 891 to <Filename>/usr/lib/sgml/lib/dblib.dsl</Filename>. </Para>
 892
 893 </Sect2>
 894
 895     <sect2>
 896       <title>Installing DocBook on FreeBSD</title>
 897
 898       <para>On FreeBSD systems, the easiest way to get DocBook up and
 899       running is to install it from the ports tree or a pre-compiled
 900       package (packages are available from your local FreeBSD mirror
 901       site).</para>
 902
 903       <para>To use the ports tree, do this:
 904 <screen>
 905       $ cd /usr/ports/textproc/docproj
 906       $ make install
 907 </screen>
 908       This installs the FreeBSD documentation project tools, which
 909       includes everything needed to format the GHC
 910       documentation.</para>
 911     </sect2>
 912
 913 <Sect2>
 914 <Title>Installing from binaries on Windows</Title>
 915
 916 <Para>It's a good idea to use Norman Walsh's <ULink
 917 URL="http://nwalsh.com/docbook/dsssl/doc/install.html">installation
 918 notes</ULink> as a guide. You should get version 3.1 of DocBook, and note
 919 that his file <Filename>test.sgm</Filename> won't work, as it needs version
 920 3.0. You should unpack Jade into <Filename>\Jade</Filename>, along with the
 921 entities, DocBook into <Filename>\docbook</Filename>, and the DocBook
 922 stylesheets into <Filename>\docbook\stylesheets</Filename> (so they actually
 923 end up in <Filename>\docbook\stylesheets\docbook</Filename>).
 924 </Para>
 925
 926 </Sect2>
 927
 928
 929 <Sect2>
 930 <Title>Installing the DocBook tools from source</Title>
 931
 932 <Sect3>
 933 <Title>Jade</Title>
 934
 935 <Para>Install <ULink URL="http://openjade.sourceforge.net/">OpenJade</ULink> (Windows binaries are available as well as sources). If you want DVI, PS, or PDF then install JadeTeX from the <Filename>dsssl</Filename>
 936 subdirectory. (If you get the error:
 937
 938 <Screen>
 939 ! LaTeX Error: Unknown option implicit=false' for package hyperref'.
 940 </Screen>
 941
 942 your version of <Command>hyperref</Command> is out of date; download it from
 943 CTAN (<Filename>macros/latex/contrib/supported/hyperref</Filename>), and
 944 make it, ensuring that you have first removed or renamed your old copy. If
 945 you start getting file not found errors when making the test for
 946 <Command>hyperref</Command>, you can abort at that point and proceed
 947 straight to <Command>make install</Command>, or enter them as
 948 <Filename>../</Filename><Emphasis>filename</Emphasis>.)
 949 </Para>
 950
 951 <Para>Make links from <Filename>virtex</Filename> to <Filename>jadetex</Filename>
 952 and <Filename>pdfvirtex</Filename> to <Filename>pdfjadetex</Filename>
 953 (otherwise DVI, PostScript and PDF output will not work). Copy
 954 <Filename>dsssl/*.{dtd,dsl}</Filename> and <Filename>catalog</Filename> to <Filename>/usr/[local/]lib/sgml</Filename>.
 955 </Para>
 956
 957 </Sect3>
 958
 959 <Sect3>
 960 <Title>DocBook and the DocBook stylesheets</Title>
 961
 962 <Para>Get a Zip of <ULink
 963 URL="http://www.oasis-open.org/docbook/sgml/3.1/index.html">DocBook</ULink>
 964 and install the contents in <Filename>/usr/[local/]/lib/sgml</Filename>.
 965 </Para>
 966
 967 <Para>Get the <ULink URL="http://nwalsh.com/docbook/dsssl/">DocBook
 968 stylesheets</ULink> and install in
 969 <Filename>/usr/[local/]lib/sgml/stylesheets</Filename> (thereby creating a
 970 subdirectory docbook). For indexing, copy or link <Filename>collateindex.pl</Filename> from the DocBook stylesheets archive in <Filename>bin</Filename> into a directory on your <Constant>PATH</Constant>.
 971 </Para>
 972
 973 <Para>Download the <ULink
 974 URL="http://www.oasis-open.org/cover/ISOEnts.zip">ISO
 975 entities</ULink> into <Filename>/usr/[local/]lib/sgml</Filename>.
 976 </Para>
 977
 978 </Sect3>
 979
 980 </Sect2>
 981
 982 <Sect2>
 983 <Title>Configuring the DocBook tools</Title>
 984
 985 <Para>Once the DocBook tools are installed, the configure script will detect them and set up the build system accordingly. If you have a system that isn't supported, let us know, and we'll try to help.
 986 </Para>
 987
 988 </Sect2>
 989
 990 <Sect2>
 991 <Title>Remaining problems</Title>
 992
 993 <Para>If you install from source, you'll get a pile of warnings of the form
 994
 995 <Screen>DTDDECL catalog entries are not supported</Screen>
 996
 997 every time you build anything. These can safely be ignored, but if you find them tedious you can get rid of them by removing all the <Constant>DTDDECL</Constant> entries from <Filename>docbook.cat</Filename>.
 998 </Para>
 999
1000 </Sect2>
1001
1002 </Sect1>
1003
1004 </Chapter>
1005
1006 <!-- Emacs stuff:
1007      ;;; Local Variables: ***
1008      ;;; mode: sgml ***
1009      ;;; sgml-parent-document: ("users_guide.sgml" "book" "chapter") ***
1010      ;;; End: ***
1011  -->