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
86 url="http://hackage.haskell.org/trac/ghc/wiki/FAQ">FAQ</ulink>
91 <term>list email address:</term>
93 <para><email>glasgow-haskell-users@haskell.org</email></para>
98 <term>subscribe at:</term>
101 url="http://www.haskell.org/mailman/listinfo/glasgow-haskell-users"><literal>http://www.haskell.org/mailman/listinfo/glasgow-haskell-users</literal></ulink>.</para>
106 <term>admin email address:</term>
108 <para><email>glasgow-haskell-users-admin@haskell.org</email></para>
113 <term>list archives:</term>
116 url="http://www.haskell.org/pipermail/glasgow-haskell-users/"><literal>http://www.haskell.org/pipermail/glasgow-haskell-users/</literal></ulink></para>
124 <term>glasgow-haskell-bugs:</term>
126 <para>Send bug reports for GHC to this address! The sad and
127 lonely people who subscribe to this list will muse upon
128 what's wrong and what you might do about it.</para>
132 <term>list email address:</term>
134 <para><email>glasgow-haskell-bugs@haskell.org</email></para>
139 <term>subscribe at:</term>
142 url="http://www.haskell.org/mailman/listinfo/glasgow-haskell-bugs"><literal>http://www.haskell.org/mailman/listinfo/glasgow-haskell-bugs</literal></ulink>.</para>
147 <term>admin email address:</term>
149 <para><email>glasgow-haskell-bugs-admin@haskell.org</email></para>
154 <term>list archives:</term>
157 url="http://www.haskell.org/pipermail/glasgow-haskell-bugs/"><literal>http://www.haskell.org/pipermail/glasgow-haskell-bugs/</literal></ulink></para>
165 <term>cvs-ghc:</term>
167 <para>The hardcore GHC developers hang out here. This list
168 also gets commit message from the CVS repository. There are
169 several other similar lists for other parts of the CVS
170 repository (eg. <literal>cvs-hslibs</literal>,
171 <literal>cvs-happy</literal>, <literal>cvs-hdirect</literal>
176 <term>list email address:</term>
178 <para><email>cvs-ghc@haskell.org</email></para>
183 <term>subscribe at:</term>
186 url="http://www.haskell.org/mailman/listinfo/cvs-ghc"><literal>http://www.haskell.org/mailman/listinfo/cvs-ghc</literal></ulink>.</para>
191 <term>admin email address:</term>
193 <para><email>cvs-ghc-admin@haskell.org</email></para>
198 <term>list archives:</term>
201 url="http://www.haskell.org/pipermail/cvs-ghc/"><literal>http://www.haskell.org/pipermail/cvs-ghc/</literal></ulink></para>
209 <para>There are several other haskell and GHC-related mailing
210 lists served by <literal>www.haskell.org</literal>. Go to <ulink
211 url="http://www.haskell.org/mailman/listinfo/"><literal>http://www.haskell.org/mailman/listinfo/</literal></ulink>
212 for the full list.</para>
214 <para>Some Haskell-related discussion also takes place in the
215 Usenet newsgroup <literal>comp.lang.functional</literal>.</para>
219 <sect1 id="bug-reporting">
220 <title>Reporting bugs in GHC</title>
221 <indexterm><primary>bugs</primary><secondary>reporting</secondary>
223 <indexterm><primary>reporting bugs</primary>
226 <para>Glasgow Haskell is a changing system so there are sure to be
229 <para>To report a bug, either:</para>
233 <para>Preferred: <ulink
234 url="http://hackage.haskell.org/trac/ghc/newticket?type=bug">Create
235 a new bug</ulink>, and enter your bug report. You can also
236 search the bug database here to make sure your bug hasn't already
237 been reported (if it has, it might still help to add information
238 from your experience to the existing report).</para>
241 <para>Bug reports can also be emailed to
242 <email>glasgow-haskell-bugs@haskell.org</email>. </para>
247 <title>How do I tell if I should report my bug?</title>
249 <para>Take a look at the <ulink
250 url="http://hackage.haskell.org/trac/ghc/wiki/FAQ">FAQ</ulink> and <xref
251 linkend="wrong"/>, which will give you some guidance as to
252 whether the behaviour you're seeing is really a bug or
255 <para>If it is a bug, then it might have been reported before:
256 try searching on the <ulink
257 url="http://hackage.haskell.org/trac/ghc">bug tracker</ulink>,
258 and failing that, try <ulink
259 url="http://www.google.com">Google</ulink>.</para>
261 <para>If in doubt, just report it.</para>
265 <title>What to put in a bug report</title>
266 <indexterm><primary>bug reports</primary><secondary>contents</secondary></indexterm>
268 <para>The name of the bug-reporting game is: facts, facts,
269 facts. Don't omit them because “Oh, they won't be
270 interested…”</para>
274 <para>What kind of machine are you running on, and exactly
275 what version of the operating system are you using? (on a
276 Unix system, <command>uname -a</command> or <command>cat
277 /etc/motd</command> will show the desired information.) In
278 the bug tracker, this information can be given in the
279 “Architecture” and “Operating
280 system” fields.</para>
284 <para>What version of GCC are you using? <command>gcc -v</command> will tell you.</para>
288 <para>Run the sequence of compiles/runs that caused the
289 offending behaviour, cut-and-paste the whole session into
290 the bug report. We'd prefer to see the whole thing.</para>
294 <para>Add the -v flag when running GHC, so we can see exactly
295 what was run, what versions of things you have, etc.</para>
299 <para>What is the program behaviour that is wrong, in your
304 <para>If practical, please attach or send enough source
305 files for us to duplicate the problem.</para>
309 <para>If you are a Hero and track down the problem in the
310 compilation-system sources, please send us patches (either
311 <literal>darcs send</literal>, plain patches, or just whole
312 files if you prefer).</para>
318 <sect1 id="version-numbering">
319 <title>GHC version numbering policy</title>
320 <indexterm><primary>version, of ghc</primary></indexterm>
322 <para>As of GHC version 6.8, we have adopted the following policy
323 for numbering GHC versions:</para>
327 <term>Stable Releases</term>
329 <para>Stable branches are numbered <literal><replaceable>x</replaceable>.<replaceable>y</replaceable></literal>, where
330 <replaceable>y</replaceable> is <emphasis>even</emphasis>.
331 Releases on the stable branch <literal><replaceable>x</replaceable>.<replaceable>y</replaceable></literal> are numbered <literal><replaceable>x</replaceable>.<replaceable>y</replaceable>.<replaceable>z</replaceable></literal>, where
332 <replaceable>z</replaceable> (>= 1) is the patchlevel number.
333 Patchlevels are bug-fix releases only, and never
334 change the programmer interface to any system-supplied code.
335 However, if you install a new patchlevel over an old one you
336 will need to recompile any code that was compiled against the
337 old libraries.</para>
339 <para>The value of <literal>__GLASGOW_HASKELL__</literal>
340 (see <xref linkend="c-pre-processor"/>) for a major release
341 <literal><replaceable>x</replaceable>.<replaceable>y</replaceable>.<replaceable>z</replaceable></literal>
342 is the integer <replaceable>xyy</replaceable> (if
343 <replaceable>y</replaceable> is a single digit, then a leading zero
344 is added, so for example in version 6.8.2 of GHC we would have
345 <literal>__GLASGOW_HASKELL__==608</literal>).</para>
347 <primary><literal>__GLASGOW_HASKELL__</literal></primary>
353 <term>Stable snapshots</term>
356 We may make snapshot releases of the current
357 stable branch <ulink url="http://www.haskell.org/ghc/dist/stable/dist/">available for download</ulink>, and the latest sources are available from <ulink url="http://hackage.haskell.org/trac/ghc/wiki/DarcsRepositories">the darcs repositories</ulink>.
360 <para>Stable snapshot releases are named
361 <literal><replaceable>x</replaceable>.<replaceable>y</replaceable>.<replaceable>z</replaceable>.<replaceable>YYYYMMDD</replaceable></literal>.
362 where <literal><replaceable>YYYYMMDD</replaceable></literal> is the date of the sources
363 from which the snapshot was built, and <literal><replaceable>x</replaceable>.<replaceable>y</replaceable>.<replaceable>z+1</replaceable></literal> is the next release to be made on that branch.
364 For example, <literal>6.8.1.20040225</literal> would be a
365 snapshot of the <literal>6.8</literal> branch during the development
366 of <literal>6.8.2</literal>.</para>
368 <para>The value of <literal>__GLASGOW_HASKELL__</literal>
369 for a snapshot release is the integer
370 <replaceable>xyy</replaceable>. You should never write any
371 conditional code which tests for this value, however: since
372 interfaces change on a day-to-day basis, and we don't have
373 finer granularity in the values of
374 <literal>__GLASGOW_HASKELL__</literal>, you should only
375 conditionally compile using predicates which test whether
376 <literal>__GLASGOW_HASKELL__</literal> is equal to, later
377 than, or earlier than a given major release.</para>
379 <primary><literal>__GLASGOW_HASKELL__</literal></primary>
385 <term>Unstable snapshots</term>
388 We may make snapshot releases of the
389 HEAD <ulink url="http://www.haskell.org/ghc/dist/current/dist/">available for download</ulink>, and the latest sources are available from <ulink url="http://hackage.haskell.org/trac/ghc/wiki/DarcsRepositories">the darcs repositories</ulink>.
392 <para>Unstable snapshot releases are named
393 <literal><replaceable>x</replaceable>.<replaceable>y</replaceable>.<replaceable>YYYYMMDD</replaceable></literal>.
394 where <literal><replaceable>YYYYMMDD</replaceable></literal> is the date of the sources
395 from which the snapshot was built.
396 For example, <literal>6.7.20040225</literal> would be a
397 snapshot of the HEAD before the creation of the
398 <literal>6.8</literal> branch.</para>
400 <para>The value of <literal>__GLASGOW_HASKELL__</literal>
401 for a snapshot release is the integer
402 <replaceable>xyy</replaceable>. You should never write any
403 conditional code which tests for this value, however: since
404 interfaces change on a day-to-day basis, and we don't have
405 finer granularity in the values of
406 <literal>__GLASGOW_HASKELL__</literal>, you should only
407 conditionally compile using predicates which test whether
408 <literal>__GLASGOW_HASKELL__</literal> is equal to, later
409 than, or earlier than a given major release.</para>
411 <primary><literal>__GLASGOW_HASKELL__</literal></primary>
417 <para>The version number of your copy of GHC can be found by
418 invoking <literal>ghc</literal> with the
419 <literal>––version</literal> flag (see <xref
420 linkend="options-help"/>).</para>
429 ;;; Local Variables: ***
431 ;;; sgml-parent-document: ("users_guide.xml" "book" "chapter") ***