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>
 227         Glasgow Haskell is a changing system so there are sure to be
 228         bugs in it. If you find one, please see
 229         <ulink url="http://hackage.haskell.org/trac/ghc/wiki/ReportABug">this wiki page</ulink>
 230         for information on how to report it.
 231     </para>
 232
 233   </sect1>
 234
 235   <sect1 id="version-numbering">
 236     <title>GHC version numbering policy</title>
 237     <indexterm><primary>version, of ghc</primary></indexterm>
 238
 239     <para>As of GHC version 6.8, we have adopted the following policy
 240     for numbering GHC versions:</para>
 241
 242     <variablelist>
 243       <varlistentry>
 244         <term>Stable Releases</term>
 245         <listitem>
 246           <para>Stable branches are numbered <literal><replaceable>x</replaceable>.<replaceable>y</replaceable></literal>, where
 247           <replaceable>y</replaceable> is <emphasis>even</emphasis>.
 248           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
 249           <replaceable>z</replaceable> (>= 1) is the patchlevel number.
 250           Patchlevels are bug-fix releases only, and never
 251           change the programmer interface to any system-supplied code.
 252           However, if you install a new patchlevel over an old one you
 253           will need to recompile any code that was compiled against the
 254           old libraries.</para>
 255
 256           <para>The value of <literal>__GLASGOW_HASKELL__</literal>
 257           (see <xref linkend="c-pre-processor"/>) for a major release
 258           <literal><replaceable>x</replaceable>.<replaceable>y</replaceable>.<replaceable>z</replaceable></literal>
 259           is the integer <replaceable>xyy</replaceable> (if
 260           <replaceable>y</replaceable> is a single digit, then a leading zero
 261           is added, so for example in version 6.8.2 of GHC we would have
 262           <literal>__GLASGOW_HASKELL__==608</literal>).</para>
 263           <indexterm>
 264             <primary><literal>__GLASGOW_HASKELL__</literal></primary>
 265           </indexterm>
 266         </listitem>
 267       </varlistentry>
 268
 269       <varlistentry>
 270         <term>Stable snapshots</term>
 271         <listitem>
 272           <para>
 273       We may make snapshot releases of the current
 274       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>.
 275           </para>
 276
 277           <para>Stable snapshot releases are named
 278           <literal><replaceable>x</replaceable>.<replaceable>y</replaceable>.<replaceable>z</replaceable>.<replaceable>YYYYMMDD</replaceable></literal>.
 279           where <literal><replaceable>YYYYMMDD</replaceable></literal> is the date of the sources
 280           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.
 281           For example, <literal>6.8.1.20040225</literal> would be a
 282           snapshot of the <literal>6.8</literal> branch during the development
 283       of <literal>6.8.2</literal>.</para>
 284
 285           <para>The value of <literal>__GLASGOW_HASKELL__</literal>
 286           for a snapshot release is the integer
 287           <replaceable>xyy</replaceable>.  You should never write any
 288           conditional code which tests for this value, however: since
 289           interfaces change on a day-to-day basis, and we don't have
 290           finer granularity in the values of
 291           <literal>__GLASGOW_HASKELL__</literal>, you should only
 292           conditionally compile using predicates which test whether
 293           <literal>__GLASGOW_HASKELL__</literal> is equal to, later
 294           than, or earlier than a given major release.</para>
 295           <indexterm>
 296             <primary><literal>__GLASGOW_HASKELL__</literal></primary>
 297           </indexterm>
 298         </listitem>
 299       </varlistentry>
 300
 301       <varlistentry>
 302         <term>Unstable snapshots</term>
 303         <listitem>
 304           <para>
 305       We may make snapshot releases of the
 306       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>.
 307           </para>
 308
 309           <para>Unstable snapshot releases are named
 310           <literal><replaceable>x</replaceable>.<replaceable>y</replaceable>.<replaceable>YYYYMMDD</replaceable></literal>.
 311           where <literal><replaceable>YYYYMMDD</replaceable></literal> is the date of the sources
 312           from which the snapshot was built.
 313           For example, <literal>6.7.20040225</literal> would be a
 314           snapshot of the HEAD before the creation of the
 315       <literal>6.8</literal> branch.</para>
 316
 317           <para>The value of <literal>__GLASGOW_HASKELL__</literal>
 318           for a snapshot release is the integer
 319           <replaceable>xyy</replaceable>.  You should never write any
 320           conditional code which tests for this value, however: since
 321           interfaces change on a day-to-day basis, and we don't have
 322           finer granularity in the values of
 323           <literal>__GLASGOW_HASKELL__</literal>, you should only
 324           conditionally compile using predicates which test whether
 325           <literal>__GLASGOW_HASKELL__</literal> is equal to, later
 326           than, or earlier than a given major release.</para>
 327           <indexterm>
 328             <primary><literal>__GLASGOW_HASKELL__</literal></primary>
 329           </indexterm>
 330         </listitem>
 331       </varlistentry>
 332     </variablelist>
 333
 334     <para>The version number of your copy of GHC can be found by
 335     invoking <literal>ghc</literal> with the
 336     <literal>&ndash;&ndash;version</literal> flag (see <xref
 337     linkend="options-help"/>).</para>
 338   </sect1>
 339
 340
 341 &relnotes;
 342
 343 </chapter>
 344
 345 <!-- Emacs stuff:
 346      ;;; Local Variables: ***
 347      ;;; mode: xml ***
 348      ;;; sgml-parent-document: ("users_guide.xml" "book" "chapter") ***
 349      ;;; End: ***
 350  -->