diff options
Diffstat (limited to 'docs/users_guide/intro.xml')
| -rw-r--r-- | docs/users_guide/intro.xml | 409 |
1 files changed, 409 insertions, 0 deletions
diff --git a/docs/users_guide/intro.xml b/docs/users_guide/intro.xml new file mode 100644 index 0000000000..d4b6a1241f --- /dev/null +++ b/docs/users_guide/intro.xml @@ -0,0 +1,409 @@ +<?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 + <ulink + url="http://hackage.haskell.org/trac/ghc/wiki/FAQ">FAQ</ulink> + first.</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>Preferred: <ulink + url="http://hackage.haskell.org/trac/ghc/newticket?type=bug">Create + a new bug</ulink>, and enter your bug report. You can also + search the bug database here to make sure your bug hasn't already + been reported (if it has, it might still help to add information + from your experience to the existing report).</para> + </listitem> + <listitem> + <para>Bug reports can also be emailed 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 <ulink + url="http://hackage.haskell.org/trac/ghc/wiki/FAQ">FAQ</ulink> 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 on the <ulink + url="http://hackage.haskell.org/trac/ghc">bug tracker</ulink>, + and failing that, try <ulink + url="http://www.google.com">Google</ulink>.</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.) In + the bug tracker, this information can be given in the + “Architecture” and “Operating + system” fields.</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, cut-and-paste the whole session into + the bug report. We'd prefer to see the whole thing.</para> + </listitem> + + <listitem> + <para>Add the -v flag when running GHC, 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 attach or 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 (either + <literal>darcs send</literal>, plain patches, or just 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: *** + --> |