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