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 number of libraries. These 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           <ulink
  85           url="http://haskell.org/haskellwiki/GHC/FAQ">FAQ</ulink>
  86           first.</para>
  87
  88           <variablelist>
  89             <varlistentry>
  90               <term>list email address:</term>
  91               <listitem>
  92                 <para><email>glasgow-haskell-users@haskell.org</email></para>
  93               </listitem>
  94             </varlistentry>
  95
  96             <varlistentry>
  97               <term>subscribe at:</term>
  98               <listitem>
  99                 <para><ulink
 100               url="http://www.haskell.org/mailman/listinfo/glasgow-haskell-users"><literal>http://www.haskell.org/mailman/listinfo/glasgow-haskell-users</literal></ulink>.</para>
 101               </listitem>
 102             </varlistentry>
 103
 104             <varlistentry>
 105               <term>admin email address:</term>
 106               <listitem>
 107                 <para><email>glasgow-haskell-users-admin@haskell.org</email></para>
 108               </listitem>
 109             </varlistentry>
 110
 111             <varlistentry>
 112               <term>list archives:</term>
 113               <listitem>
 114                 <para><ulink
 115           url="http://www.haskell.org/pipermail/glasgow-haskell-users/"><literal>http://www.haskell.org/pipermail/glasgow-haskell-users/</literal></ulink></para>
 116               </listitem>
 117             </varlistentry>
 118           </variablelist>
 119         </listitem>
 120       </varlistentry>
 121
 122       <varlistentry>
 123         <term>glasgow-haskell-bugs:</term>
 124         <listitem>
 125           <para>Send bug reports for GHC to this address!  The sad and
 126           lonely people who subscribe to this list will muse upon
 127           what's wrong and what you might do about it.</para>
 128
 129           <variablelist>
 130             <varlistentry>
 131               <term>list email address:</term>
 132               <listitem>
 133                 <para><email>glasgow-haskell-bugs@haskell.org</email></para>
 134               </listitem>
 135             </varlistentry>
 136
 137             <varlistentry>
 138               <term>subscribe at:</term>
 139               <listitem>
 140                 <para><ulink
 141               url="http://www.haskell.org/mailman/listinfo/glasgow-haskell-bugs"><literal>http://www.haskell.org/mailman/listinfo/glasgow-haskell-bugs</literal></ulink>.</para>
 142               </listitem>
 143             </varlistentry>
 144
 145             <varlistentry>
 146               <term>admin email address:</term>
 147               <listitem>
 148                 <para><email>glasgow-haskell-bugs-admin@haskell.org</email></para>
 149               </listitem>
 150             </varlistentry>
 151
 152             <varlistentry>
 153               <term>list archives:</term>
 154               <listitem>
 155                 <para><ulink
 156           url="http://www.haskell.org/pipermail/glasgow-haskell-bugs/"><literal>http://www.haskell.org/pipermail/glasgow-haskell-bugs/</literal></ulink></para>
 157               </listitem>
 158             </varlistentry>
 159           </variablelist>
 160         </listitem>
 161       </varlistentry>
 162
 163       <varlistentry>
 164         <term>cvs-ghc:</term>
 165         <listitem>
 166           <para>The hardcore GHC developers hang out here.  This list
 167           also gets commit message from the CVS repository.  There are
 168           several other similar lists for other parts of the CVS
 169           repository (eg. <literal>cvs-hslibs</literal>,
 170           <literal>cvs-happy</literal>, <literal>cvs-hdirect</literal>
 171           etc.)</para>
 172
 173           <variablelist>
 174             <varlistentry>
 175               <term>list email address:</term>
 176               <listitem>
 177                 <para><email>cvs-ghc@haskell.org</email></para>
 178               </listitem>
 179             </varlistentry>
 180
 181             <varlistentry>
 182               <term>subscribe at:</term>
 183               <listitem>
 184                 <para><ulink
 185               url="http://www.haskell.org/mailman/listinfo/cvs-ghc"><literal>http://www.haskell.org/mailman/listinfo/cvs-ghc</literal></ulink>.</para>
 186               </listitem>
 187             </varlistentry>
 188
 189             <varlistentry>
 190               <term>admin email address:</term>
 191               <listitem>
 192                 <para><email>cvs-ghc-admin@haskell.org</email></para>
 193               </listitem>
 194             </varlistentry>
 195
 196             <varlistentry>
 197               <term>list archives:</term>
 198               <listitem>
 199                 <para><ulink
 200           url="http://www.haskell.org/pipermail/cvs-ghc/"><literal>http://www.haskell.org/pipermail/cvs-ghc/</literal></ulink></para>
 201               </listitem>
 202             </varlistentry>
 203           </variablelist>
 204         </listitem>
 205       </varlistentry>
 206     </variablelist>
 207
 208     <para>There are several other haskell and GHC-related mailing
 209     lists served by <literal>www.haskell.org</literal>.  Go to <ulink
 210     url="http://www.haskell.org/mailman/listinfo/"><literal>http://www.haskell.org/mailman/listinfo/</literal></ulink>
 211     for the full list.</para>
 212
 213     <para>Some Haskell-related discussion also takes place in the
 214     Usenet newsgroup <literal>comp.lang.functional</literal>.</para>
 215
 216   </sect1>
 217
 218   <sect1 id="bug-reporting">
 219     <title>Reporting bugs in GHC</title>
 220     <indexterm><primary>bugs</primary><secondary>reporting</secondary>
 221     </indexterm>
 222     <indexterm><primary>reporting bugs</primary>
 223     </indexterm>
 224
 225     <para>
 226         Glasgow Haskell is a changing system so there are sure to be
 227         bugs in it. If you find one, please see
 228         <ulink url="http://hackage.haskell.org/trac/ghc/wiki/ReportABug">this wiki page</ulink>
 229         for information on how to report it.
 230     </para>
 231
 232   </sect1>
 233
 234   <sect1 id="version-numbering">
 235     <title>GHC version numbering policy</title>
 236     <indexterm><primary>version, of ghc</primary></indexterm>
 237
 238     <para>As of GHC version 6.8, we have adopted the following policy
 239     for numbering GHC versions:</para>
 240
 241     <variablelist>
 242       <varlistentry>
 243         <term>Stable Releases</term>
 244         <listitem>
 245           <para>Stable branches are numbered <literal><replaceable>x</replaceable>.<replaceable>y</replaceable></literal>, where
 246           <replaceable>y</replaceable> is <emphasis>even</emphasis>.
 247           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
 248           <replaceable>z</replaceable> (>= 1) is the patchlevel number.
 249           Patchlevels are bug-fix releases only, and never
 250           change the programmer interface to any system-supplied code.
 251           However, if you install a new patchlevel over an old one you
 252           will need to recompile any code that was compiled against the
 253           old libraries.</para>
 254
 255           <para>The value of <literal>__GLASGOW_HASKELL__</literal>
 256           (see <xref linkend="c-pre-processor"/>) for a major release
 257           <literal><replaceable>x</replaceable>.<replaceable>y</replaceable>.<replaceable>z</replaceable></literal>
 258           is the integer <replaceable>xyy</replaceable> (if
 259           <replaceable>y</replaceable> is a single digit, then a leading zero
 260           is added, so for example in version 6.8.2 of GHC we would have
 261           <literal>__GLASGOW_HASKELL__==608</literal>).</para>
 262           <indexterm>
 263             <primary><literal>__GLASGOW_HASKELL__</literal></primary>
 264           </indexterm>
 265         </listitem>
 266       </varlistentry>
 267
 268       <varlistentry>
 269         <term>Stable snapshots</term>
 270         <listitem>
 271           <para>
 272       We may make snapshot releases of the current
 273       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>.
 274           </para>
 275
 276           <para>Stable snapshot releases are named
 277           <literal><replaceable>x</replaceable>.<replaceable>y</replaceable>.<replaceable>z</replaceable>.<replaceable>YYYYMMDD</replaceable></literal>.
 278           where <literal><replaceable>YYYYMMDD</replaceable></literal> is the date of the sources
 279           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.
 280           For example, <literal>6.8.1.20040225</literal> would be a
 281           snapshot of the <literal>6.8</literal> branch during the development
 282       of <literal>6.8.2</literal>.</para>
 283
 284           <para>The value of <literal>__GLASGOW_HASKELL__</literal>
 285           for a snapshot release is the integer
 286           <replaceable>xyy</replaceable>.  You should never write any
 287           conditional code which tests for this value, however: since
 288           interfaces change on a day-to-day basis, and we don't have
 289           finer granularity in the values of
 290           <literal>__GLASGOW_HASKELL__</literal>, you should only
 291           conditionally compile using predicates which test whether
 292           <literal>__GLASGOW_HASKELL__</literal> is equal to, later
 293           than, or earlier than a given major release.</para>
 294           <indexterm>
 295             <primary><literal>__GLASGOW_HASKELL__</literal></primary>
 296           </indexterm>
 297         </listitem>
 298       </varlistentry>
 299
 300       <varlistentry>
 301         <term>Unstable snapshots</term>
 302         <listitem>
 303           <para>
 304       We may make snapshot releases of the
 305       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>.
 306           </para>
 307
 308           <para>Unstable snapshot releases are named
 309           <literal><replaceable>x</replaceable>.<replaceable>y</replaceable>.<replaceable>YYYYMMDD</replaceable></literal>.
 310           where <literal><replaceable>YYYYMMDD</replaceable></literal> is the date of the sources
 311           from which the snapshot was built.
 312           For example, <literal>6.7.20040225</literal> would be a
 313           snapshot of the HEAD before the creation of the
 314       <literal>6.8</literal> branch.</para>
 315
 316           <para>The value of <literal>__GLASGOW_HASKELL__</literal>
 317           for a snapshot release is the integer
 318           <replaceable>xyy</replaceable>.  You should never write any
 319           conditional code which tests for this value, however: since
 320           interfaces change on a day-to-day basis, and we don't have
 321           finer granularity in the values of
 322           <literal>__GLASGOW_HASKELL__</literal>, you should only
 323           conditionally compile using predicates which test whether
 324           <literal>__GLASGOW_HASKELL__</literal> is equal to, later
 325           than, or earlier than a given major release.</para>
 326           <indexterm>
 327             <primary><literal>__GLASGOW_HASKELL__</literal></primary>
 328           </indexterm>
 329         </listitem>
 330       </varlistentry>
 331     </variablelist>
 332
 333     <para>The version number of your copy of GHC can be found by
 334     invoking <literal>ghc</literal> with the
 335     <literal>&ndash;&ndash;version</literal> flag (see <xref
 336     linkend="options-help"/>).</para>
 337   </sect1>
 338
 339
 340 &relnotes;
 341
 342 </chapter>
 343
 344 <!-- Emacs stuff:
 345      ;;; Local Variables: ***
 346      ;;; mode: xml ***
 347      ;;; sgml-parent-document: ("users_guide.xml" "book" "chapter") ***
 348      ;;; End: ***
 349  -->