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>Most common OSes 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>Check the <ulink url="http://www.haskell.org/ghc/distribution_packages.html">distribution packages</ulink> page to see if there is a package available for your platform.</para>
  49     </sect2>
  50
  51 <sect2>
  52 <title>GHC binary distributions</title>
  53
  54 <para>
  55 <indexterm><primary>bundles of binary stuff</primary></indexterm>
  56 </para>
  57
  58 <para>
  59 Binary distributions come in &ldquo;bundles,&rdquo; called
  60 <literal>ghc-<replaceable>version</replaceable>-<replaceable>platform</replaceable>.tar.bz2</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:
  61 </para>
  62
  63 <para>
  64 <screen>
  65 % cd /your/scratch/space
  66 % bunzip2 &#60; ghc-<replaceable>version</replaceable>-<replaceable>platform</replaceable>.tar.bz2 | tar xvf -</screen>
  67 </para>
  68
  69 <para>
  70 Then you should find the bundle contents inside a single directory,
  71 <literal>ghc-<replaceable>version</replaceable></literal>.
  72 </para>
  73
  74 <sect3 id="install">
  75 <title>Installing</title>
  76
  77 <para>
  78 OK, so let's assume that you have unpacked your chosen bundles. What
  79 next? Well, you will first need to
  80 <literal>configure</literal><indexterm><primary>configure</primary></indexterm>
  81 the bundle by
  82 changing to the bundle's top-level directory
  83 and typing <literal>./configure</literal>. That should convert
  84 <literal>Makefile-vars.in</literal> to <literal>Makefile-vars</literal>.
  85 </para>
  86
  87 <para>
  88 The <literal>configure</literal> script takes a number of flags. The most
  89 commonly used is the
  90 <literal>--prefix=<replaceable>/path/to/install/in</replaceable></literal>
  91 flag, which tells the bundle that you want it to be installed in
  92 <replaceable>/path/to/install/in</replaceable> rather than the default
  93 location (/usr/local).
  94 To see all the flags that configure accepts, run
  95 <literal>configure --help</literal>.
  96 </para>
  97
  98 <para>
  99 Then do the following:
 100 </para>
 101
 102 <para>
 103
 104 <orderedlist>
 105 <listitem>
 106
 107 <para>
 108 Run <literal>make install</literal>.  This <emphasis>
 109 should</emphasis> work with ordinary Unix
 110 <literal>make</literal>&mdash;no need for fancy stuff like GNU
 111 <literal>make</literal>.
 112 </para>
 113 </listitem>
 114
 115 <listitem>
 116 <para>
 117 If appropriate, add the bin directory to your PATH, as instructed.
 118 </para>
 119 </listitem>
 120
 121 <listitem>
 122 <para>
 123 You may need to run <literal>rehash</literal> (t?csh or zsh users), in
 124 order for your shell to see the new stuff in your bin directory.
 125 </para>
 126 </listitem>
 127
 128 <listitem>
 129 <para>
 130  Once done, test your &ldquo;installation&rdquo; as suggested in
 131 <xref linkend="GHC-test"/>.  Be sure to use a <literal>-v</literal>
 132 option, so you can see exactly what pathnames it's using.
 133 If things don't work as expected, check the list of known pitfalls in
 134 the <ulink url="http://hackage.haskell.org/trac/ghc/wiki/Building">building guide</ulink>.
 135 </para>
 136
 137 </listitem>
 138
 139 </orderedlist>
 140
 141 </para>
 142
 143 <para>
 144 <indexterm><primary>link, installed as ghc</primary></indexterm>
 145 When installing the user-invokable binaries, this installation
 146 procedure will install GHC as <literal>ghc-x.xx</literal> where <literal>x.xx</literal> is the version
 147 number of GHC.  It will also make a link (in the binary installation
 148 directory) from <literal>ghc</literal> to <literal>ghc-x.xx</literal>.  If you install multiple versions
 149 of GHC then the last one &ldquo;wins&rdquo;, and &ldquo;<literal>ghc</literal>&rdquo; will invoke the last
 150 one installed.  You can change this manually if you want.  But
 151 regardless, <literal>ghc-x.xx</literal> should always invoke GHC version <literal>x.xx</literal>.
 152 </para>
 153
 154 </sect3>
 155
 156
 157 <sect3 id="GHC-test">
 158 <title>Testing that GHC seems to be working
 159 </title>
 160
 161 <para>
 162 <indexterm><primary>testing a new GHC</primary></indexterm>
 163 </para>
 164
 165 <para>
 166 The way to do this is, of course, to compile and run <emphasis>this</emphasis> program
 167 (in a file <literal>Main.hs</literal>):
 168 </para>
 169
 170 <para>
 171
 172 <programlisting>
 173 main = putStr "Hello, world!\n"
 174 </programlisting>
 175
 176 </para>
 177
 178 <para>
 179 Compile the program, using the <literal>-v</literal> (verbose) flag to verify that
 180 libraries, etc., are being found properly:
 181
 182 <screen>
 183 % ghc -v -o hello Main.hs</screen>
 184
 185 </para>
 186
 187 <para>
 188 Now run it:
 189
 190 <screen>
 191 % ./hello
 192 Hello, world!</screen>
 193
 194 </para>
 195
 196 <para>For more information on how to &ldquo;drive&rdquo; GHC, read
 197 on...</para>
 198
 199 </sect3>
 200
 201 </sect2>
 202
 203 </sect1>
 204
 205
 206 <sect1 id="install-windows"><title>Installing on Windows</title>
 207
 208 <para>
 209 Getting the Glasgow Haskell Compiler (post 5.02) to run on Windows platforms is
 210 a snap: the installer does everything you need.
 211 </para>
 212
 213 <sect2><title>Installing GHC on Windows</title>
 214
 215 <para>
 216 To install GHC, use the following steps:
 217 </para>
 218 <itemizedlist>
 219 <listitem><para>Download the installer
 220 from the
 221 <ulink
 222 url="http://www.haskell.org/ghc/download.html">GHC download page</ulink>.
 223 </para></listitem>
 224
 225 <listitem><para>Run the installer.
 226 On Windows, all of GHC's files are installed in a single directory.
 227 You can override it, but by default this directory is
 228 <filename>c:/ghc/ghc-<replaceable>version</replaceable></filename>.
 229 The executable binary for GHC will be installed in the
 230 <filename>bin/</filename> sub-directory of the installation directory.
 231 If you want to invoke GHC from a command line, add this
 232 to your <literal>$PATH</literal> environment variable.
 233 </para>
 234 <para>
 235 When installation is complete, you should find GHCi and the GHC
 236 documentation are available in your Start menu under
 237 "Start/All Programs/GHC/ghc-<replaceable>version</replaceable>".
 238 </para>
 239 </listitem>
 240
 241 <listitem><para>
 242 GHC needs a directory in which to create, and later delete, temporary files.
 243 It uses the standard Windows procedure <literal>GetTempPath()</literal> to
 244 find a suitable directory.  This procedure returns:
 245 <itemizedlist>
 246 <listitem><para>The path in the environment variable TMP,
 247 if TMP is set.</para></listitem>
 248 <listitem><para>Otherwise, the path in the environment variable TEMP,
 249 if TEMP is set.</para></listitem>
 250 <listitem><para>Otherwise, there is a per-user default which varies
 251 between versions of Windows. On NT and XP-ish versions, it might
 252 be:
 253 <filename>c:\Documents and Settings\&lt;username&gt;\Local Settings\Temp</filename>.
 254 </para></listitem>
 255 </itemizedlist>
 256 The main point is that if you don't do anything GHC will work fine,
 257 but if you want to control where the directory is, you can do so by
 258 setting TMP or TEMP.
 259 </para></listitem>
 260
 261 <listitem>
 262 <para>
 263 To test the fruits of your labour, try now to compile a simple
 264 Haskell program:
 265 </para>
 266
 267 <screen>
 268 bash$ cat main.hs
 269 module Main(main) where
 270
 271 main = putStrLn "Hello, world!"
 272 bash$ ghc -o main main.hs
 273 ..
 274 bash$ ./main
 275 Hello, world!
 276 bash$</screen>
 277 </listitem>
 278 </itemizedlist>
 279
 280 <para>
 281 You do <emphasis>not</emphasis> need the Cygwin toolchain, or anything
 282 else, to install and run GHC.
 283 </para>
 284 <para>
 285 An installation of GHC requires about 365M of disk space.
 286 To run GHC comfortably, your machine should have at least
 287 64M of memory.
 288 </para>
 289 </sect2>
 290
 291 <sect2><title>Moving GHC around</title>
 292 <para>
 293 Once GHC is installed, you can freely move the entire GHC tree just by copying
 294 the <filename>c:/ghc/ghc-<replaceable>version</replaceable></filename>
 295 directory. (You will need to fix up
 296 the links in "Start/All Programs/GHC/ghc-<replaceable>version</replaceable>"
 297 if you do this.)
 298 </para>
 299 <para>
 300 It is OK to put GHC tree in a directory whose path involves spaces.  However,
 301 don't do this if you use want to use GHC with the Cygwin tools,
 302 because Cygwin can get confused when this happens.
 303 We haven't quite got to the bottom of this, but so far as we know it's not
 304 a problem with GHC itself.  Nevertheless, just to keep life simple we usually
 305 put GHC in a place with a space-free path.
 306 </para>
 307 </sect2>
 308
 309 <sect2 id="winfaq">
 310 <title>Installing ghc-win32 FAQ</title>
 311
 312       <variablelist>
 313         <varlistentry>
 314           <term>I'm having trouble with symlinks.</term>
 315           <listitem>
 316             <para>Symlinks only work under Cygwin (<xref linkend="install" />),
 317           so binaries not linked to the Cygwin
 318               DLL, in particular those built for Mingwin, will not work with
 319               symlinks.</para>
 320           </listitem>
 321         </varlistentry>
 322
 323         <varlistentry>
 324           <term>I'm getting &ldquo;permission denied&rdquo; messages from the
 325             <command>rm</command> or <command>mv</command>.</term>
 326           <listitem>
 327             <para>This can have various causes: trying to rename a directory
 328               when an Explorer window is open on it tends to fail. Closing the
 329               window generally cures the problem, but sometimes its cause is
 330               more mysterious, and logging off and back on or rebooting may be
 331               the quickest cure.</para>
 332           </listitem>
 333         </varlistentry>
 334       </variablelist>
 335 </sect2>
 336
 337 </sect1>
 338
 339
 340 <sect1 id="install-files"><title>The layout of installed files</title>
 341
 342 <para>
 343 This section describes what files get installed where.  You don't need to know it
 344 if you are simply installing GHC, but it is vital information if you are changing
 345 the implementation.
 346 </para>
 347 <para> GHC is installed in two directory trees:</para>
 348 <variablelist>
 349 <varlistentry>
 350 <term>Library directory,</term>
 351 <listitem> <para> known as <filename>$(libdir)</filename>, holds all the
 352 support files needed to run GHC.  On Unix, this
 353 directory is usually something like <filename>/usr/lib/ghc/ghc-5.02</filename>. </para>
 354 </listitem>
 355 </varlistentry>
 356 <varlistentry>
 357 <term>Binary directory</term>
 358 <listitem> <para> known as <filename>$(bindir)</filename>, holds executables that
 359 the user is expected to invoke.
 360 Notably, it contains
 361 <filename>ghc</filename> and <filename>ghci</filename>.  On Unix, this directory
 362 can be anywhere, but is typically something like <filename>/usr/local/bin</filename>.  On Windows,
 363 however, this directory <emphasis>must be</emphasis> <filename>$(libdir)/bin</filename>.
 364 </para>
 365 </listitem>
 366 </varlistentry>
 367 </variablelist>
 368
 369 <para>
 370 When GHC runs, it must know where its library directory is.
 371 It finds this out in one of two ways:
 372 </para>
 373 <itemizedlist>
 374 <listitem>
 375 <para>
 376 <filename>$(libdir)</filename> is passed to GHC using the <option>-B</option> flag.
 377 On Unix (but not Windows), the installed <filename>ghc</filename> is just a one-line
 378 shell script that invokes the real GHC, passing a suitable <option>-B</option> flag.
 379 [All the user-supplied flags
 380 follow, and a later <option>-B</option> flag overrides an earlier one, so a user-supplied
 381 one wins.]
 382 </para>
 383 </listitem>
 384 <listitem>
 385 <para> On Windows (but not Unix), if no <option>-B</option> flag is given, GHC uses a system
 386 call to find the directory in which the running GHC executable lives, and derives
 387 <filename>$(libdir)</filename> from that. [Unix lacks such a system call.]
 388 That is why <filename>$(bindir)</filename> must be <filename>$(libdir)/bin</filename>.
 389 </para>
 390 </listitem>
 391 </itemizedlist>
 392
 393 <sect2> <title>The binary directory</title>
 394
 395 <para>The binary directory, <filename>$(bindir)</filename>, contains user-visible
 396 executables, notably <filename>ghc</filename> and <filename>ghci</filename>.
 397 You should add it to your <literal>$PATH</literal>.
 398 </para>
 399
 400 <para>On Unix, the user-invokable <filename>ghc</filename> invokes <filename>$(libdir)/ghc-<replaceable>version</replaceable></filename>,
 401 passing a suitable <option>-B</option> flag to tell <filename>ghc-<replaceable>version</replaceable></filename> where
 402 <filename>$(libdir)</filename> is.
 403 Similarly <filename>ghci</filename>, except the extra flag <literal>--interactive</literal> is passed.
 404 </para>
 405
 406 <para>On Win32, the user-invokable <filename>ghc</filename> binary
 407 is the Real Thing (no intervening
 408 shell scripts or <filename>.bat</filename> files).
 409 Reason: we sometimes invoke GHC with very long command lines,
 410 and <filename>cmd.exe</filename> (which executes <filename>.bat</filename> files)
 411 truncates them.  Similarly <filename>ghci</filename> is a C wrapper program that invokes <filename>ghc --interactive</filename>
 412 (passing on all other arguments), not a <filename>.bat</filename> file.
 413 </para>
 414
 415
 416 </sect2>
 417
 418 <sect2> <title>The library directory</title>
 419
 420 <para>The layout of the library directory, <filename>$(libdir)</filename>,
 421 is almost identical on
 422 Windows and Unix, as follows.  Differences between Windows and Unix
 423 are annotated <literal>[Win32 only]</literal> and are commented below.</para>
 424
 425 <programlisting>
 426   $(libdir)/
 427     package.conf           GHC package configuration
 428     ghc-usage.txt          Message displayed by ghc &ndash;&ndash;help
 429     ghci-usage.txt         Message displayed by ghci &ndash;&ndash;help
 430
 431     bin/                   [Win32 only]  User-visible binaries
 432         ghc.exe
 433         ghci.exe
 434
 435     unlit                  Remove literate markup
 436
 437     touchy.exe             [Win32 only]
 438     perl.exe               [Win32 only]
 439     gcc.exe                [Win32 only]
 440
 441     ghc-x.xx               GHC executable [Unix only]
 442
 443     ghc-split              Asm code splitter
 444     ghc-asm                Asm code mangler
 445
 446     gcc-lib/               [Win32 only] Support files for gcc
 447         specs              gcc configuration
 448
 449         cpp0.exe           gcc support binaries
 450         as.exe
 451         ld.exe
 452
 453         crt0.o              Standard
 454            ..etc..          binaries
 455
 456         libmingw32.a        Standard
 457            ..etc..          libraries
 458
 459         *.h                 Include files
 460
 461     hslibs-imports/         GHC interface files for the...
 462         ghc/*.hi            ...'ghc' library
 463
 464     include/                 C header files
 465         StgMacros.h           GHC-specific
 466         ..etc..               header files
 467
 468         mingw/*.h            [Win32 only] Mingwin header files
 469
 470     lib/                    GHC's library
 471         base-2.1
 472         ..etc..
 473
 474     libHSrts*.a             GHC RTS archive
 475     libHSghc.a              GHC package archive
 476
 477     HSrts.o                 GHC RTS linkable, used by ghci
 478     HSghc.o                 GHC package linkable, used by ghci
 479 </programlisting>
 480
 481 <para>Note that:
 482 <itemizedlist>
 483
 484         <listitem>
 485           <para><filename>$(libdir)</filename> also contains support
 486           binaries.  These are <emphasis>not</emphasis> expected to be
 487           on the user's <filename>PATH</filename>, but are invoked
 488           directly by GHC.  In the Makefile system, this directory is
 489           also called <filename>$(libexecdir)</filename>, but
 490           <emphasis>you are not free to change it</emphasis>.  It must
 491           be the same as <filename>$(libdir)</filename>.</para>
 492         </listitem>
 493
 494 <listitem>
 495 <para>We distribute <filename>gcc</filename> with the Win32 distribution of GHC, so that users
 496 don't need to install <filename>gcc</filename>, nor need to care about which version it is.
 497 All <filename>gcc</filename>'s support files are kept in  <filename>$(libdir)/gcc-lib/</filename>.
 498 </para>
 499 </listitem>
 500
 501 <listitem>
 502 <para>Similarly, we distribute <filename>perl</filename> and a <filename>touch</filename>
 503 replacement (<filename>touchy.exe</filename>)
 504 with the Win32 distribution of GHC. </para>
 505 </listitem>
 506
 507         <listitem>
 508           <para>The support programs <filename>ghc-split</filename>
 509           and <filename>ghc-asm</filename> are Perl scripts.  The
 510           first line says <literal>#!/usr/bin/perl</literal>; on Unix, the
 511           script is indeed invoked as a shell script, which invokes
 512           Perl; on Windows, GHC invokes
 513           <filename>$(libdir)/perl.exe</filename> directly, which
 514           treats the <literal>#!/usr/bin/perl</literal> as a comment.
 515           Reason: on Windows we want to invoke the Perl distributed
 516           with GHC, rather than assume some installed one.  </para>
 517         </listitem>
 518 </itemizedlist>
 519 </para>
 520
 521 </sect2>
 522
 523 </sect1>
 524
 525 </chapter>
 526
 527 <!-- Emacs stuff:
 528      ;;; Local Variables: ***
 529      ;;; mode: xml ***
 530      ;;; sgml-parent-document: ("users_guide.xml" "book" "chapter") ***
 531      ;;; End: ***
 532  -->