path: root/ghc/docs/users_guide/intro.xml

<?xml version="1.0" encoding="iso-8859-1"?>
<chapter id="introduction-GHC">
  <title>Introduction to GHC</title>

  <para>This is a guide to using the Glasgow Haskell Compiler (GHC):
  an interactive and batch compilation system for the <ulink
  url="http://www.haskell.org/">Haskell&nbsp;98</ulink>
  language.</para>

  <para>GHC has two main components: an interactive Haskell
  interpreter (also known as GHCi), described in <xref
  linkend="ghci"/>, and a batch compiler, described throughout <xref
  linkend="using-ghc"/>.  In fact, GHC consists of a single program
  which is just run with different options to provide either the
  interactive or the batch system.</para>

  <para>The batch compiler can be used alongside GHCi: compiled
  modules can be loaded into an interactive session and used in the
  same way as interpreted code, and in fact when using GHCi most of
  the library code will be pre-compiled.  This means you get the best
  of both worlds: fast pre-compiled library code, and fast compile
  turnaround for the parts of your program being actively
  developed.</para>

  <para>GHC supports numerous language extensions, including
  concurrency, a foreign function interface, exceptions, type system
  extensions such as multi-parameter type classes, local universal and
  existential quantification, functional dependencies, scoped type
  variables and explicit unboxed types.  These are all described in
  <xref linkend="ghc-language-features"/>.</para>

  <para>GHC has a comprehensive optimiser, so when you want to Really
  Go For It (and you've got time to spare) GHC can produce pretty fast
  code.  Alternatively, the default option is to compile as fast as
  possible while not making too much effort to optimise the generated
  code (although GHC probably isn't what you'd describe as a fast
  compiler :-).</para>
  
  <para>GHC's profiling system supports &ldquo;cost centre
  stacks&rdquo;: a way of seeing the profile of a Haskell program in a
  call-graph like structure.  See <xref linkend="profiling"/> for more
  details.</para>

  <para>GHC comes with a large collection of libraries, with
  everything from parser combinators to networking.  The libraries are
  described in separate documentation.</para>

  <sect1 id="mailing-lists-GHC">
    <title>Meta-information: Web sites, mailing lists, etc.</title>

    <indexterm><primary>mailing lists, Glasgow Haskell</primary></indexterm>
    <indexterm><primary>Glasgow Haskell mailing lists</primary></indexterm>

    <para>On the World-Wide Web, there are several URLs of likely
    interest:</para>

    <itemizedlist>
      <listitem>
	<para><ulink url="http://www.haskell.org/" >Haskell home
	page</ulink></para>
      </listitem>

      <listitem>
	<para><ulink url="http://www.haskell.org/ghc/">GHC home
	page</ulink></para>
      </listitem>

      <listitem>
	<para><ulink
	url="http://www.cs.nott.ac.uk/~gmh/faq.html">comp.lang.functional
	FAQ</ulink></para>
      </listitem>

    </itemizedlist>

    <para>We run the following mailing lists about Glasgow Haskell.
    We encourage you to join, as you feel is appropriate.</para>

    <variablelist>
      <varlistentry>
	<term>glasgow-haskell-users:</term>
	<listitem>
	  <para>This list is for GHC users to chat among themselves.
	  If you have a specific question about GHC, please check the
	  <ulink
	  url="http://hackage.haskell.org/trac/ghc/wiki/FAQ">FAQ</ulink>
	  first.</para>

	  <variablelist>
	    <varlistentry>
	      <term>list email address:</term>
	      <listitem>
		<para><email>glasgow-haskell-users@haskell.org</email></para>
	      </listitem>
	    </varlistentry>

	    <varlistentry>
	      <term>subscribe at:</term> 
	      <listitem>
		<para><ulink
	      url="http://www.haskell.org/mailman/listinfo/glasgow-haskell-users"><literal>http://www.haskell.org/mailman/listinfo/glasgow-haskell-users</literal></ulink>.</para>
	      </listitem>
	    </varlistentry>

	    <varlistentry>
	      <term>admin email address:</term>
	      <listitem>
		<para><email>glasgow-haskell-users-admin@haskell.org</email></para>
	      </listitem>
	    </varlistentry>

	    <varlistentry>
	      <term>list archives:</term>
	      <listitem>
		<para><ulink
          url="http://www.haskell.org/pipermail/glasgow-haskell-users/"><literal>http://www.haskell.org/pipermail/glasgow-haskell-users/</literal></ulink></para>
	      </listitem>
	    </varlistentry>
	  </variablelist>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term>glasgow-haskell-bugs:</term>
	<listitem>
	  <para>Send bug reports for GHC to this address!  The sad and
          lonely people who subscribe to this list will muse upon
          what's wrong and what you might do about it.</para>

	  <variablelist>
	    <varlistentry>
	      <term>list email address:</term>
	      <listitem>
		<para><email>glasgow-haskell-bugs@haskell.org</email></para>
	      </listitem>
	    </varlistentry>

	    <varlistentry>
	      <term>subscribe at:</term> 
	      <listitem>
		<para><ulink
	      url="http://www.haskell.org/mailman/listinfo/glasgow-haskell-bugs"><literal>http://www.haskell.org/mailman/listinfo/glasgow-haskell-bugs</literal></ulink>.</para>
	      </listitem>
	    </varlistentry>

	    <varlistentry>
	      <term>admin email address:</term>
	      <listitem>
		<para><email>glasgow-haskell-bugs-admin@haskell.org</email></para>
	      </listitem>
	    </varlistentry>

	    <varlistentry>
	      <term>list archives:</term>
	      <listitem>
		<para><ulink
          url="http://www.haskell.org/pipermail/glasgow-haskell-bugs/"><literal>http://www.haskell.org/pipermail/glasgow-haskell-bugs/</literal></ulink></para>
	      </listitem>
	    </varlistentry>
	  </variablelist>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term>cvs-ghc:</term>
	<listitem>
	  <para>The hardcore GHC developers hang out here.  This list
	  also gets commit message from the CVS repository.  There are
	  several other similar lists for other parts of the CVS
	  repository (eg. <literal>cvs-hslibs</literal>,
	  <literal>cvs-happy</literal>, <literal>cvs-hdirect</literal>
	  etc.)</para>
	  
	  <variablelist>
	    <varlistentry>
	      <term>list email address:</term>
	      <listitem>
		<para><email>cvs-ghc@haskell.org</email></para>
	      </listitem>
	    </varlistentry>

	    <varlistentry>
	      <term>subscribe at:</term> 
	      <listitem>
		<para><ulink
	      url="http://www.haskell.org/mailman/listinfo/cvs-ghc"><literal>http://www.haskell.org/mailman/listinfo/cvs-ghc</literal></ulink>.</para>
	      </listitem>
	    </varlistentry>

	    <varlistentry>
	      <term>admin email address:</term>
	      <listitem>
		<para><email>cvs-ghc-admin@haskell.org</email></para>
	      </listitem>
	    </varlistentry>

	    <varlistentry>
	      <term>list archives:</term>
	      <listitem>
		<para><ulink
          url="http://www.haskell.org/pipermail/cvs-ghc/"><literal>http://www.haskell.org/pipermail/cvs-ghc/</literal></ulink></para>
	      </listitem>
	    </varlistentry>
	  </variablelist>
	</listitem>
      </varlistentry>
    </variablelist>

    <para>There are several other haskell and GHC-related mailing
    lists served by <literal>www.haskell.org</literal>.  Go to <ulink
    url="http://www.haskell.org/mailman/listinfo/"><literal>http://www.haskell.org/mailman/listinfo/</literal></ulink>
    for the full list.</para>

    <para>Some Haskell-related discussion also takes place in the
    Usenet newsgroup <literal>comp.lang.functional</literal>.</para>

  </sect1>

  <sect1 id="bug-reporting">
    <title>Reporting bugs in GHC</title>
    <indexterm><primary>bugs</primary><secondary>reporting</secondary>
    </indexterm>
    <indexterm><primary>reporting bugs</primary>
    </indexterm>

    <para>Glasgow Haskell is a changing system so there are sure to be
    bugs in it. </para>

    <para>To report a bug, either:</para>

    <itemizedlist>
      <listitem>
	<para>Preferred: <ulink
    url="http://hackage.haskell.org/trac/ghc/newticket?type=bug">Create
    a new bug</ulink>, and enter your bug report.  You can also
    search the bug database here to make sure your bug hasn't already
    been reported (if it has, it might still help to add information
    from your experience to the existing report).</para>
      </listitem>
      <listitem>
	<para>Bug reports can also be emailed to
    <email>glasgow-haskell-bugs@haskell.org</email>. </para>
      </listitem>
    </itemizedlist>

    <sect2>
      <title>How do I tell if I should report my bug?</title>

      <para>Take a look at the <ulink
      url="http://hackage.haskell.org/trac/ghc/wiki/FAQ">FAQ</ulink> and <xref
      linkend="wrong"/>, which will give you some guidance as to
      whether the behaviour you're seeing is really a bug or
      not.</para>

      <para>If it is a bug, then it might have been reported before:
      try searching on the <ulink
      url="http://hackage.haskell.org/trac/ghc">bug tracker</ulink>,
      and failing that, try <ulink
      url="http://www.google.com">Google</ulink>.</para>

      <para>If in doubt, just report it.</para>
    </sect2>

    <sect2>
      <title>What to put in a bug report</title>
      <indexterm><primary>bug reports</primary><secondary>contents</secondary></indexterm>

      <para>The name of the bug-reporting game is: facts, facts,
      facts.  Don't omit them because &ldquo;Oh, they won't be
      interested&hellip;&rdquo;</para>

      <orderedlist>
	<listitem>
	  <para>What kind of machine are you running on, and exactly
          what version of the operating system are you using?  (on a
          Unix system, <command>uname -a</command> or <command>cat
          /etc/motd</command> will show the desired information.)  In
          the bug tracker, this information can be given in the
          &ldquo;Architecture&rdquo; and &ldquo;Operating
          system&rdquo; fields.</para>
	</listitem>

	<listitem>
	  <para>What version of GCC are you using? <command>gcc&nbsp;-v</command> will tell you.</para>
	</listitem>

	<listitem>
	  <para>Run the sequence of compiles/runs that caused the
          offending behaviour, cut-and-paste the whole session into
          the bug report.  We'd prefer to see the whole thing.</para>
	</listitem>

	<listitem>
	  <para>Add the -v flag when running GHC, so we can see exactly
          what was run, what versions of things you have, etc.</para>
	</listitem>

	<listitem>
	  <para>What is the program behaviour that is wrong, in your
	  opinion?</para>
	</listitem>

	<listitem>
	  <para>If practical, please attach or send enough source
          files for us to duplicate the problem.</para>
	</listitem>

	<listitem>
	  <para>If you are a Hero and track down the problem in the
          compilation-system sources, please send us patches (either
          <literal>darcs send</literal>, plain patches, or just whole
          files if you prefer).</para>
	</listitem>
      </orderedlist>
    </sect2>
  </sect1>

  <sect1 id="version-numbering">
    <title>GHC version numbering policy</title>
    <indexterm><primary>version, of ghc</primary></indexterm>

    <para>As of GHC version 6.0, we have adopted the following policy
    for numbering GHC versions:</para>

    <variablelist>
      <varlistentry>
	<term>Stable Releases</term>
	<listitem>
	  <para>These are numbered <literal><replaceable>x</replaceable>.<replaceable>y</replaceable>.<replaceable>z</replaceable></literal>, where
	  <replaceable>y</replaceable> is <emphasis>even</emphasis>, and
	  <replaceable>z</replaceable> is the patchlevel number (the trailing
	  <literal>.<replaceable>z</replaceable></literal> can be omitted if <replaceable>z</replaceable>
	  is zero).  Patchlevels are bug-fix releases only, and never
	  change the programmer interface to any system-supplied code.
	  However, if you install a new patchlevel over an old one you
	  will need to recompile any code that was compiled against the
	  old libraries.</para>

	  <para>The value of <literal>__GLASGOW_HASKELL__</literal>
	  (see <xref linkend="c-pre-processor"/>) for a major release
	  <literal><replaceable>x</replaceable>.<replaceable>y</replaceable>.<replaceable>z</replaceable></literal>
	  is the integer <replaceable>xyy</replaceable> (if
	  <replaceable>y</replaceable> is a single digit, then a leading zero
	  is added, so for example in version 6.2 of GHC,
	  <literal>__GLASGOW_HASKELL__==602</literal>).</para>
	  <indexterm>
	    <primary><literal>__GLASGOW_HASKELL__</literal></primary>
	  </indexterm>
	</listitem>
      </varlistentry>
      
      <varlistentry>
	<term>Snapshots/unstable releases</term>
	<listitem>
	  <para>We may make snapshot releases of the current
	  development sources from time to time, and the current
	  sources are always available via the CVS repository (see the
	  <ulink url="http://www.haskell.org/ghc/">GHC web
	  site</ulink> for details).</para>

	  <para>Snapshot releases are named
	  <literal><replaceable>x</replaceable>.<replaceable>y</replaceable>.YYYYMMDD</literal>
	  where <literal>YYYYMMDD</literal> is the date of the sources
	  from which the snapshot was built.  In theory, you can check
	  out the exact same sources from the CVS repository using
	  this date.</para>

	  <para>If <replaceable>y</replaceable> is odd, then this is a
	  snapshot of the CVS HEAD (the main development branch).  If
	  <replaceable>y</replaceable> is even, then it is a snapshot
	  of the stable branch between patchlevel releases.  For
	  example, <literal>6.3.20040225</literal> would be a snapshot
	  of the HEAD, but <literal>6.2.20040225</literal> would be a
	  snapshot of the <literal>6.2</literal> branch.</para>

	  <para>The value of <literal>__GLASGOW_HASKELL__</literal>
	  for a snapshot release is the integer
	  <replaceable>xyy</replaceable>.  You should never write any
	  conditional code which tests for this value, however: since
	  interfaces change on a day-to-day basis, and we don't have
	  finer granularity in the values of
	  <literal>__GLASGOW_HASKELL__</literal>, you should only
	  conditionally compile using predicates which test whether
	  <literal>__GLASGOW_HASKELL__</literal> is equal to, later
	  than, or earlier than a given major release.</para>
	  <indexterm>
	    <primary><literal>__GLASGOW_HASKELL__</literal></primary>
	  </indexterm>
	</listitem>
      </varlistentry>
    </variablelist>
    
    <para>The version number of your copy of GHC can be found by
    invoking <literal>ghc</literal> with the
    <literal>&ndash;&ndash;version</literal> flag (see <xref
    linkend="options-help"/>).</para>
  </sect1>


&relnotes;

</chapter>

<!-- Emacs stuff:
     ;;; Local Variables: ***
     ;;; mode: xml ***
     ;;; sgml-parent-document: ("users_guide.xml" "book" "chapter") ***
     ;;; End: ***
 -->