docs/users_guide/intro.xml

   1 <?xml version="1.0" encoding="iso-8859-1"?>
   2 <chapter id="introduction-GHC">
   3   <title>Introduction to GHC</title>
   4
   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&nbsp;98</ulink>
   8   language.</para>
   9
  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>
  16
  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
  23   developed.</para>
  24
  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>
  31
  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
  37   compiler :-).</para>
  38
  39   <para>GHC's profiling system supports &ldquo;cost centre
  40   stacks&rdquo;: a way of seeing the profile of a Haskell program in a
  41   call-graph like structure.  See <xref linkend="profiling"/> for more
  42   details.</para>
  43
  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>
  47
  48   <sect1 id="mailing-lists-GHC">
  49     <title>Meta-information: Web sites, mailing lists, etc.</title>
  50
  51     <indexterm><primary>mailing lists, Glasgow Haskell</primary></indexterm>
  52     <indexterm><primary>Glasgow Haskell mailing lists</primary></indexterm>
  53
  54     <para>On the World-Wide Web, there are several URLs of likely
  55     interest:</para>
  56
  57     <itemizedlist>
  58       <listitem>
  59         <para><ulink url="http://www.haskell.org/" >Haskell home
  60         page</ulink></para>
  61       </listitem>
  62
  63       <listitem>
  64         <para><ulink url="http://www.haskell.org/ghc/">GHC home
  65         page</ulink></para>
  66       </listitem>
  67
  68       <listitem>
  69         <para><ulink
  70         url="http://www.cs.nott.ac.uk/~gmh/faq.html">comp.lang.functional
  71         FAQ</ulink></para>
  72       </listitem>
  73
  74     </itemizedlist>
  75
  76     <para>We run the following mailing lists about Glasgow Haskell.
  77     We encourage you to join, as you feel is appropriate.</para>
  78
  79     <variablelist>
  80       <varlistentry>
  81         <term>glasgow-haskell-users:</term>
  82         <listitem>
  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           <ulink
  86           url="http://hackage.haskell.org/trac/ghc/wiki/FAQ">FAQ</ulink>
  87           first.</para>
  88
  89           <variablelist>
  90             <varlistentry>
  91               <term>list email address:</term>
  92               <listitem>
  93                 <para><email>glasgow-haskell-users@haskell.org</email></para>
  94               </listitem>
  95             </varlistentry>
  96
  97             <varlistentry>
  98               <term>subscribe at:</term>
  99               <listitem>
 100                 <para><ulink
 101               url="http://www.haskell.org/mailman/listinfo/glasgow-haskell-users"><literal>http://www.haskell.org/mailman/listinfo/glasgow-haskell-users</literal></ulink>.</para>
 102               </listitem>
 103             </varlistentry>
 104
 105             <varlistentry>
 106               <term>admin email address:</term>
 107               <listitem>
 108                 <para><email>glasgow-haskell-users-admin@haskell.org</email></para>
 109               </listitem>
 110             </varlistentry>
 111
 112             <varlistentry>
 113               <term>list archives:</term>
 114               <listitem>
 115                 <para><ulink
 116           url="http://www.haskell.org/pipermail/glasgow-haskell-users/"><literal>http://www.haskell.org/pipermail/glasgow-haskell-users/</literal></ulink></para>
 117               </listitem>
 118             </varlistentry>
 119           </variablelist>
 120         </listitem>
 121       </varlistentry>
 122
 123       <varlistentry>
 124         <term>glasgow-haskell-bugs:</term>
 125         <listitem>
 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>
 129
 130           <variablelist>
 131             <varlistentry>
 132               <term>list email address:</term>
 133               <listitem>
 134                 <para><email>glasgow-haskell-bugs@haskell.org</email></para>
 135               </listitem>
 136             </varlistentry>
 137
 138             <varlistentry>
 139               <term>subscribe at:</term>
 140               <listitem>
 141                 <para><ulink
 142               url="http://www.haskell.org/mailman/listinfo/glasgow-haskell-bugs"><literal>http://www.haskell.org/mailman/listinfo/glasgow-haskell-bugs</literal></ulink>.</para>
 143               </listitem>
 144             </varlistentry>
 145
 146             <varlistentry>
 147               <term>admin email address:</term>
 148               <listitem>
 149                 <para><email>glasgow-haskell-bugs-admin@haskell.org</email></para>
 150               </listitem>
 151             </varlistentry>
 152
 153             <varlistentry>
 154               <term>list archives:</term>
 155               <listitem>
 156                 <para><ulink
 157           url="http://www.haskell.org/pipermail/glasgow-haskell-bugs/"><literal>http://www.haskell.org/pipermail/glasgow-haskell-bugs/</literal></ulink></para>
 158               </listitem>
 159             </varlistentry>
 160           </variablelist>
 161         </listitem>
 162       </varlistentry>
 163
 164       <varlistentry>
 165         <term>cvs-ghc:</term>
 166         <listitem>
 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>
 172           etc.)</para>
 173
 174           <variablelist>
 175             <varlistentry>
 176               <term>list email address:</term>
 177               <listitem>
 178                 <para><email>cvs-ghc@haskell.org</email></para>
 179               </listitem>
 180             </varlistentry>
 181
 182             <varlistentry>
 183               <term>subscribe at:</term>
 184               <listitem>
 185                 <para><ulink
 186               url="http://www.haskell.org/mailman/listinfo/cvs-ghc"><literal>http://www.haskell.org/mailman/listinfo/cvs-ghc</literal></ulink>.</para>
 187               </listitem>
 188             </varlistentry>
 189
 190             <varlistentry>
 191               <term>admin email address:</term>
 192               <listitem>
 193                 <para><email>cvs-ghc-admin@haskell.org</email></para>
 194               </listitem>
 195             </varlistentry>
 196
 197             <varlistentry>
 198               <term>list archives:</term>
 199               <listitem>
 200                 <para><ulink
 201           url="http://www.haskell.org/pipermail/cvs-ghc/"><literal>http://www.haskell.org/pipermail/cvs-ghc/</literal></ulink></para>
 202               </listitem>
 203             </varlistentry>
 204           </variablelist>
 205         </listitem>
 206       </varlistentry>
 207     </variablelist>
 208
 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>
 213
 214     <para>Some Haskell-related discussion also takes place in the
 215     Usenet newsgroup <literal>comp.lang.functional</literal>.</para>
 216
 217   </sect1>
 218
 219   <sect1 id="bug-reporting">
 220     <title>Reporting bugs in GHC</title>
 221     <indexterm><primary>bugs</primary><secondary>reporting</secondary>
 222     </indexterm>
 223     <indexterm><primary>reporting bugs</primary>
 224     </indexterm>
 225
 226     <para>Glasgow Haskell is a changing system so there are sure to be
 227     bugs in it. </para>
 228
 229     <para>To report a bug, either:</para>
 230
 231     <itemizedlist>
 232       <listitem>
 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>
 239       </listitem>
 240       <listitem>
 241         <para>Bug reports can also be emailed to
 242     <email>glasgow-haskell-bugs@haskell.org</email>. </para>
 243       </listitem>
 244     </itemizedlist>
 245
 246     <sect2>
 247       <title>How do I tell if I should report my bug?</title>
 248
 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
 253       not.</para>
 254
 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>
 260
 261       <para>If in doubt, just report it.</para>
 262     </sect2>
 263
 264     <sect2>
 265       <title>What to put in a bug report</title>
 266       <indexterm><primary>bug reports</primary><secondary>contents</secondary></indexterm>
 267
 268       <para>The name of the bug-reporting game is: facts, facts,
 269       facts.  Don't omit them because &ldquo;Oh, they won't be
 270       interested&hellip;&rdquo;</para>
 271
 272       <orderedlist>
 273         <listitem>
 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           &ldquo;Architecture&rdquo; and &ldquo;Operating
 280           system&rdquo; fields.</para>
 281         </listitem>
 282
 283         <listitem>
 284           <para>What version of GCC are you using? <command>gcc&nbsp;-v</command> will tell you.</para>
 285         </listitem>
 286
 287         <listitem>
 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>
 291         </listitem>
 292
 293         <listitem>
 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>
 296         </listitem>
 297
 298         <listitem>
 299           <para>What is the program behaviour that is wrong, in your
 300           opinion?</para>
 301         </listitem>
 302
 303         <listitem>
 304           <para>If practical, please attach or send enough source
 305           files for us to duplicate the problem.</para>
 306         </listitem>
 307
 308         <listitem>
 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>
 313         </listitem>
 314       </orderedlist>
 315     </sect2>
 316   </sect1>
 317
 318   <sect1 id="version-numbering">
 319     <title>GHC version numbering policy</title>
 320     <indexterm><primary>version, of ghc</primary></indexterm>
 321
 322     <para>As of GHC version 6.0, we have adopted the following policy
 323     for numbering GHC versions:</para>
 324
 325     <variablelist>
 326       <varlistentry>
 327         <term>Stable Releases</term>
 328         <listitem>
 329           <para>These are numbered <literal><replaceable>x</replaceable>.<replaceable>y</replaceable>.<replaceable>z</replaceable></literal>, where
 330           <replaceable>y</replaceable> is <emphasis>even</emphasis>, and
 331           <replaceable>z</replaceable> is the patchlevel number (the trailing
 332           <literal>.<replaceable>z</replaceable></literal> can be omitted if <replaceable>z</replaceable>
 333           is zero).  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>
 338
 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.2 of GHC,
 345           <literal>__GLASGOW_HASKELL__==602</literal>).</para>
 346           <indexterm>
 347             <primary><literal>__GLASGOW_HASKELL__</literal></primary>
 348           </indexterm>
 349         </listitem>
 350       </varlistentry>
 351
 352       <varlistentry>
 353         <term>Snapshots/unstable releases</term>
 354         <listitem>
 355           <para>We may make snapshot releases of the current
 356           development sources from time to time, and the current
 357           sources are always available via the CVS repository (see the
 358           <ulink url="http://www.haskell.org/ghc/">GHC web
 359           site</ulink> for details).</para>
 360
 361           <para>Snapshot releases are named
 362           <literal><replaceable>x</replaceable>.<replaceable>y</replaceable>.YYYYMMDD</literal>
 363           where <literal>YYYYMMDD</literal> is the date of the sources
 364           from which the snapshot was built.  In theory, you can check
 365           out the exact same sources from the CVS repository using
 366           this date.</para>
 367
 368           <para>If <replaceable>y</replaceable> is odd, then this is a
 369           snapshot of the CVS HEAD (the main development branch).  If
 370           <replaceable>y</replaceable> is even, then it is a snapshot
 371           of the stable branch between patchlevel releases.  For
 372           example, <literal>6.3.20040225</literal> would be a snapshot
 373           of the HEAD, but <literal>6.2.20040225</literal> would be a
 374           snapshot of the <literal>6.2</literal> branch.</para>
 375
 376           <para>The value of <literal>__GLASGOW_HASKELL__</literal>
 377           for a snapshot release is the integer
 378           <replaceable>xyy</replaceable>.  You should never write any
 379           conditional code which tests for this value, however: since
 380           interfaces change on a day-to-day basis, and we don't have
 381           finer granularity in the values of
 382           <literal>__GLASGOW_HASKELL__</literal>, you should only
 383           conditionally compile using predicates which test whether
 384           <literal>__GLASGOW_HASKELL__</literal> is equal to, later
 385           than, or earlier than a given major release.</para>
 386           <indexterm>
 387             <primary><literal>__GLASGOW_HASKELL__</literal></primary>
 388           </indexterm>
 389         </listitem>
 390       </varlistentry>
 391     </variablelist>
 392
 393     <para>The version number of your copy of GHC can be found by
 394     invoking <literal>ghc</literal> with the
 395     <literal>&ndash;&ndash;version</literal> flag (see <xref
 396     linkend="options-help"/>).</para>
 397   </sect1>
 398
 399
 400 &relnotes;
 401
 402 </chapter>
 403
 404 <!-- Emacs stuff:
 405      ;;; Local Variables: ***
 406      ;;; mode: xml ***
 407      ;;; sgml-parent-document: ("users_guide.xml" "book" "chapter") ***
 408      ;;; End: ***
 409  -->