ghc/docs/users_guide/intro.sgml

   1 <chapter id="introduction-GHC">
   2   <title>Introduction to GHC</title>
   3
   4   <para>This is a guide to using the Glasgow Haskell Compiler (GHC):
   5   an interactive and batch compilation system for the <ulink
   6   url="http://www.haskell.org/">Haskell&nbsp;98</ulink>
   7   language.</para>
   8
   9   <para>GHC has two main components: an interactive Haskell
  10   interpreter (also known as GHCi), described in <xref
  11   linkend="ghci"/>, and a batch compiler, described throughout <xref
  12   linkend="using-ghc"/>.  In fact, GHC consists of a single program
  13   which is just run with different options to provide either the
  14   interactive or the batch system.</para>
  15
  16   <para>The batch compiler can be used alongside GHCi: compiled
  17   modules can be loaded into an interactive session and used in the
  18   same way as interpreted code, and in fact when using GHCi most of
  19   the library code will be pre-compiled.  This means you get the best
  20   of both worlds: fast pre-compiled library code, and fast compile
  21   turnaround for the parts of your program being actively
  22   developed.</para>
  23
  24   <para>GHC supports numerous language extensions, including
  25   concurrency, a foreign function interface, exceptions, type system
  26   extensions such as multi-parameter type classes, local universal and
  27   existential quantification, functional dependencies, scoped type
  28   variables and explicit unboxed types.  These are all described in
  29   <xref linkend="ghc-language-features"/>.</para>
  30
  31   <para>GHC has a comprehensive optimiser, so when you want to Really
  32   Go For It (and you've got time to spare) GHC can produce pretty fast
  33   code.  Alternatively, the default option is to compile as fast as
  34   possible while not making too much effort to optimise the generated
  35   code (although GHC probably isn't what you'd describe as a fast
  36   compiler :-).</para>
  37
  38   <para>GHC's profiling system supports &ldquo;cost centre
  39   stacks&rdquo;: a way of seeing the profile of a Haskell program in a
  40   call-graph like structure.  See <xref linkend="profiling"/> for more
  41   details.</para>
  42
  43   <para>GHC comes with a large collection of libraries, with
  44   everything from parser combinators to networking.  The libraries are
  45   described in separate documentation.</para>
  46
  47   <sect1 id="mailing-lists-GHC">
  48     <title>Meta-information: Web sites, mailing lists, etc.</title>
  49
  50     <indexterm><primary>mailing lists, Glasgow Haskell</primary></indexterm>
  51     <indexterm><primary>Glasgow Haskell mailing lists</primary></indexterm>
  52
  53     <para>On the World-Wide Web, there are several URLs of likely
  54     interest:</para>
  55
  56     <itemizedlist>
  57       <listitem>
  58         <para><ulink URL="http://www.haskell.org/" >Haskell home
  59         page</ulink></para>
  60       </listitem>
  61
  62       <listitem>
  63         <para><ulink URL="http://www.haskell.org/ghc/">GHC home
  64         page</ulink></para>
  65       </listitem>
  66
  67       <listitem>
  68         <para><ulink
  69         URL="http://www.cs.nott.ac.uk/~gmh/faq.html">comp.lang.functional
  70         FAQ</ulink></para>
  71       </listitem>
  72
  73     </itemizedlist>
  74
  75     <para>We run the following mailing lists about Glasgow Haskell.
  76     We encourage you to join, as you feel is appropriate.</para>
  77
  78     <variablelist>
  79       <varlistentry>
  80         <term>glasgow-haskell-users:</term>
  81         <listitem>
  82           <para>This list is for GHC users to chat among themselves.
  83           If you have a specific question about GHC, please check the
  84           FAQ first (<xref linkend="faq"/>).</para>
  85
  86           <variablelist>
  87             <varlistentry>
  88               <term>list email address:</term>
  89               <listitem>
  90                 <para><email>glasgow-haskell-users@haskell.org</email></para>
  91               </listitem>
  92             </varlistentry>
  93
  94             <varlistentry>
  95               <term>subscribe at:</term>
  96               <listitem>
  97                 <para><ulink
  98               url="http://www.haskell.org/mailman/listinfo/glasgow-haskell-users"><literal>http://www.haskell.org/mailman/listinfo/glasgow-haskell-users</literal></ulink>.</para>
  99               </listitem>
 100             </varlistentry>
 101
 102             <varlistentry>
 103               <term>admin email address:</term>
 104               <listitem>
 105                 <para><email>glasgow-haskell-users-admin@haskell.org</email></para>
 106               </listitem>
 107             </varlistentry>
 108
 109             <varlistentry>
 110               <term>list archives:</term>
 111               <listitem>
 112                 <para><ulink
 113           url="http://www.haskell.org/pipermail/glasgow-haskell-users/"><literal>http://www.haskell.org/pipermail/glasgow-haskell-users/</literal></ulink></para>
 114               </listitem>
 115             </varlistentry>
 116           </variablelist>
 117         </listitem>
 118       </varlistentry>
 119
 120       <varlistentry>
 121         <term>glasgow-haskell-bugs:</term>
 122         <listitem>
 123           <para>Send bug reports for GHC to this address!  The sad and
 124           lonely people who subscribe to this list will muse upon
 125           what's wrong and what you might do about it.</para>
 126
 127           <variablelist>
 128             <varlistentry>
 129               <term>list email address:</term>
 130               <listitem>
 131                 <para><email>glasgow-haskell-bugs@haskell.org</email></para>
 132               </listitem>
 133             </varlistentry>
 134
 135             <varlistentry>
 136               <term>subscribe at:</term>
 137               <listitem>
 138                 <para><ulink
 139               url="http://www.haskell.org/mailman/listinfo/glasgow-haskell-bugs"><literal>http://www.haskell.org/mailman/listinfo/glasgow-haskell-bugs</literal></ulink>.</para>
 140               </listitem>
 141             </varlistentry>
 142
 143             <varlistentry>
 144               <term>admin email address:</term>
 145               <listitem>
 146                 <para><email>glasgow-haskell-bugs-admin@haskell.org</email></para>
 147               </listitem>
 148             </varlistentry>
 149
 150             <varlistentry>
 151               <term>list archives:</term>
 152               <listitem>
 153                 <para><ulink
 154           url="http://www.haskell.org/pipermail/glasgow-haskell-bugs/"><literal>http://www.haskell.org/pipermail/glasgow-haskell-bugs/</literal></ulink></para>
 155               </listitem>
 156             </varlistentry>
 157           </variablelist>
 158         </listitem>
 159       </varlistentry>
 160
 161       <varlistentry>
 162         <term>cvs-ghc:</term>
 163         <listitem>
 164           <para>The hardcore GHC developers hang out here.  This list
 165           also gets commit message from the CVS repository.  There are
 166           several other similar lists for other parts of the CVS
 167           repository (eg. <literal>cvs-hslibs</literal>,
 168           <literal>cvs-happy</literal>, <literal>cvs-hdirect</literal>
 169           etc.)</para>
 170
 171           <variablelist>
 172             <varlistentry>
 173               <term>list email address:</term>
 174               <listitem>
 175                 <para><email>cvs-ghc@haskell.org</email></para>
 176               </listitem>
 177             </varlistentry>
 178
 179             <varlistentry>
 180               <term>subscribe at:</term>
 181               <listitem>
 182                 <para><ulink
 183               url="http://www.haskell.org/mailman/listinfo/cvs-ghc"><literal>http://www.haskell.org/mailman/listinfo/cvs-ghc</literal></ulink>.</para>
 184               </listitem>
 185             </varlistentry>
 186
 187             <varlistentry>
 188               <term>admin email address:</term>
 189               <listitem>
 190                 <para><email>cvs-ghc-admin@haskell.org</email></para>
 191               </listitem>
 192             </varlistentry>
 193
 194             <varlistentry>
 195               <term>list archives:</term>
 196               <listitem>
 197                 <para><ulink
 198           url="http://www.haskell.org/pipermail/cvs-ghc/"><literal>http://www.haskell.org/pipermail/cvs-ghc/</literal></ulink></para>
 199               </listitem>
 200             </varlistentry>
 201           </variablelist>
 202         </listitem>
 203       </varlistentry>
 204     </variablelist>
 205
 206     <para>There are several other haskell and GHC-related mailing
 207     lists served by <literal>www.haskell.org</literal>.  Go to <ulink
 208     url="http://www.haskell.org/mailman/listinfo/"><literal>http://www.haskell.org/mailman/listinfo/</literal></ulink>
 209     for the full list.</para>
 210
 211     <para>Some Haskell-related discussion also takes place in the
 212     Usenet newsgroup <literal>comp.lang.functional</literal>.</para>
 213
 214   </sect1>
 215
 216   <sect1 id="bug-reporting">
 217     <title>Reporting bugs in GHC</title>
 218     <indexterm><primary>bugs</primary><secondary>reporting</secondary>
 219     </indexterm>
 220     <indexterm><primary>reporting bugs</primary>
 221     </indexterm>
 222
 223     <para>Glasgow Haskell is a changing system so there are sure to be
 224     bugs in it. </para>
 225
 226     <para>To report a bug, either:</para>
 227
 228     <itemizedlist>
 229       <listitem>
 230         <para>Go to the <ulink
 231     url="http://sourceforge.net/projects/ghc/">SourceForge GHC
 232     page</ulink>, go to the <quote>bugs</quote> section, click on
 233     <quote>submit</quote>, and enter your bug report.  You can also
 234     check the outstanding bugs here and search the archives to make
 235     sure it hasn't already been reported.  Or:</para>
 236       </listitem>
 237       <listitem>
 238         <para>Email your bug report to
 239     <email>glasgow-haskell-bugs@haskell.org</email>. </para>
 240       </listitem>
 241     </itemizedlist>
 242
 243     <sect2>
 244       <title>How do I tell if I should report my bug?</title>
 245
 246       <para>Take a look at the FAQ (<xref linkend="faq"/>) and <xref
 247       linkend="wrong"/>, which will give you some guidance as to
 248       whether the behaviour you're seeing is really a bug or
 249       not.</para>
 250
 251       <para>If it is a bug, then it might have been reported before:
 252       try searching the mailing list archives.  The archives don't
 253       have a built-in search facility, but we find that <ulink
 254       url="http://www.google.com/">Google</ulink>'s site search works
 255       pretty well: enter
 256       <quote><literal>site:www.haskell.org</literal></quote> followed
 257       by your search term into Google.</para>
 258
 259       <para>If in doubt, just report it.</para>
 260     </sect2>
 261
 262     <sect2>
 263       <title>What to put in a bug report</title>
 264       <indexterm><primary>bug reports</primary><secondary>contents</secondary></indexterm>
 265
 266       <para>The name of the bug-reporting game is: facts, facts,
 267       facts.  Don't omit them because &ldquo;Oh, they won't be
 268       interested&hellip;&rdquo;</para>
 269
 270       <orderedlist>
 271         <listitem>
 272           <para>What kind of machine are you running on, and exactly
 273           what version of the operating system are you using?
 274           (on a Unix system, <command>uname -a</command> or <command>cat
 275           /etc/motd</command> will show the desired information.)</para>
 276         </listitem>
 277
 278         <listitem>
 279           <para> What version of GCC are you using? <command>gcc
 280           -v</command> will tell you.</para>
 281         </listitem>
 282
 283         <listitem>
 284           <para> Run the sequence of compiles/runs that caused the
 285           offending behaviour, capturing all the input/output in a
 286           &ldquo;script&rdquo; (a UNIX command) or in an Emacs shell
 287           window.  We'd prefer to see the whole thing.</para>
 288         </listitem>
 289
 290         <listitem>
 291           <para> Be sure any Haskell compilations are run with a
 292           <option>-v</option> (verbose) flag, so we can see exactly
 293           what was run, what versions of things you have, etc.</para>
 294         </listitem>
 295
 296         <listitem>
 297           <para> What is the program behaviour that is wrong, in your
 298           opinion?</para>
 299         </listitem>
 300
 301         <listitem>
 302           <para> If practical, please send enough source files for us
 303           to duplicate the problem.</para>
 304         </listitem>
 305
 306         <listitem>
 307           <para> If you are a Hero and track down the problem in the
 308           compilation-system sources, please send us patches relative
 309           to a known released version of GHC, or whole files if you
 310           prefer.</para>
 311         </listitem>
 312       </orderedlist>
 313     </sect2>
 314   </sect1>
 315
 316   <sect1 id="version-numbering">
 317     <title>GHC version numbering policy</title>
 318     <indexterm><primary>version, of ghc</primary></indexterm>
 319
 320     <para>As of GHC version 6.0, we have adopted the following policy
 321     for numbering GHC versions:</para>
 322
 323     <variablelist>
 324       <varlistentry>
 325         <term>Stable Releases</term>
 326         <listitem>
 327           <para>These are numbered <literal><replaceable>x</replaceable>.<replaceable>y</replaceable>.<replaceable>z</replaceable></literal>, where
 328           <replaceable>y</replaceable> is <emphasis>even</emphasis>, and
 329           <replaceable>z</replaceable> is the patchlevel number (the trailing
 330           <literal>.<replaceable>z</replaceable></literal> can be omitted if <replaceable>z</replaceable>
 331           is zero).  Patchlevels are bug-fix releases only, and never
 332           change the programmer interface to any system-supplied code.
 333           However, if you install a new patchlevel over an old one you
 334           will need to recompile any code that was compiled against the
 335           old libraries.</para>
 336
 337           <para>The value of <literal>__GLASGOW_HASKELL__</literal>
 338           (see <xref linkend="c-pre-processor"/>) for a major release
 339           <literal><replaceable>x</replaceable>.<replaceable>y</replaceable>.<replaceable>z</replaceable></literal>
 340           is the integer <replaceable>xyy</replaceable> (if
 341           <replaceable>y</replaceable> is a single digit, then a leading zero
 342           is added, so for example in version 6.2 of GHC,
 343           <literal>__GLASGOW_HASKELL__==602</literal>).</para>
 344           <indexterm>
 345             <primary><literal>__GLASGOW_HASKELL__</literal></primary>
 346           </indexterm>
 347         </listitem>
 348       </varlistentry>
 349
 350       <varlistentry>
 351         <term>Snapshots/unstable releases</term>
 352         <listitem>
 353           <para>We may make snapshot releases of the current
 354           development sources from time to time, and the current
 355           sources are always available via the CVS repository (see the
 356           <ulink url="http://www.haskell.org/ghc/">GHC web
 357           site</ulink> for details).</para>
 358
 359           <para>Snapshot releases are named
 360           <literal><replaceable>x</replaceable>.<replaceable>y</replaceable>.YYYYMMDD</literal>
 361           where <literal>YYYYMMDD</literal> is the date of the sources
 362           from which the snapshot was built.  In theory, you can check
 363           out the exact same sources from the CVS repository using
 364           this date.</para>
 365
 366           <para>If <replaceable>y</replaceable> is odd, then this is a
 367           snapshot of the CVS HEAD (the main development branch).  If
 368           <replaceable>y</replaceable> is even, then it is a snapshot
 369           of the stable branch between patchlevel releases.  For
 370           example, <literal>6.3.20040225</literal> would be a snapshot
 371           of the HEAD, but <literal>6.2.20040225</literal> would be a
 372           snapshot of the <literal>6.2</literal> branch.</para>
 373
 374           <para>The value of <literal>__GLASGOW_HASKELL__</literal>
 375           for a snapshot release is the integer
 376           <replaceable>xyy</replaceable>.  You should never write any
 377           conditional code which tests for this value, however: since
 378           interfaces change on a day-to-day basis, and we don't have
 379           finer granularity in the values of
 380           <literal>__GLASGOW_HASKELL__</literal>, you should only
 381           conditionally compile using predicates which test whether
 382           <literal>__GLASGOW_HASKELL__</literal> is equal to, later
 383           than, or earlier than a given major release.</para>
 384           <indexterm>
 385             <primary><literal>__GLASGOW_HASKELL__</literal></primary>
 386           </indexterm>
 387         </listitem>
 388       </varlistentry>
 389     </variablelist>
 390
 391     <para>The version number of your copy of GHC can be found by
 392     invoking <literal>ghc</literal> with the
 393     <literal>&ndash;&ndash;version</literal> flag (see <xref
 394     linkend="options-help"/>).</para>
 395   </sect1>
 396
 397
 398 &relnotes;
 399
 400 </chapter>
 401
 402 <!-- Emacs stuff:
 403      ;;; Local Variables: ***
 404      ;;; mode: sgml ***
 405      ;;; sgml-parent-document: ("users_guide.sgml" "book" "chapter") ***
 406      ;;; End: ***
 407  -->