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.  These are all
  45   described in <xref linkend="book-hslibs">.</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/Department/Staff/mpj/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
  83           themselves.</para>
  84
  85           <variablelist>
  86             <varlistentry>
  87               <term>list email address:</term>
  88               <listitem>
  89                 <para><email>glasgow-haskell-users@haskell.org</email></para>
  90               </listitem>
  91             </varlistentry>
  92
  93             <varlistentry>
  94               <term>subscribe at:</term>
  95               <listitem>
  96                 <para><ulink
  97               url="http://www.haskell.org/mailman/listinfo/glasgow-haskell-users"><literal>http://www.haskell.org/mailman/listinfo/glasgow-haskell-users</literal></ulink>.</para>
  98               </listitem>
  99             </varlistentry>
 100
 101             <varlistentry>
 102               <term>admin email address:</term>
 103               <listitem>
 104                 <para><email>glasgow-haskell-users-admin@haskell.org</email></para>
 105               </listitem>
 106             </varlistentry>
 107
 108             <varlistentry>
 109               <term>list archives:</term>
 110               <listitem>
 111                 <para><ulink
 112           url="http://www.haskell.org/pipermail/glasgow-haskell-users/"><literal>http://www.haskell.org/pipermail/glasgow-haskell-users/</literal></ulink></para>
 113               </listitem>
 114             </varlistentry>
 115           </variablelist>
 116         </listitem>
 117       </varlistentry>
 118
 119       <varlistentry>
 120         <term>glasgow-haskell-bugs:</term>
 121         <listitem>
 122           <para>Send bug reports for GHC to this address!  The sad and
 123           lonely people who subscribe to this list will muse upon
 124           what's wrong and what you might do about it.</para>
 125
 126           <variablelist>
 127             <varlistentry>
 128               <term>list email address:</term>
 129               <listitem>
 130                 <para><email>glasgow-haskell-bugs@haskell.org</email></para>
 131               </listitem>
 132             </varlistentry>
 133
 134             <varlistentry>
 135               <term>subscribe at:</term>
 136               <listitem>
 137                 <para><ulink
 138               url="http://www.haskell.org/mailman/listinfo/glasgow-haskell-bugs"><literal>http://www.haskell.org/mailman/listinfo/glasgow-haskell-bugs</literal></ulink>.</para>
 139               </listitem>
 140             </varlistentry>
 141
 142             <varlistentry>
 143               <term>admin email address:</term>
 144               <listitem>
 145                 <para><email>glasgow-haskell-bugs-admin@haskell.org</email></para>
 146               </listitem>
 147             </varlistentry>
 148
 149             <varlistentry>
 150               <term>list archives:</term>
 151               <listitem>
 152                 <para><ulink
 153           url="http://www.haskell.org/pipermail/glasgow-haskell-bugs/"><literal>http://www.haskell.org/pipermail/glasgow-haskell-bugs/</literal></ulink></para>
 154               </listitem>
 155             </varlistentry>
 156           </variablelist>
 157         </listitem>
 158       </varlistentry>
 159
 160       <varlistentry>
 161         <term>cvs-ghc:</term>
 162         <listitem>
 163           <para>The hardcore GHC developers hang out here.  This list
 164           also gets commit message from the CVS repository.  There are
 165           several other similar lists for other parts of the CVS
 166           repository (eg. <literal>cvs-hslibs</literal>,
 167           <literal>cvs-happy</literal>, <literal>cvs-hdirect</literal>
 168           etc.)</para>
 169
 170           <variablelist>
 171             <varlistentry>
 172               <term>list email address:</term>
 173               <listitem>
 174                 <para><email>cvs-ghc@haskell.org</email></para>
 175               </listitem>
 176             </varlistentry>
 177
 178             <varlistentry>
 179               <term>subscribe at:</term>
 180               <listitem>
 181                 <para><ulink
 182               url="http://www.haskell.org/mailman/listinfo/cvs-ghc"><literal>http://www.haskell.org/mailman/listinfo/cvs-ghc</literal></ulink>.</para>
 183               </listitem>
 184             </varlistentry>
 185
 186             <varlistentry>
 187               <term>admin email address:</term>
 188               <listitem>
 189                 <para><email>cvs-ghc-admin@haskell.org</email></para>
 190               </listitem>
 191             </varlistentry>
 192
 193             <varlistentry>
 194               <term>list archives:</term>
 195               <listitem>
 196                 <para><ulink
 197           url="http://www.haskell.org/pipermail/cvs-ghc/"><literal>http://www.haskell.org/pipermail/cvs-ghc/</literal></ulink></para>
 198               </listitem>
 199             </varlistentry>
 200           </variablelist>
 201         </listitem>
 202       </varlistentry>
 203     </variablelist>
 204
 205     <para>There are several other haskell and GHC-related mailing
 206     lists served by <literal>www.haskell.org</literal>.  Go to <ulink
 207     url="http://www.haskell.org/mailman/listinfo/"><literal>http://www.haskell.org/mailman/listinfo/</literal></ulink>
 208     for the full list.</para>
 209
 210     <para>Some Haskell-related discussion also takes place in the
 211     Usenet newsgroup <literal>comp.lang.functional</literal>.</para>
 212
 213   </sect1>
 214
 215   <sect1 id="bug-reporting">
 216     <title>Reporting bugs in GHC</title>
 217     <indexterm><primary>bugs</primary><secondary>reporting</secondary>
 218     </indexterm>
 219     <indexterm><primary>reporting bugs</primary>
 220     </indexterm>
 221
 222     <para>Glasgow Haskell is a changing system so there are sure to be
 223     bugs in it. </para>
 224
 225     <para>To repot a bug, either:</para>
 226
 227     <itemizedlist>
 228       <listitem>
 229         <para>Go to the <ulink
 230     url="http://sourceforge.net/projects/ghc/">SoureForge GHC
 231     page</ulink>, go to the <quote>bugs</quote> section, click on
 232     <quote>submit</quote>, and enter your bug report.  You can also
 233     check the outstanding bugs here to make sure it hasn't already
 234     been reported.  Or:</para>
 235       </listitem>
 236       <listitem>
 237         <para>Email your bug report to
 238     <Email>glasgow-haskell-bugs@haskell.org</Email>. </para>
 239       </listitem>
 240     </itemizedlist>
 241
 242     <sect2>
 243       <title>What to put in a bug report</title>
 244       <indexterm><primary>bug reports</primary><secondary>contents</secondary></indexterm>
 245
 246       <para>The name of the bug-reporting game is: facts, facts,
 247       facts.  Don't omit them because &ldquo;Oh, they won't be
 248       interested&hellip;&rdquo;</para>
 249
 250       <orderedlist>
 251         <listitem>
 252           <para>What kind of machine are you running on, and exactly
 253           what version of the operating system are you using?
 254           (on a Unix system, <Command>uname -a</Command> or <Command>cat
 255           /etc/motd</Command> will show the desired information.)</para>
 256         </listitem>
 257
 258         <listitem>
 259           <para> What version of GCC are you using? <Command>gcc
 260           -v</Command> will tell you.</para>
 261         </listitem>
 262
 263         <listitem>
 264           <para> Run the sequence of compiles/runs that caused the
 265           offending behaviour, capturing all the input/output in a
 266           &ldquo;script&rdquo; (a UNIX command) or in an Emacs shell
 267           window.  We'd prefer to see the whole thing.</para>
 268         </listitem>
 269
 270         <listitem>
 271           <para> Be sure any Haskell compilations are run with a
 272           <Option>-v</Option> (verbose) flag, so we can see exactly
 273           what was run, what versions of things you have, etc.</para>
 274         </listitem>
 275
 276         <listitem>
 277           <para> What is the program behaviour that is wrong, in your
 278           opinion?</para>
 279         </listitem>
 280
 281         <listitem>
 282           <para> If practical, please send enough source files for us
 283           to duplicate the problem.</para>
 284         </listitem>
 285
 286         <listitem>
 287           <para> If you are a Hero and track down the problem in the
 288           compilation-system sources, please send us patches relative
 289           to a known released version of GHC, or whole files if you
 290           prefer.</para>
 291         </listitem>
 292       </orderedlist>
 293     </sect2>
 294   </sect1>
 295
 296   <sect1 id="version-numbering">
 297     <title>GHC version numbering policy</title>
 298     <indexterm><primary>version, of ghc</primary></indexterm>
 299
 300     <para>As of GHC version 4.08, we have adopted the following
 301     policy for numbering GHC versions:</para>
 302
 303     <variablelist>
 304       <varlistentry>
 305         <term>Stable Releases</term>
 306         <listitem>
 307           <para>These are numbered <literal>x.yy.z</literal>, where
 308           <literal>yy</literal> is <emphasis>even</emphasis>, and
 309           <literal>z</literal> is the patchlevel number (the trailing
 310           <literal>.z</literal> can be omitted if <literal>z</literal>
 311           is zero).  Patchlevels are bug-fix releases only, and never
 312           change the programmer interface to any system-supplied code.
 313           However, if you install a new patchlevel over an old one you
 314           will need to recompile any code that was compiled against the
 315           old libraries.</para>
 316
 317           <para>The value of <literal>__GLASGOW_HASKELL__</literal>
 318           (see <xref linkend="c-pre-processor">) for a major release
 319           <literal>x.yy.z</literal> is the integer
 320           <literal>xyy</literal>.</para>
 321           <indexterm>
 322             <primary><literal>__GLASGOW_HASKELL__</literal></primary>
 323           </indexterm>
 324         </listitem>
 325       </varlistentry>
 326
 327       <varlistentry>
 328         <term>Snapshots/unstable releases</term>
 329         <listitem>
 330           <para>We may make snapshot releases of the current
 331           development sources from time to time, and the current
 332           sources are always available via the CVS repository (see the
 333           GHC web site for details).</para>
 334
 335           <para>Snapshot releases are named
 336           <literal>x.yy.YYYYMMDD</literal> where <literal>yy</literal>
 337           is <emphasis>odd</emphasis>, and <literal>YYYYMMDD</literal>
 338           is the date of the sources from which the snapshot was
 339           built.  In theory, you can check out the exact same sources
 340           from the CVS repository using this date.</para>
 341
 342           <para>The value of <literal>__GLASGOW_HASKELL__</literal>
 343           for a snapshot release is the integer
 344           <literal>xyy</literal>.  You should never write any
 345           conditional code which tests for this value, however: since
 346           interfaces change on a day-to-day basis, and we don't have
 347           finer granularity in the values of
 348           <literal>__GLASGOW_HASKELL__</literal>, you should only
 349           conditionally compile using predicates which test whether
 350           <literal>__GLASGOW_HASKELL__</literal> is equal to, later
 351           than, or earlier than a given major release.</para>
 352           <indexterm>
 353             <primary><literal>__GLASGOW_HASKELL__</literal></primary>
 354           </indexterm>
 355         </listitem>
 356       </varlistentry>
 357     </variablelist>
 358
 359     <para>The version number of your copy of GHC can be found by
 360     invoking <literal>ghc</literal> with the
 361     <literal>&ndash;&ndash;version</literal> flag (see <xref
 362     linkend="options-help">).</para>
 363   </sect1>
 364
 365
 366 &relnotes
 367
 368 </Chapter>
 369
 370 <!-- Emacs stuff:
 371      ;;; Local Variables: ***
 372      ;;; mode: sgml ***
 373      ;;; sgml-parent-document: ("users_guide.sgml" "book" "chapter") ***
 374      ;;; End: ***
 375  -->