1 <?xml version="1.0" encoding="iso-8859-1"?>
2 <chapter id="introduction-GHC">
3 <title>Introduction to GHC</title>
5 <para>This is a guide to using the Glasgow Haskell Compiler (GHC):
6 an interactive and batch compilation system for the <ulink
7 url="http://www.haskell.org/">Haskell 98</ulink>
10 <para>GHC has two main components: an interactive Haskell
11 interpreter (also known as GHCi), described in <xref
12 linkend="ghci"/>, and a batch compiler, described throughout <xref
13 linkend="using-ghc"/>. In fact, GHC consists of a single program
14 which is just run with different options to provide either the
15 interactive or the batch system.</para>
17 <para>The batch compiler can be used alongside GHCi: compiled
18 modules can be loaded into an interactive session and used in the
19 same way as interpreted code, and in fact when using GHCi most of
20 the library code will be pre-compiled. This means you get the best
21 of both worlds: fast pre-compiled library code, and fast compile
22 turnaround for the parts of your program being actively
25 <para>GHC supports numerous language extensions, including
26 concurrency, a foreign function interface, exceptions, type system
27 extensions such as multi-parameter type classes, local universal and
28 existential quantification, functional dependencies, scoped type
29 variables and explicit unboxed types. These are all described in
30 <xref linkend="ghc-language-features"/>.</para>
32 <para>GHC has a comprehensive optimiser, so when you want to Really
33 Go For It (and you've got time to spare) GHC can produce pretty fast
34 code. Alternatively, the default option is to compile as fast as
35 possible while not making too much effort to optimise the generated
36 code (although GHC probably isn't what you'd describe as a fast
39 <para>GHC's profiling system supports “cost centre
40 stacks”: a way of seeing the profile of a Haskell program in a
41 call-graph like structure. See <xref linkend="profiling"/> for more
44 <para>GHC comes with a large collection of libraries, with
45 everything from parser combinators to networking. The libraries are
46 described in separate documentation.</para>
48 <sect1 id="mailing-lists-GHC">
49 <title>Meta-information: Web sites, mailing lists, etc.</title>
51 <indexterm><primary>mailing lists, Glasgow Haskell</primary></indexterm>
52 <indexterm><primary>Glasgow Haskell mailing lists</primary></indexterm>
54 <para>On the World-Wide Web, there are several URLs of likely
59 <para><ulink url="http://www.haskell.org/" >Haskell home
64 <para><ulink url="http://www.haskell.org/ghc/">GHC home
70 url="http://www.cs.nott.ac.uk/~gmh/faq.html">comp.lang.functional
76 <para>We run the following mailing lists about Glasgow Haskell.
77 We encourage you to join, as you feel is appropriate.</para>
81 <term>glasgow-haskell-users:</term>
83 <para>This list is for GHC users to chat among themselves.
84 If you have a specific question about GHC, please check the
85 FAQ first (<xref linkend="faq"/>).</para>
89 <term>list email address:</term>
91 <para><email>glasgow-haskell-users@haskell.org</email></para>
96 <term>subscribe at:</term>
99 url="http://www.haskell.org/mailman/listinfo/glasgow-haskell-users"><literal>http://www.haskell.org/mailman/listinfo/glasgow-haskell-users</literal></ulink>.</para>
104 <term>admin email address:</term>
106 <para><email>glasgow-haskell-users-admin@haskell.org</email></para>
111 <term>list archives:</term>
114 url="http://www.haskell.org/pipermail/glasgow-haskell-users/"><literal>http://www.haskell.org/pipermail/glasgow-haskell-users/</literal></ulink></para>
122 <term>glasgow-haskell-bugs:</term>
124 <para>Send bug reports for GHC to this address! The sad and
125 lonely people who subscribe to this list will muse upon
126 what's wrong and what you might do about it.</para>
130 <term>list email address:</term>
132 <para><email>glasgow-haskell-bugs@haskell.org</email></para>
137 <term>subscribe at:</term>
140 url="http://www.haskell.org/mailman/listinfo/glasgow-haskell-bugs"><literal>http://www.haskell.org/mailman/listinfo/glasgow-haskell-bugs</literal></ulink>.</para>
145 <term>admin email address:</term>
147 <para><email>glasgow-haskell-bugs-admin@haskell.org</email></para>
152 <term>list archives:</term>
155 url="http://www.haskell.org/pipermail/glasgow-haskell-bugs/"><literal>http://www.haskell.org/pipermail/glasgow-haskell-bugs/</literal></ulink></para>
163 <term>cvs-ghc:</term>
165 <para>The hardcore GHC developers hang out here. This list
166 also gets commit message from the CVS repository. There are
167 several other similar lists for other parts of the CVS
168 repository (eg. <literal>cvs-hslibs</literal>,
169 <literal>cvs-happy</literal>, <literal>cvs-hdirect</literal>
174 <term>list email address:</term>
176 <para><email>cvs-ghc@haskell.org</email></para>
181 <term>subscribe at:</term>
184 url="http://www.haskell.org/mailman/listinfo/cvs-ghc"><literal>http://www.haskell.org/mailman/listinfo/cvs-ghc</literal></ulink>.</para>
189 <term>admin email address:</term>
191 <para><email>cvs-ghc-admin@haskell.org</email></para>
196 <term>list archives:</term>
199 url="http://www.haskell.org/pipermail/cvs-ghc/"><literal>http://www.haskell.org/pipermail/cvs-ghc/</literal></ulink></para>
207 <para>There are several other haskell and GHC-related mailing
208 lists served by <literal>www.haskell.org</literal>. Go to <ulink
209 url="http://www.haskell.org/mailman/listinfo/"><literal>http://www.haskell.org/mailman/listinfo/</literal></ulink>
210 for the full list.</para>
212 <para>Some Haskell-related discussion also takes place in the
213 Usenet newsgroup <literal>comp.lang.functional</literal>.</para>
217 <sect1 id="bug-reporting">
218 <title>Reporting bugs in GHC</title>
219 <indexterm><primary>bugs</primary><secondary>reporting</secondary>
221 <indexterm><primary>reporting bugs</primary>
224 <para>Glasgow Haskell is a changing system so there are sure to be
227 <para>To report a bug, either:</para>
231 <para>Go to the <ulink
232 url="http://sourceforge.net/projects/ghc/">SourceForge GHC
233 page</ulink>, go to the <quote>bugs</quote> section, click on
234 <quote>submit</quote>, and enter your bug report. You can also
235 check the outstanding bugs here and search the archives to make
236 sure it hasn't already been reported. Or:</para>
239 <para>Email your bug report to
240 <email>glasgow-haskell-bugs@haskell.org</email>. </para>
245 <title>How do I tell if I should report my bug?</title>
247 <para>Take a look at the FAQ (<xref linkend="faq"/>) and <xref
248 linkend="wrong"/>, which will give you some guidance as to
249 whether the behaviour you're seeing is really a bug or
252 <para>If it is a bug, then it might have been reported before:
253 try searching the mailing list archives. The archives don't
254 have a built-in search facility, but we find that <ulink
255 url="http://www.google.com/">Google</ulink>'s site search works
257 <quote><literal>site:www.haskell.org</literal></quote> followed
258 by your search term into Google.</para>
260 <para>If in doubt, just report it.</para>
264 <title>What to put in a bug report</title>
265 <indexterm><primary>bug reports</primary><secondary>contents</secondary></indexterm>
267 <para>The name of the bug-reporting game is: facts, facts,
268 facts. Don't omit them because “Oh, they won't be
269 interested…”</para>
273 <para>What kind of machine are you running on, and exactly
274 what version of the operating system are you using?
275 (on a Unix system, <command>uname -a</command> or <command>cat
276 /etc/motd</command> will show the desired information.)</para>
280 <para> What version of GCC are you using? <command>gcc
281 -v</command> will tell you.</para>
285 <para> Run the sequence of compiles/runs that caused the
286 offending behaviour, capturing all the input/output in a
287 “script” (a UNIX command) or in an Emacs shell
288 window. We'd prefer to see the whole thing.</para>
292 <para> Be sure any Haskell compilations are run with a
293 <option>-v</option> (verbose) flag, so we can see exactly
294 what was run, what versions of things you have, etc.</para>
298 <para> What is the program behaviour that is wrong, in your
303 <para> If practical, please send enough source files for us
304 to duplicate the problem.</para>
308 <para> If you are a Hero and track down the problem in the
309 compilation-system sources, please send us patches relative
310 to a known released version of GHC, or whole files if you
317 <sect1 id="version-numbering">
318 <title>GHC version numbering policy</title>
319 <indexterm><primary>version, of ghc</primary></indexterm>
321 <para>As of GHC version 6.0, we have adopted the following policy
322 for numbering GHC versions:</para>
326 <term>Stable Releases</term>
328 <para>These are numbered <literal><replaceable>x</replaceable>.<replaceable>y</replaceable>.<replaceable>z</replaceable></literal>, where
329 <replaceable>y</replaceable> is <emphasis>even</emphasis>, and
330 <replaceable>z</replaceable> is the patchlevel number (the trailing
331 <literal>.<replaceable>z</replaceable></literal> can be omitted if <replaceable>z</replaceable>
332 is zero). Patchlevels are bug-fix releases only, and never
333 change the programmer interface to any system-supplied code.
334 However, if you install a new patchlevel over an old one you
335 will need to recompile any code that was compiled against the
336 old libraries.</para>
338 <para>The value of <literal>__GLASGOW_HASKELL__</literal>
339 (see <xref linkend="c-pre-processor"/>) for a major release
340 <literal><replaceable>x</replaceable>.<replaceable>y</replaceable>.<replaceable>z</replaceable></literal>
341 is the integer <replaceable>xyy</replaceable> (if
342 <replaceable>y</replaceable> is a single digit, then a leading zero
343 is added, so for example in version 6.2 of GHC,
344 <literal>__GLASGOW_HASKELL__==602</literal>).</para>
346 <primary><literal>__GLASGOW_HASKELL__</literal></primary>
352 <term>Snapshots/unstable releases</term>
354 <para>We may make snapshot releases of the current
355 development sources from time to time, and the current
356 sources are always available via the CVS repository (see the
357 <ulink url="http://www.haskell.org/ghc/">GHC web
358 site</ulink> for details).</para>
360 <para>Snapshot releases are named
361 <literal><replaceable>x</replaceable>.<replaceable>y</replaceable>.YYYYMMDD</literal>
362 where <literal>YYYYMMDD</literal> is the date of the sources
363 from which the snapshot was built. In theory, you can check
364 out the exact same sources from the CVS repository using
367 <para>If <replaceable>y</replaceable> is odd, then this is a
368 snapshot of the CVS HEAD (the main development branch). If
369 <replaceable>y</replaceable> is even, then it is a snapshot
370 of the stable branch between patchlevel releases. For
371 example, <literal>6.3.20040225</literal> would be a snapshot
372 of the HEAD, but <literal>6.2.20040225</literal> would be a
373 snapshot of the <literal>6.2</literal> branch.</para>
375 <para>The value of <literal>__GLASGOW_HASKELL__</literal>
376 for a snapshot release is the integer
377 <replaceable>xyy</replaceable>. You should never write any
378 conditional code which tests for this value, however: since
379 interfaces change on a day-to-day basis, and we don't have
380 finer granularity in the values of
381 <literal>__GLASGOW_HASKELL__</literal>, you should only
382 conditionally compile using predicates which test whether
383 <literal>__GLASGOW_HASKELL__</literal> is equal to, later
384 than, or earlier than a given major release.</para>
386 <primary><literal>__GLASGOW_HASKELL__</literal></primary>
392 <para>The version number of your copy of GHC can be found by
393 invoking <literal>ghc</literal> with the
394 <literal>––version</literal> flag (see <xref
395 linkend="options-help"/>).</para>
404 ;;; Local Variables: ***
406 ;;; sgml-parent-document: ("users_guide.xml" "book" "chapter") ***