ghc/docs/users_guide/intro.sgml

   1 <Chapter id="introduction-GHC">
   2 <Title>Introduction to GHC
   3 </Title>
   4
   5 <Para>
   6 This is a guide to using the Glasgow Haskell compilation (GHC) system. It is
   7 a batch compiler for the Haskell&nbsp;98 language, with support for various
   8 Glasgow-only extensions. In this document, we assume that GHC has been
   9 installed at your site as <Literal>ghc</Literal>.  A separate document,
  10 &ldquo;Building and Installing the Glasgow Functional Programming Tools Suite&rdquo;,
  11 describes how to install <Literal>ghc</Literal>.
  12 </Para>
  13
  14 <Para>
  15 Many people will use GHC very simply: compile some
  16 modules&mdash;<Literal>ghc -c -O Foo.hs Bar.hs</Literal>; and link them&mdash;
  17 <Literal>ghc -o wiggle -O Foo.o Bar.o</Literal>.
  18 </Para>
  19
  20 <Para>
  21 But if you need to do something more complicated, GHC can do that,
  22 too:
  23
  24 <Screen>
  25 ghc -c -O -fno-foldr-build -dcore-lint -fvia-C -ddump-simpl Foo.lhs
  26 </Screen>
  27
  28 Stay tuned&mdash;all will be revealed!
  29 </Para>
  30
  31 <Para>
  32 The rest of this section provide some tutorial information
  33 on batch-style compilation; if you're familiar with these concepts
  34 already, then feel free to skip to the next section.
  35 </Para>
  36
  37 <Sect1 id="batch-system-parts">
  38 <Title>The (batch) compilation system components</Title>
  39
  40 <Para>
  41 The Glorious Haskell Compilation System, as with most UNIX (batch)
  42 compilation systems, has several interacting parts:
  43
  44 <OrderedList>
  45 <ListItem>
  46 <Para>
  47 A <Emphasis>driver</Emphasis><IndexTerm><Primary>driver
  48 program</Primary></IndexTerm>
  49 <Literal>ghc</Literal><IndexTerm><Primary>ghc</Primary></IndexTerm>&mdash;which
  50 you usually think of as &ldquo;the compiler&rdquo;&mdash;is a program
  51 that merely invokes/glues-together the other pieces of the system
  52 (listed below), passing the right options to each, slurping in the
  53 right libraries, etc.
  54 </Para>
  55 </ListItem>
  56
  57 <ListItem>
  58 <Para>
  59 A <Emphasis>literate pre-processor</Emphasis>
  60 <IndexTerm><Primary>literate pre-processor</Primary></IndexTerm>
  61 <IndexTerm><Primary>pre-processor, literate</Primary></IndexTerm>
  62 <Literal>unlit</Literal><IndexTerm><Primary>unlit</Primary></IndexTerm> that extracts Haskell
  63 code from a literate script; used if you believe in that sort of
  64 thing.
  65 </Para>
  66 </ListItem>
  67
  68 <ListItem>
  69 <Para>
  70 The <Emphasis>Haskellised C pre-processor</Emphasis>
  71 <IndexTerm><Primary>Haskellised C pre-processor</Primary></IndexTerm>
  72 <IndexTerm><Primary>C pre-processor, Haskellised</Primary></IndexTerm>
  73 <IndexTerm><Primary>pre-processor, Haskellised C</Primary></IndexTerm>
  74 <Literal>hscpp</Literal>,<IndexTerm><Primary>hscpp</Primary></IndexTerm> only needed by people requiring conditional
  75 compilation, probably for large systems.  The &ldquo;Haskellised&rdquo; part
  76 just means that <Literal>&num;line</Literal> directives in the output have been
  77 converted into proper Haskell <Literal>&lcub;-&num; LINE ... -&rcub;</Literal> pragmas. You must give an explicit <Literal>-cpp</Literal> option
  78 <IndexTerm><Primary>-cpp option</Primary></IndexTerm> for the C pre-processor to be invoked.
  79 </Para>
  80 </ListItem>
  81
  82 <ListItem>
  83 <Para>
  84 The <Emphasis>Haskell compiler</Emphasis>
  85 <IndexTerm><Primary>Haskell compiler</Primary></IndexTerm>
  86 <IndexTerm><Primary>compiler, Haskell</Primary></IndexTerm>
  87 <Literal>hsc</Literal>,<IndexTerm><Primary>hsc</Primary></IndexTerm>
  88 which&mdash;in normal use&mdash;takes its input from the C pre-processor
  89 and produces assembly-language output (sometimes: ANSI C output).
  90 </Para>
  91 </ListItem>
  92
  93 <ListItem>
  94 <Para>
  95 The <Emphasis>ANSI&nbsp;C Haskell high-level assembler :-)</Emphasis>
  96 <IndexTerm><Primary>ANSI C compiler</Primary></IndexTerm>
  97 <IndexTerm><Primary>high-level assembler</Primary></IndexTerm>
  98 <IndexTerm><Primary>assembler, high-level</Primary></IndexTerm>
  99 compiles <Literal>hsc</Literal>'s C output into assembly language for a particular
 100 target architecture.  In fact, the only C compiler we currently
 101 support is <Literal>gcc</Literal>, because we make use of certain extensions to the
 102 C language only supported by gcc.  Version 2.x is a must; we recommend
 103 version 2.7.2.1 for stability (we've heard both good and bad reports
 104 of later versions).
 105 </Para>
 106 </ListItem>
 107
 108 <ListItem>
 109 <Para>
 110 The <Emphasis>assembler</Emphasis><IndexTerm><Primary>assembler</Primary></IndexTerm>&mdash;a standard UNIX one, probably
 111 <Literal>as</Literal><IndexTerm><Primary>as</Primary></IndexTerm>.
 112 </Para>
 113 </ListItem>
 114
 115 <ListItem>
 116 <Para>
 117 The <Emphasis>linker</Emphasis><IndexTerm><Primary>linker</Primary></IndexTerm>&mdash;a standard UNIX one, probably
 118 <Literal>ld</Literal>.<IndexTerm><Primary>ld</Primary></IndexTerm>
 119 </Para>
 120 </ListItem>
 121
 122 <ListItem>
 123 <Para>
 124 A <Emphasis>runtime system</Emphasis>,<IndexTerm><Primary>runtime system</Primary></IndexTerm> including (most notably)
 125 a storage manager; the linker links in the code for this.
 126 </Para>
 127 </ListItem>
 128
 129 <ListItem>
 130 <Para>
 131 The <Emphasis>Haskell standard prelude</Emphasis><IndexTerm><Primary>standard prelude</Primary></IndexTerm>, a
 132 large library of standard functions, is linked in as well.
 133 </Para>
 134 </ListItem>
 135
 136 <ListItem>
 137 <Para>
 138 Parts of other <Emphasis>installed libraries</Emphasis> that you have at your site may be linked in also.
 139 </Para>
 140 </ListItem>
 141
 142 </OrderedList>
 143 </Para>
 144
 145 </Sect1>
 146
 147 <Sect1 id="compile-what-really-happens">
 148 <Title>What really happens when I &ldquo;compile&rdquo; a Haskell program?
 149 </Title>
 150
 151 <Para>
 152 You invoke the Glasgow Haskell compilation system through the
 153 driver program <Literal>ghc</Literal>.<IndexTerm><Primary>ghc</Primary></IndexTerm> For example, if you had typed a
 154 literate &ldquo;Hello, world!&rdquo; program into <Literal>hello.lhs</Literal>, and you then
 155 invoked:
 156
 157 <Screen>
 158 ghc hello.lhs
 159 </Screen>
 160
 161 </Para>
 162
 163 <Para>
 164 the following would happen:
 165
 166 <OrderedList>
 167 <ListItem>
 168
 169 <Para>
 170 The file <Literal>hello.lhs</Literal> is run through the literate-program
 171 code extractor <Literal>unlit</Literal><IndexTerm><Primary>unlit</Primary></IndexTerm>, feeding its output to
 172
 173 </Para>
 174 </ListItem>
 175 <ListItem>
 176
 177 <Para>
 178 The Haskell compiler proper <Literal>hsc</Literal><IndexTerm><Primary>hsc</Primary></IndexTerm>, which produces
 179 input for
 180
 181 </Para>
 182 </ListItem>
 183 <ListItem>
 184
 185 <Para>
 186 The assembler (or that ubiquitous &ldquo;high-level assembler,&rdquo; a C
 187 compiler), which produces an object file and passes it to
 188
 189 </Para>
 190 </ListItem>
 191 <ListItem>
 192
 193 <Para>
 194 The linker, which links your code with the appropriate libraries
 195 (including the standard prelude), producing an executable program in
 196 the default output file named <Literal>a.out</Literal>.
 197 </Para>
 198 </ListItem>
 199
 200 </OrderedList>
 201
 202 </Para>
 203
 204 <Para>
 205 You have considerable control over the compilation process.  You feed
 206 command-line arguments (call them &ldquo;options,&rdquo; for short) to the
 207 driver, <Literal>ghc</Literal>; the &ldquo;types&rdquo; of the input files (as encoded in
 208 their names' suffixes) also matter.
 209 </Para>
 210
 211 <Para>
 212 Here's hoping this is enough background so that you can read the rest
 213 of this guide!
 214 </Para>
 215
 216 </Sect1>
 217
 218   <Sect1 id="mailing-lists-GHC">
 219     <Title>Meta-information: Web sites, mailing lists, etc.</Title>
 220
 221     <IndexTerm><Primary>mailing lists, Glasgow Haskell</Primary></IndexTerm>
 222     <IndexTerm><Primary>Glasgow Haskell mailing lists</Primary></IndexTerm>
 223
 224 <Para>On the World-Wide Web, there are several URLs of likely
 225 interest:</Para>
 226
 227 <Para>
 228
 229 <ItemizedList>
 230 <ListItem>
 231
 232 <Para>
 233   <ULink
 234 URL="http://www.haskell.org/"
 235 >Haskell home page</ULink
 236 >
 237 </Para>
 238 </ListItem>
 239 <ListItem>
 240
 241 <Para>
 242   <ULink
 243 URL="http://www.haskell.org/ghc/"
 244 >GHC home page</ULink
 245 >
 246 </Para>
 247 </ListItem>
 248 <ListItem>
 249
 250 <Para>
 251   <ULink
 252 URL="http://www.cs.nott.ac.uk/Department/Staff/mpj/faq.html"
 253 >comp.lang.functional FAQ</ULink
 254 >
 255 </Para>
 256 </ListItem>
 257
 258 </ItemizedList>
 259
 260 </Para>
 261
 262 <Para>
 263 We run two mailing lists about Glasgow Haskell.  We encourage you to
 264 join, as you feel is appropriate.
 265 </Para>
 266
 267 <VariableList>
 268 <VarListEntry>
 269 <Term>glasgow-haskell-users:</Term>
 270 <ListItem>
 271 <Para>
 272 This list is for GHC users to chat among themselves.  Subscription can
 273 be done on-line at <ulink
 274 url="http://www.haskell.org/mailman/listinfo/glasgow-haskell-users"><literal>http://www.haskell.org/mailman/listinfo/glasgow-haskell-users</literal></ulink>.</para>
 275
 276 <Para>
 277 To communicate with your fellow users, send mail to <email>glasgow-haskell-users@haskell.org</email>.
 278 </Para>
 279
 280 <Para>
 281 To contact the list administrator, send mail to
 282 <email>glasgow-haskell-users-admin@haskell.org</email>.  An archive
 283 of the list is available at <ulink url="http://www.haskell.org/pipermail/glasgow-haskell-users/"><literal>http://www.haskell.org/pipermail/glasgow-haskell-users/</literal></ulink>.
 284
 285 </Para>
 286 </ListItem>
 287 </VarListEntry>
 288 <VarListEntry>
 289 <Term>glasgow-haskell-bugs:</Term>
 290 <ListItem>
 291 <Para>
 292 Send bug reports for GHC to this address!  The sad and lonely people
 293 who subscribe to this list will muse upon what's wrong and what you
 294 might do about it.
 295 </Para>
 296
 297 <para>Subscription can be done on-line at <ulink
 298 url="http://www.haskell.org/mailman/listinfo/glasgow-haskell-bugs"><literal>http://www.haskell.org/mailman/listinfo/glasgow-haskell-bugs</literal></ulink>.</para>
 299
 300 <Para>
 301 Again, you may contact the list administrator at
 302 <email>glasgow-haskell-bugs-admin@haskell.org</email>.  And, yes, an
 303 archive of the list is available on the Web at the <ulink url="http://www.haskell.org/pipermail/glasgow-haskell-bugs/"><literal>http://www.haskell.org/pipermail/glasgow-haskell-bugs/</literal></ulink>.</Para>
 304 </ListItem>
 305 </VarListEntry>
 306
 307             <varlistentry>
 308               <term>cvs-ghc:</term>
 309               <listitem>
 310                 <para>The hardcore GHC developers hang out here.  This
 311                 list also gets commit message from the CVS repository.
 312                 There are several other similar lists for other parts
 313                 of the CVS repository
 314                 (eg. <literal>cvs-hslibs</literal>,
 315                 <literal>cvs-happy</literal>,
 316                 <literal>cvs-hdirect</literal> etc.)</para>
 317
 318                 <para>To subscribe: <ulink
 319                 url="http://www.haskell.org/mailman/listinfo/cvs-ghc"><literal>http://www.haskell.org/mailman/listinfo/cvs-ghc</literal></ulink></para>
 320
 321               </listitem>
 322             </varlistentry>
 323           </variablelist>
 324
 325 <Para>
 326 There are several other haskell and GHC-related mailing lists served
 327 by <literal>www.haskell.org</literal>.  Go to <ulink
 328 url="http://www.haskell.org/mailman/listinfo/"><literal>http://www.haskell.org/mailman/listinfo/</literal></ulink>
 329 for the full list.</Para>
 330
 331 <Para>
 332 Some Haskell-related discussion also takes place in the Usenet
 333 newsgroup <Literal>comp.lang.functional</Literal>.
 334 </Para>
 335
 336   </Sect1>
 337
 338   <sect1 id="version-numbering">
 339     <title>GHC version numbering policy</title>
 340     <indexterm><primary>version, of ghc</primary></indexterm>
 341
 342     <para>As of GHC version 4.08, we have adopted the following
 343     policy for numbering GHC versions:</para>
 344
 345     <variablelist>
 346       <varlistentry>
 347         <term>Stable Releases</term>
 348         <listitem>
 349           <para>These are numbered <literal>x.yy.z</literal>, where
 350           <literal>yy</literal> is <emphasis>even</emphasis>, and
 351           <literal>z</literal> is the patchlevel number (the trailing
 352           <literal>.z</literal> can be omitted if <literal>z</literal>
 353           is zero).  Patchlevels are bug-fix releases only, and never
 354           change the programmer interface to any system-supplied code.
 355           However, if you install a new patchlevel over an old one you
 356           may need to recompile any code that was compiled against the
 357           old libraries.</para>
 358
 359           <para>The value of <literal>__GLASGOW_HASKELL__</literal>
 360           (see <xref linkend="c-pre-processor">) for a major release
 361           <literal>x.yy.z</literal> is the integer
 362           <literal>xyy</literal>.</para>
 363           <indexterm>
 364             <primary><literal>__GLASGOW_HASKELL__</literal></primary>
 365           </indexterm>
 366         </listitem>
 367       </varlistentry>
 368
 369       <varlistentry>
 370         <term>Snapshots/unstable releases</term>
 371         <listitem>
 372           <para>We may make snapshot releases of the current
 373           development sources from time to time, and the current
 374           sources are always available via the CVS repository (see the
 375           GHC web site for details).</para>
 376
 377           <para>Snapshot releases are named
 378           <literal>x.yy.YYYYMMDD</literal> where <literal>yy</literal>
 379           is <emphasis>odd</emphasis>, and <literal>YYYYMMDD</literal>
 380           is the date of the sources from which the snapshot was
 381           built.  In theory, you can check out the exact same sources
 382           from the CVS repository using this date.</para>
 383
 384           <para>The value of <literal>__GLASGOW_HASKELL__</literal>
 385           for a snapshot release is the integer
 386           <literal>xyy</literal>.  You should never write any
 387           conditional code which tests for this value, however: since
 388           interfaces change on a day-to-day basis, and we don't have
 389           finer granularity in the values of
 390           <literal>__GLASGOW_HASKELL__</literal>, you should only
 391           conditionally compile using predicates which test whether
 392           <literal>__GLASGOW_HASKELL__</literal> is equal to, later
 393           than, or earlier than a given major release.</para>
 394           <indexterm>
 395             <primary><literal>__GLASGOW_HASKELL__</literal></primary>
 396           </indexterm>
 397         </listitem>
 398       </varlistentry>
 399     </variablelist>
 400
 401     <para>The version number of your copy of GHC can be found by
 402     invoking <literal>ghc</literal> with the
 403     <literal>--version</literal> flag.</para>
 404   </sect1>
 405
 406
 407 &relnotes
 408
 409 </Chapter>
 410
 411 <!-- Emacs stuff:
 412      ;;; Local Variables: ***
 413      ;;; mode: sgml ***
 414      ;;; sgml-parent-document: ("users_guide.sgml" "book" "chapter") ***
 415      ;;; End: ***
 416  -->