--- /dev/null
+<?xml version="1.0" encoding="iso-8859-1"?>
+<chapter id="introduction-GHC">
+ <title>Introduction to GHC</title>
+
+ <para>This is a guide to using the Glasgow Haskell Compiler (GHC):
+ an interactive and batch compilation system for the <ulink
+ url="http://www.haskell.org/">Haskell 98</ulink>
+ language.</para>
+
+ <para>GHC has two main components: an interactive Haskell
+ interpreter (also known as GHCi), described in <xref
+ linkend="ghci"/>, and a batch compiler, described throughout <xref
+ linkend="using-ghc"/>. In fact, GHC consists of a single program
+ which is just run with different options to provide either the
+ interactive or the batch system.</para>
+
+ <para>The batch compiler can be used alongside GHCi: compiled
+ modules can be loaded into an interactive session and used in the
+ same way as interpreted code, and in fact when using GHCi most of
+ the library code will be pre-compiled. This means you get the best
+ of both worlds: fast pre-compiled library code, and fast compile
+ turnaround for the parts of your program being actively
+ developed.</para>
+
+ <para>GHC supports numerous language extensions, including
+ concurrency, a foreign function interface, exceptions, type system
+ extensions such as multi-parameter type classes, local universal and
+ existential quantification, functional dependencies, scoped type
+ variables and explicit unboxed types. These are all described in
+ <xref linkend="ghc-language-features"/>.</para>
+
+ <para>GHC has a comprehensive optimiser, so when you want to Really
+ Go For It (and you've got time to spare) GHC can produce pretty fast
+ code. Alternatively, the default option is to compile as fast as
+ possible while not making too much effort to optimise the generated
+ code (although GHC probably isn't what you'd describe as a fast
+ compiler :-).</para>
+
+ <para>GHC's profiling system supports “cost centre
+ stacks”: a way of seeing the profile of a Haskell program in a
+ call-graph like structure. See <xref linkend="profiling"/> for more
+ details.</para>
+
+ <para>GHC comes with a large collection of libraries, with
+ everything from parser combinators to networking. The libraries are
+ described in separate documentation.</para>
+
+ <sect1 id="mailing-lists-GHC">
+ <title>Meta-information: Web sites, mailing lists, etc.</title>
+
+ <indexterm><primary>mailing lists, Glasgow Haskell</primary></indexterm>
+ <indexterm><primary>Glasgow Haskell mailing lists</primary></indexterm>
+
+ <para>On the World-Wide Web, there are several URLs of likely
+ interest:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para><ulink url="http://www.haskell.org/" >Haskell home
+ page</ulink></para>
+ </listitem>
+
+ <listitem>
+ <para><ulink url="http://www.haskell.org/ghc/">GHC home
+ page</ulink></para>
+ </listitem>
+
+ <listitem>
+ <para><ulink
+ url="http://www.cs.nott.ac.uk/~gmh/faq.html">comp.lang.functional
+ FAQ</ulink></para>
+ </listitem>
+
+ </itemizedlist>
+
+ <para>We run the following mailing lists about Glasgow Haskell.
+ We encourage you to join, as you feel is appropriate.</para>
+
+ <variablelist>
+ <varlistentry>
+ <term>glasgow-haskell-users:</term>
+ <listitem>
+ <para>This list is for GHC users to chat among themselves.
+ If you have a specific question about GHC, please check the
+ FAQ first (<xref linkend="faq"/>).</para>
+
+ <variablelist>
+ <varlistentry>
+ <term>list email address:</term>
+ <listitem>
+ <para><email>glasgow-haskell-users@haskell.org</email></para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>subscribe at:</term>
+ <listitem>
+ <para><ulink
+ url="http://www.haskell.org/mailman/listinfo/glasgow-haskell-users"><literal>http://www.haskell.org/mailman/listinfo/glasgow-haskell-users</literal></ulink>.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>admin email address:</term>
+ <listitem>
+ <para><email>glasgow-haskell-users-admin@haskell.org</email></para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>list archives:</term>
+ <listitem>
+ <para><ulink
+ url="http://www.haskell.org/pipermail/glasgow-haskell-users/"><literal>http://www.haskell.org/pipermail/glasgow-haskell-users/</literal></ulink></para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>glasgow-haskell-bugs:</term>
+ <listitem>
+ <para>Send bug reports for GHC to this address! The sad and
+ lonely people who subscribe to this list will muse upon
+ what's wrong and what you might do about it.</para>
+
+ <variablelist>
+ <varlistentry>
+ <term>list email address:</term>
+ <listitem>
+ <para><email>glasgow-haskell-bugs@haskell.org</email></para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>subscribe at:</term>
+ <listitem>
+ <para><ulink
+ url="http://www.haskell.org/mailman/listinfo/glasgow-haskell-bugs"><literal>http://www.haskell.org/mailman/listinfo/glasgow-haskell-bugs</literal></ulink>.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>admin email address:</term>
+ <listitem>
+ <para><email>glasgow-haskell-bugs-admin@haskell.org</email></para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>list archives:</term>
+ <listitem>
+ <para><ulink
+ url="http://www.haskell.org/pipermail/glasgow-haskell-bugs/"><literal>http://www.haskell.org/pipermail/glasgow-haskell-bugs/</literal></ulink></para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>cvs-ghc:</term>
+ <listitem>
+ <para>The hardcore GHC developers hang out here. This list
+ also gets commit message from the CVS repository. There are
+ several other similar lists for other parts of the CVS
+ repository (eg. <literal>cvs-hslibs</literal>,
+ <literal>cvs-happy</literal>, <literal>cvs-hdirect</literal>
+ etc.)</para>
+
+ <variablelist>
+ <varlistentry>
+ <term>list email address:</term>
+ <listitem>
+ <para><email>cvs-ghc@haskell.org</email></para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>subscribe at:</term>
+ <listitem>
+ <para><ulink
+ url="http://www.haskell.org/mailman/listinfo/cvs-ghc"><literal>http://www.haskell.org/mailman/listinfo/cvs-ghc</literal></ulink>.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>admin email address:</term>
+ <listitem>
+ <para><email>cvs-ghc-admin@haskell.org</email></para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>list archives:</term>
+ <listitem>
+ <para><ulink
+ url="http://www.haskell.org/pipermail/cvs-ghc/"><literal>http://www.haskell.org/pipermail/cvs-ghc/</literal></ulink></para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>There are several other haskell and GHC-related mailing
+ lists served by <literal>www.haskell.org</literal>. Go to <ulink
+ url="http://www.haskell.org/mailman/listinfo/"><literal>http://www.haskell.org/mailman/listinfo/</literal></ulink>
+ for the full list.</para>
+
+ <para>Some Haskell-related discussion also takes place in the
+ Usenet newsgroup <literal>comp.lang.functional</literal>.</para>
+
+ </sect1>
+
+ <sect1 id="bug-reporting">
+ <title>Reporting bugs in GHC</title>
+ <indexterm><primary>bugs</primary><secondary>reporting</secondary>
+ </indexterm>
+ <indexterm><primary>reporting bugs</primary>
+ </indexterm>
+
+ <para>Glasgow Haskell is a changing system so there are sure to be
+ bugs in it. </para>
+
+ <para>To report a bug, either:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>Go to the <ulink
+ url="http://sourceforge.net/projects/ghc/">SourceForge GHC
+ page</ulink>, go to the <quote>bugs</quote> section, click on
+ <quote>submit</quote>, and enter your bug report. You can also
+ check the outstanding bugs here and search the archives to make
+ sure it hasn't already been reported. Or:</para>
+ </listitem>
+ <listitem>
+ <para>Email your bug report to
+ <email>glasgow-haskell-bugs@haskell.org</email>. </para>
+ </listitem>
+ </itemizedlist>
+
+ <sect2>
+ <title>How do I tell if I should report my bug?</title>
+
+ <para>Take a look at the FAQ (<xref linkend="faq"/>) and <xref
+ linkend="wrong"/>, which will give you some guidance as to
+ whether the behaviour you're seeing is really a bug or
+ not.</para>
+
+ <para>If it is a bug, then it might have been reported before:
+ try searching the mailing list archives. The archives don't
+ have a built-in search facility, but we find that <ulink
+ url="http://www.google.com/">Google</ulink>'s site search works
+ pretty well: enter
+ <quote><literal>site:www.haskell.org</literal></quote> followed
+ by your search term into Google.</para>
+
+ <para>If in doubt, just report it.</para>
+ </sect2>
+
+ <sect2>
+ <title>What to put in a bug report</title>
+ <indexterm><primary>bug reports</primary><secondary>contents</secondary></indexterm>
+
+ <para>The name of the bug-reporting game is: facts, facts,
+ facts. Don't omit them because “Oh, they won't be
+ interested…”</para>
+
+ <orderedlist>
+ <listitem>
+ <para>What kind of machine are you running on, and exactly
+ what version of the operating system are you using?
+ (on a Unix system, <command>uname -a</command> or <command>cat
+ /etc/motd</command> will show the desired information.)</para>
+ </listitem>
+
+ <listitem>
+ <para> What version of GCC are you using? <command>gcc
+ -v</command> will tell you.</para>
+ </listitem>
+
+ <listitem>
+ <para> Run the sequence of compiles/runs that caused the
+ offending behaviour, capturing all the input/output in a
+ “script” (a UNIX command) or in an Emacs shell
+ window. We'd prefer to see the whole thing.</para>
+ </listitem>
+
+ <listitem>
+ <para> Be sure any Haskell compilations are run with a
+ <option>-v</option> (verbose) flag, so we can see exactly
+ what was run, what versions of things you have, etc.</para>
+ </listitem>
+
+ <listitem>
+ <para> What is the program behaviour that is wrong, in your
+ opinion?</para>
+ </listitem>
+
+ <listitem>
+ <para> If practical, please send enough source files for us
+ to duplicate the problem.</para>
+ </listitem>
+
+ <listitem>
+ <para> If you are a Hero and track down the problem in the
+ compilation-system sources, please send us patches relative
+ to a known released version of GHC, or whole files if you
+ prefer.</para>
+ </listitem>
+ </orderedlist>
+ </sect2>
+ </sect1>
+
+ <sect1 id="version-numbering">
+ <title>GHC version numbering policy</title>
+ <indexterm><primary>version, of ghc</primary></indexterm>
+
+ <para>As of GHC version 6.0, we have adopted the following policy
+ for numbering GHC versions:</para>
+
+ <variablelist>
+ <varlistentry>
+ <term>Stable Releases</term>
+ <listitem>
+ <para>These are numbered <literal><replaceable>x</replaceable>.<replaceable>y</replaceable>.<replaceable>z</replaceable></literal>, where
+ <replaceable>y</replaceable> is <emphasis>even</emphasis>, and
+ <replaceable>z</replaceable> is the patchlevel number (the trailing
+ <literal>.<replaceable>z</replaceable></literal> can be omitted if <replaceable>z</replaceable>
+ is zero). Patchlevels are bug-fix releases only, and never
+ change the programmer interface to any system-supplied code.
+ However, if you install a new patchlevel over an old one you
+ will need to recompile any code that was compiled against the
+ old libraries.</para>
+
+ <para>The value of <literal>__GLASGOW_HASKELL__</literal>
+ (see <xref linkend="c-pre-processor"/>) for a major release
+ <literal><replaceable>x</replaceable>.<replaceable>y</replaceable>.<replaceable>z</replaceable></literal>
+ is the integer <replaceable>xyy</replaceable> (if
+ <replaceable>y</replaceable> is a single digit, then a leading zero
+ is added, so for example in version 6.2 of GHC,
+ <literal>__GLASGOW_HASKELL__==602</literal>).</para>
+ <indexterm>
+ <primary><literal>__GLASGOW_HASKELL__</literal></primary>
+ </indexterm>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Snapshots/unstable releases</term>
+ <listitem>
+ <para>We may make snapshot releases of the current
+ development sources from time to time, and the current
+ sources are always available via the CVS repository (see the
+ <ulink url="http://www.haskell.org/ghc/">GHC web
+ site</ulink> for details).</para>
+
+ <para>Snapshot releases are named
+ <literal><replaceable>x</replaceable>.<replaceable>y</replaceable>.YYYYMMDD</literal>
+ where <literal>YYYYMMDD</literal> is the date of the sources
+ from which the snapshot was built. In theory, you can check
+ out the exact same sources from the CVS repository using
+ this date.</para>
+
+ <para>If <replaceable>y</replaceable> is odd, then this is a
+ snapshot of the CVS HEAD (the main development branch). If
+ <replaceable>y</replaceable> is even, then it is a snapshot
+ of the stable branch between patchlevel releases. For
+ example, <literal>6.3.20040225</literal> would be a snapshot
+ of the HEAD, but <literal>6.2.20040225</literal> would be a
+ snapshot of the <literal>6.2</literal> branch.</para>
+
+ <para>The value of <literal>__GLASGOW_HASKELL__</literal>
+ for a snapshot release is the integer
+ <replaceable>xyy</replaceable>. You should never write any
+ conditional code which tests for this value, however: since
+ interfaces change on a day-to-day basis, and we don't have
+ finer granularity in the values of
+ <literal>__GLASGOW_HASKELL__</literal>, you should only
+ conditionally compile using predicates which test whether
+ <literal>__GLASGOW_HASKELL__</literal> is equal to, later
+ than, or earlier than a given major release.</para>
+ <indexterm>
+ <primary><literal>__GLASGOW_HASKELL__</literal></primary>
+ </indexterm>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>The version number of your copy of GHC can be found by
+ invoking <literal>ghc</literal> with the
+ <literal>––version</literal> flag (see <xref
+ linkend="options-help"/>).</para>
+ </sect1>
+
+
+&relnotes;
+
+</chapter>
+
+<!-- Emacs stuff:
+ ;;; Local Variables: ***
+ ;;; mode: xml ***
+ ;;; sgml-parent-document: ("users_guide.xml" "book" "chapter") ***
+ ;;; End: ***
+ -->
projects / ghc-hetmet.git / blobdiff