ghc/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           FAQ first (<xref linkend="faq"/>).</para>
  86
  87           <variablelist>
  88             <varlistentry>
  89               <term>list email address:</term>
  90               <listitem>
  91                 <para><email>glasgow-haskell-users@haskell.org</email></para>
  92               </listitem>
  93             </varlistentry>
  94
  95             <varlistentry>
  96               <term>subscribe at:</term>
  97               <listitem>
  98                 <para><ulink
  99               url="http://www.haskell.org/mailman/listinfo/glasgow-haskell-users"><literal>http://www.haskell.org/mailman/listinfo/glasgow-haskell-users</literal></ulink>.</para>
 100               </listitem>
 101             </varlistentry>
 102
 103             <varlistentry>
 104               <term>admin email address:</term>
 105               <listitem>
 106                 <para><email>glasgow-haskell-users-admin@haskell.org</email></para>
 107               </listitem>
 108             </varlistentry>
 109
 110             <varlistentry>
 111               <term>list archives:</term>
 112               <listitem>
 113                 <para><ulink
 114           url="http://www.haskell.org/pipermail/glasgow-haskell-users/"><literal>http://www.haskell.org/pipermail/glasgow-haskell-users/</literal></ulink></para>
 115               </listitem>
 116             </varlistentry>
 117           </variablelist>
 118         </listitem>
 119       </varlistentry>
 120
 121       <varlistentry>
 122         <term>glasgow-haskell-bugs:</term>
 123         <listitem>
 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>
 127
 128           <variablelist>
 129             <varlistentry>
 130               <term>list email address:</term>
 131               <listitem>
 132                 <para><email>glasgow-haskell-bugs@haskell.org</email></para>
 133               </listitem>
 134             </varlistentry>
 135
 136             <varlistentry>
 137               <term>subscribe at:</term>
 138               <listitem>
 139                 <para><ulink
 140               url="http://www.haskell.org/mailman/listinfo/glasgow-haskell-bugs"><literal>http://www.haskell.org/mailman/listinfo/glasgow-haskell-bugs</literal></ulink>.</para>
 141               </listitem>
 142             </varlistentry>
 143
 144             <varlistentry>
 145               <term>admin email address:</term>
 146               <listitem>
 147                 <para><email>glasgow-haskell-bugs-admin@haskell.org</email></para>
 148               </listitem>
 149             </varlistentry>
 150
 151             <varlistentry>
 152               <term>list archives:</term>
 153               <listitem>
 154                 <para><ulink
 155           url="http://www.haskell.org/pipermail/glasgow-haskell-bugs/"><literal>http://www.haskell.org/pipermail/glasgow-haskell-bugs/</literal></ulink></para>
 156               </listitem>
 157             </varlistentry>
 158           </variablelist>
 159         </listitem>
 160       </varlistentry>
 161
 162       <varlistentry>
 163         <term>cvs-ghc:</term>
 164         <listitem>
 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>
 170           etc.)</para>
 171
 172           <variablelist>
 173             <varlistentry>
 174               <term>list email address:</term>
 175               <listitem>
 176                 <para><email>cvs-ghc@haskell.org</email></para>
 177               </listitem>
 178             </varlistentry>
 179
 180             <varlistentry>
 181               <term>subscribe at:</term>
 182               <listitem>
 183                 <para><ulink
 184               url="http://www.haskell.org/mailman/listinfo/cvs-ghc"><literal>http://www.haskell.org/mailman/listinfo/cvs-ghc</literal></ulink>.</para>
 185               </listitem>
 186             </varlistentry>
 187
 188             <varlistentry>
 189               <term>admin email address:</term>
 190               <listitem>
 191                 <para><email>cvs-ghc-admin@haskell.org</email></para>
 192               </listitem>
 193             </varlistentry>
 194
 195             <varlistentry>
 196               <term>list archives:</term>
 197               <listitem>
 198                 <para><ulink
 199           url="http://www.haskell.org/pipermail/cvs-ghc/"><literal>http://www.haskell.org/pipermail/cvs-ghc/</literal></ulink></para>
 200               </listitem>
 201             </varlistentry>
 202           </variablelist>
 203         </listitem>
 204       </varlistentry>
 205     </variablelist>
 206
 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>
 211
 212     <para>Some Haskell-related discussion also takes place in the
 213     Usenet newsgroup <literal>comp.lang.functional</literal>.</para>
 214
 215   </sect1>
 216
 217   <sect1 id="bug-reporting">
 218     <title>Reporting bugs in GHC</title>
 219     <indexterm><primary>bugs</primary><secondary>reporting</secondary>
 220     </indexterm>
 221     <indexterm><primary>reporting bugs</primary>
 222     </indexterm>
 223
 224     <para>Glasgow Haskell is a changing system so there are sure to be
 225     bugs in it. </para>
 226
 227     <para>To report a bug, either:</para>
 228
 229     <itemizedlist>
 230       <listitem>
 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>
 237       </listitem>
 238       <listitem>
 239         <para>Email your bug report to
 240     <email>glasgow-haskell-bugs@haskell.org</email>. </para>
 241       </listitem>
 242     </itemizedlist>
 243
 244     <sect2>
 245       <title>How do I tell if I should report my bug?</title>
 246
 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
 250       not.</para>
 251
 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
 256       pretty well: enter
 257       <quote><literal>site:www.haskell.org</literal></quote> followed
 258       by your search term into Google.</para>
 259
 260       <para>If in doubt, just report it.</para>
 261     </sect2>
 262
 263     <sect2>
 264       <title>What to put in a bug report</title>
 265       <indexterm><primary>bug reports</primary><secondary>contents</secondary></indexterm>
 266
 267       <para>The name of the bug-reporting game is: facts, facts,
 268       facts.  Don't omit them because &ldquo;Oh, they won't be
 269       interested&hellip;&rdquo;</para>
 270
 271       <orderedlist>
 272         <listitem>
 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>
 277         </listitem>
 278
 279         <listitem>
 280           <para> What version of GCC are you using? <command>gcc
 281           -v</command> will tell you.</para>
 282         </listitem>
 283
 284         <listitem>
 285           <para> Run the sequence of compiles/runs that caused the
 286           offending behaviour, capturing all the input/output in a
 287           &ldquo;script&rdquo; (a UNIX command) or in an Emacs shell
 288           window.  We'd prefer to see the whole thing.</para>
 289         </listitem>
 290
 291         <listitem>
 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>
 295         </listitem>
 296
 297         <listitem>
 298           <para> What is the program behaviour that is wrong, in your
 299           opinion?</para>
 300         </listitem>
 301
 302         <listitem>
 303           <para> If practical, please send enough source files for us
 304           to duplicate the problem.</para>
 305         </listitem>
 306
 307         <listitem>
 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
 311           prefer.</para>
 312         </listitem>
 313       </orderedlist>
 314     </sect2>
 315   </sect1>
 316
 317   <sect1 id="version-numbering">
 318     <title>GHC version numbering policy</title>
 319     <indexterm><primary>version, of ghc</primary></indexterm>
 320
 321     <para>As of GHC version 6.0, we have adopted the following policy
 322     for numbering GHC versions:</para>
 323
 324     <variablelist>
 325       <varlistentry>
 326         <term>Stable Releases</term>
 327         <listitem>
 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>
 337
 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>
 345           <indexterm>
 346             <primary><literal>__GLASGOW_HASKELL__</literal></primary>
 347           </indexterm>
 348         </listitem>
 349       </varlistentry>
 350
 351       <varlistentry>
 352         <term>Snapshots/unstable releases</term>
 353         <listitem>
 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>
 359
 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
 365           this date.</para>
 366
 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>
 374
 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>
 385           <indexterm>
 386             <primary><literal>__GLASGOW_HASKELL__</literal></primary>
 387           </indexterm>
 388         </listitem>
 389       </varlistentry>
 390     </variablelist>
 391
 392     <para>The version number of your copy of GHC can be found by
 393     invoking <literal>ghc</literal> with the
 394     <literal>&ndash;&ndash;version</literal> flag (see <xref
 395     linkend="options-help"/>).</para>
 396   </sect1>
 397
 398
 399 &relnotes;
 400
 401 </chapter>
 402
 403 <!-- Emacs stuff:
 404      ;;; Local Variables: ***
 405      ;;; mode: xml ***
 406      ;;; sgml-parent-document: ("users_guide.xml" "book" "chapter") ***
 407      ;;; End: ***
 408  -->