+++ /dev/null
-<?xml version="1.0" encoding="iso-8859-1"?>
-<chapter id="installing-bin-distrib">
- <title>Installing GHC</title>
-<indexterm><primary>binary installations</primary></indexterm>
-<indexterm><primary>installation, of binaries</primary></indexterm>
-
-<para>
-Installing from binary distributions is easiest, and recommended!
-(Why binaries? Because GHC is a Haskell compiler written in Haskell,
-so you've got to bootstrap it somehow. We provide machine-generated
-C-files-from-Haskell for this purpose, but it's really quite a pain to
-use them. If you must build GHC from its sources, using a
-binary-distributed GHC to do so is a sensible way to proceed.)
-</para>
-
-<para>This guide is in several parts:</para>
-
- <itemizedlist>
- <listitem>
- <para> Installing on Unix-a-likes (<xref
- linkend="unix-a-likes"/>). </para>
- </listitem>
- <listitem>
- <para> Installing on Windows (<xref
- linkend="install-windows"/>). </para>
- </listitem>
- <listitem>
- <para> The layout of installed files (<xref
- linkend="install-files"/>). You don't need to know this to
- install GHC, but it's useful if you are changing the
- implementation.</para>
- </listitem>
- </itemizedlist>
-
- <sect1 id="unix-a-likes"><title>Installing on Unix-a-likes</title>
-
- <sect2>
- <title>When a platform-specific package is available</title>
-
- <para>Most common OSes provide GHC binaries packaged
- using the native package format for the platform. This is
- likely to be by far the best way to install GHC for your
- platform if one of these packages is available, since
- dependencies will automatically be handled and the package
- system normally provides a way to uninstall the package at a
- later date.</para>
-
- <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>
- </sect2>
-
-<sect2>
-<title>GHC binary distributions</title>
-
-<para>
-<indexterm><primary>bundles of binary stuff</primary></indexterm>
-</para>
-
-<para>
-Binary distributions come in “bundles,” called
-<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:
-</para>
-
-<para>
-<screen>
-% cd /your/scratch/space
-% bunzip2 < ghc-<replaceable>version</replaceable>-<replaceable>platform</replaceable>.tar.bz2 | tar xvf -</screen>
-</para>
-
-<para>
-Then you should find the bundle contents inside a single directory,
-<literal>ghc-<replaceable>version</replaceable></literal>.
-</para>
-
-<sect3 id="install">
-<title>Installing</title>
-
-<para>
-OK, so let's assume that you have unpacked your chosen bundles. What
-next? Well, you will first need to
-<literal>configure</literal><indexterm><primary>configure</primary></indexterm>
-the bundle by
-changing to the bundle's top-level directory
-and typing <literal>./configure</literal>. That should convert
-<literal>Makefile-vars.in</literal> to <literal>Makefile-vars</literal>.
-</para>
-
-<para>
-The <literal>configure</literal> script takes a number of flags. The most
-commonly used is the
-<literal>--prefix=<replaceable>/path/to/install/in</replaceable></literal>
-flag, which tells the bundle that you want it to be installed in
-<replaceable>/path/to/install/in</replaceable> rather than the default
-location (/usr/local).
-To see all the flags that configure accepts, run
-<literal>configure --help</literal>.
-</para>
-
-<para>
-Then do the following:
-</para>
-
-<para>
-
-<orderedlist>
-<listitem>
-
-<para>
-Run <literal>make install</literal>. This <emphasis>
-should</emphasis> work with ordinary Unix
-<literal>make</literal>—no need for fancy stuff like GNU
-<literal>make</literal>.
-</para>
-</listitem>
-
-<listitem>
-<para>
-If appropriate, add the bin directory to your PATH, as instructed.
-</para>
-</listitem>
-
-<listitem>
-<para>
-You may need to run <literal>rehash</literal> (t?csh or zsh users), in
-order for your shell to see the new stuff in your bin directory.
-</para>
-</listitem>
-
-<listitem>
-<para>
- Once done, test your “installation” as suggested in
-<xref linkend="GHC-test"/>. Be sure to use a <literal>-v</literal>
-option, so you can see exactly what pathnames it's using.
-If things don't work as expected, check the list of known pitfalls in
-the <ulink url="http://hackage.haskell.org/trac/ghc/wiki/Building">building guide</ulink>.
-</para>
-
-</listitem>
-
-</orderedlist>
-
-</para>
-
-<para>
-<indexterm><primary>link, installed as ghc</primary></indexterm>
-When installing the user-invokable binaries, this installation
-procedure will install GHC as <literal>ghc-x.xx</literal> where <literal>x.xx</literal> is the version
-number of GHC. It will also make a link (in the binary installation
-directory) from <literal>ghc</literal> to <literal>ghc-x.xx</literal>. If you install multiple versions
-of GHC then the last one “wins”, and “<literal>ghc</literal>” will invoke the last
-one installed. You can change this manually if you want. But
-regardless, <literal>ghc-x.xx</literal> should always invoke GHC version <literal>x.xx</literal>.
-</para>
-
-</sect3>
-
-
-<sect3 id="GHC-test">
-<title>Testing that GHC seems to be working
-</title>
-
-<para>
-<indexterm><primary>testing a new GHC</primary></indexterm>
-</para>
-
-<para>
-The way to do this is, of course, to compile and run <emphasis>this</emphasis> program
-(in a file <literal>Main.hs</literal>):
-</para>
-
-<para>
-
-<programlisting>
-main = putStr "Hello, world!\n"
-</programlisting>
-
-</para>
-
-<para>
-Compile the program, using the <literal>-v</literal> (verbose) flag to verify that
-libraries, etc., are being found properly:
-
-<screen>
-% ghc -v -o hello Main.hs</screen>
-
-</para>
-
-<para>
-Now run it:
-
-<screen>
-% ./hello
-Hello, world!</screen>
-
-</para>
-
-<para>For more information on how to “drive” GHC, read
-on...</para>
-
-</sect3>
-
-</sect2>
-
-</sect1>
-
-
-<sect1 id="install-windows"><title>Installing on Windows</title>
-
-<para>
-Getting the Glasgow Haskell Compiler (post 5.02) to run on Windows platforms is
-a snap: the installer does everything you need.
-</para>
-
-<sect2><title>Installing GHC on Windows</title>
-
-<para>
-To install GHC, use the following steps:
-</para>
-<itemizedlist>
-<listitem><para>Download the installer
-from the
-<ulink
-url="http://www.haskell.org/ghc/download.html">GHC download page</ulink>.
-</para></listitem>
-
-<listitem><para>Run the installer.
-On Windows, all of GHC's files are installed in a single directory.
-You can override it, but by default this directory is
-<filename>c:/ghc/ghc-<replaceable>version</replaceable></filename>.
-The executable binary for GHC will be installed in the
-<filename>bin/</filename> sub-directory of the installation directory.
-If you want to invoke GHC from a command line, add this
-to your <literal>$PATH</literal> environment variable.
-</para>
-<para>
-When installation is complete, you should find GHCi and the GHC
-documentation are available in your Start menu under
-"Start/All Programs/GHC/ghc-<replaceable>version</replaceable>".
-</para>
-</listitem>
-
-<listitem><para>
-GHC needs a directory in which to create, and later delete, temporary files.
-It uses the standard Windows procedure <literal>GetTempPath()</literal> to
-find a suitable directory. This procedure returns:
-<itemizedlist>
-<listitem><para>The path in the environment variable TMP,
-if TMP is set.</para></listitem>
-<listitem><para>Otherwise, the path in the environment variable TEMP,
-if TEMP is set.</para></listitem>
-<listitem><para>Otherwise, there is a per-user default which varies
-between versions of Windows. On NT and XP-ish versions, it might
-be:
-<filename>c:\Documents and Settings\<username>\Local Settings\Temp</filename>.
-</para></listitem>
-</itemizedlist>
-The main point is that if you don't do anything GHC will work fine,
-but if you want to control where the directory is, you can do so by
-setting TMP or TEMP.
-</para></listitem>
-
-<listitem>
-<para>
-To test the fruits of your labour, try now to compile a simple
-Haskell program:
-</para>
-
-<screen>
-bash$ cat main.hs
-module Main(main) where
-
-main = putStrLn "Hello, world!"
-bash$ ghc -o main main.hs
-..
-bash$ ./main
-Hello, world!
-bash$</screen>
-</listitem>
-</itemizedlist>
-
-<para>
-You do <emphasis>not</emphasis> need the Cygwin toolchain, or anything
-else, to install and run GHC.
-</para>
-<para>
-An installation of GHC requires about 365M of disk space.
-To run GHC comfortably, your machine should have at least
-64M of memory.
-</para>
-</sect2>
-
-<sect2><title>Moving GHC around</title>
-<para>
-Once GHC is installed, you can freely move the entire GHC tree just by copying
-the <filename>c:/ghc/ghc-<replaceable>version</replaceable></filename>
-directory. (You will need to fix up
-the links in "Start/All Programs/GHC/ghc-<replaceable>version</replaceable>"
-if you do this.)
-</para>
-<para>
-It is OK to put GHC tree in a directory whose path involves spaces. However,
-don't do this if you use want to use GHC with the Cygwin tools,
-because Cygwin can get confused when this happens.
-We haven't quite got to the bottom of this, but so far as we know it's not
-a problem with GHC itself. Nevertheless, just to keep life simple we usually
-put GHC in a place with a space-free path.
-</para>
-</sect2>
-
-<sect2 id="winfaq">
-<title>Installing ghc-win32 FAQ</title>
-
- <variablelist>
- <varlistentry>
- <term>I'm having trouble with symlinks.</term>
- <listitem>
- <para>Symlinks only work under Cygwin (<xref linkend="install" />),
- so binaries not linked to the Cygwin
- DLL, in particular those built for Mingwin, will not work with
- symlinks.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>I'm getting “permission denied” messages from the
- <command>rm</command> or <command>mv</command>.</term>
- <listitem>
- <para>This can have various causes: trying to rename a directory
- when an Explorer window is open on it tends to fail. Closing the
- window generally cures the problem, but sometimes its cause is
- more mysterious, and logging off and back on or rebooting may be
- the quickest cure.</para>
- </listitem>
- </varlistentry>
- </variablelist>
-</sect2>
-
-</sect1>
-
-
-<sect1 id="install-files"><title>The layout of installed files</title>
-
-<para>
-This section describes what files get installed where. You don't need to know it
-if you are simply installing GHC, but it is vital information if you are changing
-the implementation.
-</para>
-<para> GHC is installed in two directory trees:</para>
-<variablelist>
-<varlistentry>
-<term>Library directory,</term>
-<listitem> <para> known as <filename>$(libdir)</filename>, holds all the
-support files needed to run GHC. On Unix, this
-directory is usually something like <filename>/usr/lib/ghc/ghc-5.02</filename>. </para>
-</listitem>
-</varlistentry>
-<varlistentry>
-<term>Binary directory</term>
-<listitem> <para> known as <filename>$(bindir)</filename>, holds executables that
-the user is expected to invoke.
-Notably, it contains
-<filename>ghc</filename> and <filename>ghci</filename>. On Unix, this directory
-can be anywhere, but is typically something like <filename>/usr/local/bin</filename>. On Windows,
-however, this directory <emphasis>must be</emphasis> <filename>$(libdir)/bin</filename>.
-</para>
-</listitem>
-</varlistentry>
-</variablelist>
-
-<para>
-When GHC runs, it must know where its library directory is.
-It finds this out in one of two ways:
-</para>
-<itemizedlist>
-<listitem>
-<para>
-<filename>$(libdir)</filename> is passed to GHC using the <option>-B</option> flag.
-On Unix (but not Windows), the installed <filename>ghc</filename> is just a one-line
-shell script that invokes the real GHC, passing a suitable <option>-B</option> flag.
-[All the user-supplied flags
-follow, and a later <option>-B</option> flag overrides an earlier one, so a user-supplied
-one wins.]
-</para>
-</listitem>
-<listitem>
-<para> On Windows (but not Unix), if no <option>-B</option> flag is given, GHC uses a system
-call to find the directory in which the running GHC executable lives, and derives
-<filename>$(libdir)</filename> from that. [Unix lacks such a system call.]
-That is why <filename>$(bindir)</filename> must be <filename>$(libdir)/bin</filename>.
-</para>
-</listitem>
-</itemizedlist>
-
-<sect2> <title>The binary directory</title>
-
-<para>The binary directory, <filename>$(bindir)</filename>, contains user-visible
-executables, notably <filename>ghc</filename> and <filename>ghci</filename>.
-You should add it to your <literal>$PATH</literal>.
-</para>
-
-<para>On Unix, the user-invokable <filename>ghc</filename> invokes <filename>$(libdir)/ghc-<replaceable>version</replaceable></filename>,
-passing a suitable <option>-B</option> flag to tell <filename>ghc-<replaceable>version</replaceable></filename> where
-<filename>$(libdir)</filename> is.
-Similarly <filename>ghci</filename>, except the extra flag <literal>--interactive</literal> is passed.
-</para>
-
-<para>On Win32, the user-invokable <filename>ghc</filename> binary
-is the Real Thing (no intervening
-shell scripts or <filename>.bat</filename> files).
-Reason: we sometimes invoke GHC with very long command lines,
-and <filename>cmd.exe</filename> (which executes <filename>.bat</filename> files)
-truncates them. Similarly <filename>ghci</filename> is a C wrapper program that invokes <filename>ghc --interactive</filename>
-(passing on all other arguments), not a <filename>.bat</filename> file.
-</para>
-
-
-</sect2>
-
-<sect2> <title>The library directory</title>
-
-<para>The layout of the library directory, <filename>$(libdir)</filename>,
-is almost identical on
-Windows and Unix, as follows. Differences between Windows and Unix
-are annotated <literal>[Win32 only]</literal> and are commented below.</para>
-
-<programlisting>
- $(libdir)/
- package.conf GHC package configuration
- ghc-usage.txt Message displayed by ghc ––help
- ghci-usage.txt Message displayed by ghci ––help
-
- bin/ [Win32 only] User-visible binaries
- ghc.exe
- ghci.exe
-
- unlit Remove literate markup
-
- touchy.exe [Win32 only]
- perl.exe [Win32 only]
- gcc.exe [Win32 only]
-
- ghc-x.xx GHC executable [Unix only]
-
- ghc-split Asm code splitter
- ghc-asm Asm code mangler
-
- gcc-lib/ [Win32 only] Support files for gcc
- specs gcc configuration
-
- cpp0.exe gcc support binaries
- as.exe
- ld.exe
-
- crt0.o Standard
- ..etc.. binaries
-
- libmingw32.a Standard
- ..etc.. libraries
-
- *.h Include files
-
- hslibs-imports/ GHC interface files for the...
- ghc/*.hi ...'ghc' library
-
- include/ C header files
- StgMacros.h GHC-specific
- ..etc.. header files
-
- mingw/*.h [Win32 only] Mingwin header files
-
- lib/ GHC's library
- base-2.1
- ..etc..
-
- libHSrts*.a GHC RTS archive
- libHSghc.a GHC package archive
-
- HSrts.o GHC RTS linkable, used by ghci
- HSghc.o GHC package linkable, used by ghci
-</programlisting>
-
-<para>Note that:
-<itemizedlist>
-
- <listitem>
- <para><filename>$(libdir)</filename> also contains support
- binaries. These are <emphasis>not</emphasis> expected to be
- on the user's <filename>PATH</filename>, but are invoked
- directly by GHC. In the Makefile system, this directory is
- also called <filename>$(libexecdir)</filename>, but
- <emphasis>you are not free to change it</emphasis>. It must
- be the same as <filename>$(libdir)</filename>.</para>
- </listitem>
-
-<listitem>
-<para>We distribute <filename>gcc</filename> with the Win32 distribution of GHC, so that users
-don't need to install <filename>gcc</filename>, nor need to care about which version it is.
-All <filename>gcc</filename>'s support files are kept in <filename>$(libdir)/gcc-lib/</filename>.
-</para>
-</listitem>
-
-<listitem>
-<para>Similarly, we distribute <filename>perl</filename> and a <filename>touch</filename>
-replacement (<filename>touchy.exe</filename>)
-with the Win32 distribution of GHC. </para>
-</listitem>
-
- <listitem>
- <para>The support programs <filename>ghc-split</filename>
- and <filename>ghc-asm</filename> are Perl scripts. The
- first line says <literal>#!/usr/bin/perl</literal>; on Unix, the
- script is indeed invoked as a shell script, which invokes
- Perl; on Windows, GHC invokes
- <filename>$(libdir)/perl.exe</filename> directly, which
- treats the <literal>#!/usr/bin/perl</literal> as a comment.
- Reason: on Windows we want to invoke the Perl distributed
- with GHC, rather than assume some installed one. </para>
- </listitem>
-</itemizedlist>
-</para>
-
-</sect2>
-
-</sect1>
-
-</chapter>
-
-<!-- Emacs stuff:
- ;;; Local Variables: ***
- ;;; mode: xml ***
- ;;; sgml-parent-document: ("users_guide.xml" "book" "chapter") ***
- ;;; End: ***
- -->
projects / ghc-hetmet.git / commitdiff