ghc/docs/users_guide/intro.vsgml

   1 <sect>Introduction to GHC
   2 <label id="introduction-GHC">
   3 <p>
   4
   5 This is a guide to using the Glasgow Haskell compilation (GHC) system.
   6 It is a batch compiler for the Haskell~98 language, with support for
   7 various Glasgow-only extensions.
   8 In this document, we assume that GHC has been installed at your site
   9 as @ghc@.  A separate document, ``Building and Installing the
  10 Glasgow Functional Programming Tools Suite'',
  11 describes how to install @ghc@.
  12
  13 Many people will use GHC very simply: compile some
  14 modules---@ghc -c -O Foo.hs Bar.hs@; and link them---
  15 @ghc -o wiggle -O Foo.o Bar.o@.
  16
  17 But if you need to do something more complicated, GHC can do that,
  18 too:
  19 <tscreen><verb>
  20 ghc -c -O -fno-foldr-build -dcore-lint -fvia-C -ddump-simpl Foo.lhs
  21 </verb></tscreen>
  22 Stay tuned---all will be revealed!
  23
  24 The rest of this section provide some tutorial information
  25 on batch-style compilation; if you're familiar with these concepts
  26 already, then feel free to skip to the next section.
  27
  28 %************************************************************************
  29 %*                                                                      *
  30 <sect1>The (batch) compilation system components
  31 <label id="batch-system-parts">
  32 <p>
  33 %*                                                                      *
  34 %************************************************************************
  35
  36 The Glorious Haskell Compilation System, as with most UNIX (batch)
  37 compilation systems, has several interacting parts:
  38 <enum>
  39 <item>
  40 A <em>driver</em><nidx>driver program</nidx> @ghc@<nidx>ghc</nidx>---which you
  41 usually think of as ``the compiler''---is a program that merely
  42 invokes/glues-together the other pieces of the system (listed below),
  43 passing the right options to each, slurping in the right libraries,
  44 etc.
  45
  46 <item>
  47 A <em>literate pre-processor</em>
  48 <nidx>literate pre-processor</nidx>
  49 <nidx>pre-processor, literate</nidx>
  50 @unlit@<nidx>unlit</nidx> that extracts Haskell
  51 code from a literate script; used if you believe in that sort of
  52 thing.
  53
  54 <item>
  55 The <em>Haskellised C pre-processor</em>
  56 <nidx>Haskellised C pre-processor</nidx>
  57 <nidx>C pre-processor, Haskellised</nidx>
  58 <nidx>pre-processor, Haskellised C</nidx>
  59 @hscpp@,<nidx>hscpp</nidx> only needed by people requiring conditional
  60 compilation, probably for large systems.  The ``Haskellised'' part
  61 just means that @#line@ directives in the output have been
  62 converted into proper Haskell @{-# LINE ... -@} pragmas.
  63
  64 You must give an explicit @-cpp@ option
  65 <nidx>-cpp option</nidx> for the C pre-processor to be invoked.
  66
  67 <item>
  68 The <em>Haskell compiler</em>
  69 <nidx>Haskell compiler</nidx>
  70 <nidx>compiler, Haskell</nidx>
  71 @hsc@,<nidx>hsc</nidx>
  72 which---in normal use---takes its input from the C pre-processor
  73 and produces assembly-language output (sometimes: ANSI C output).
  74
  75 <item>
  76 The <em>ANSI~C Haskell high-level assembler :-)</em>
  77 <nidx>ANSI C compiler</nidx>
  78 <nidx>high-level assembler</nidx>
  79 <nidx>assembler, high-level</nidx>
  80
  81 compiles @hsc@'s C output into assembly language for a particular
  82 target architecture.  In fact, the only C compiler we currently
  83 support is <tt/gcc/, because we make use of certain extensions to the
  84 C language only supported by gcc.  Version 2.x is a must; we recommend
  85 version 2.7.2.1 for stability (we've heard both good and bad reports
  86 of later versions).
  87
  88 <item>
  89 The <em>assembler</em><nidx>assembler</nidx>---a standard UNIX one, probably
  90 @as@<nidx>as</nidx>.
  91
  92 <item>
  93 The <em>linker</em><nidx>linker</nidx>---a standard UNIX one, probably
  94 @ld@.<nidx>ld</nidx>
  95
  96 <item>
  97 A <em>runtime system</em>,<nidx>runtime system</nidx> including (most notably)
  98 a storage manager; the linker links in the code for this.
  99
 100 <item>
 101 The <em>Haskell standard prelude</em><nidx>standard prelude</nidx>, a
 102 large library of standard functions, is linked in as well.
 103
 104 <item>
 105 Parts of other <em>installed libraries</em> that you have at your site
 106 may be linked in also.
 107 </enum>
 108
 109 %************************************************************************
 110 %*                                                                      *
 111 <sect1>What really happens when I ``compile'' a Haskell program?
 112 <label id="compile-what-really-happens">
 113 <p>
 114 %*                                                                      *
 115 %************************************************************************
 116
 117 You invoke the Glasgow Haskell compilation system through the
 118 driver program @ghc@.<nidx>ghc</nidx> For example, if you had typed a
 119 literate ``Hello, world!'' program into @hello.lhs@, and you then
 120 invoked:
 121 <tscreen><verb>
 122 ghc hello.lhs
 123 </verb></tscreen>
 124
 125 the following would happen:
 126 <enum>
 127 <item>
 128 The file @hello.lhs@ is run through the literate-program
 129 code extractor @unlit@<nidx>unlit</nidx>, feeding its output to
 130
 131 <item>
 132 The Haskell compiler proper @hsc@<nidx>hsc</nidx>, which produces
 133 input for
 134
 135 <item>
 136 The assembler (or that ubiquitous ``high-level assembler,'' a C
 137 compiler), which produces an object file and passes it to
 138
 139 <item>
 140 The linker, which links your code with the appropriate libraries
 141 (including the standard prelude), producing an executable program in
 142 the default output file named @a.out@.
 143 </enum>
 144
 145 You have considerable control over the compilation process.  You feed
 146 command-line arguments (call them ``options,'' for short) to the
 147 driver, @ghc@; the ``types'' of the input files (as encoded in
 148 their names' suffixes) also matter.
 149
 150 Here's hoping this is enough background so that you can read the rest
 151 of this guide!
 152
 153 % The ``style'' of the driver program @ghc@ follows that of the GNU C
 154 % compiler driver @gcc@.  The use of environment variables to provide
 155 % defaults is more extensive in this compilation system.
 156
 157 %--------------------------------------------------------------------
 158 <sect1>Meta-information: Web sites, mailing lists, etc.
 159 <label id="mailing-lists-GHC">
 160 <p>
 161 <nidx>mailing lists, Glasgow Haskell</nidx>
 162 <nidx>Glasgow Haskell mailing lists</nidx>
 163
 164 On the World-Wide Web, there are several URLs of likely interest:
 165
 166 <itemize>
 167 <item>  <url name="Haskell home page" url="http://www.haskell.org/">
 168 <item>  <url name="GHC home page"     url="http://www.haskell.org/ghc/">
 169 <item>  <url name="Glasgow FP group page" url="http://www.dcs.gla.ac.uk/fp/">
 170 <item>  <url name="comp.lang.functional FAQ" url="http://www.cs.nott.ac.uk/Department/Staff/mpj/faq.html">
 171 </itemize>
 172
 173 We run two mailing lists about Glasgow Haskell.  We encourage you to
 174 join, as you feel is appropriate.
 175
 176 <descrip>
 177
 178 <tag>glasgow-haskell-users:</tag>
 179
 180 This list is for GHC users to chat among themselves.  Subscribe by
 181 sending mail to <htmlurl name="majordomo@@haskell.org"
 182 url="mailto:majordomo@@haskell.org">, with a message body (not
 183 header) like this:
 184
 185 <tscreen><verb>
 186 subscribe glasgow-haskell-users MyName <m.y.self@@bigbucks.com>
 187 </verb></tscreen>
 188
 189 (The last bit is your all-important e-mail address, of course.)
 190
 191 To communicate with your fellow users, send mail to <url
 192 name="glasgow-haskell-users@@haskell.org"
 193 url="mailto:glasgow-haskell-users@@haskell.org">.
 194
 195 To contact the list administrator, send mail to <htmlurl
 196 name="glasgow-haskell-users-request@@haskell.org"
 197 url="mailto:glasgow-haskell-users-request@@haskell.org">.  An archive
 198 of the list is available on the Web: <url name="glasgow-haskell-users
 199 mailing list archive"
 200 url="http://www.dcs.gla.ac.uk/mail-www/glasgow-haskell-users">.
 201
 202 <tag>glasgow-haskell-bugs:</tag>
 203 Send bug reports for GHC to this address!  The sad and lonely people
 204 who subscribe to this list will muse upon what's wrong and what you
 205 might do about it.
 206
 207 Subscribe via <htmlurl name="majordomo@@haskell.org"
 208 url="mailto:majordomo@@haskell.org"> with:
 209
 210 <tscreen><verb>
 211 subscribe glasgow-haskell-bugs My Name <m.y.self@@hackers.r.us>
 212 </verb></tscreen>
 213
 214 Again, you may contact the list administrator at <htmlurl
 215 name="glasgow-haskell-bugs-request@@haskell.org"
 216 url="mailto:glasgow-haskell-bugs-request@@haskell.org">.
 217 And, yes, an archive of the list is available on the Web at: : <url
 218 name="glasgow-haskell-bugs mailing list archive"
 219 url="http://www.dcs.gla.ac.uk/mail-www/glasgow-haskell-bugs">
 220
 221 </descrip>
 222
 223 There is also the general Haskell mailing list.  Subscribe by sending
 224 email to <htmlurl name="majordomo@@dcs.gla.ac.uk"
 225 url="mailto:majordomo@@dcs.gla.ac.uk">, with the usual message body:
 226
 227 <tscreen><verb>
 228 subscribe haskell My Name <m.y.self@@fp.rules.ok.org>
 229 </verb></tscreen>
 230
 231 Some Haskell-related discussion takes place in the Usenet newsgroup
 232 @comp.lang.functional@.  (But note: news is basically dead at Glasgow.
 233 That's one reason Glaswegians aren't too active in c.f.l.)
 234
 235 The main anonymous-FTP site for Glasgow Haskell is <htmlurl
 236 name="ftp://ftp.dcs.gla.ac.uk/pub/haskell/glasgow"
 237 url="ftp://ftp.dcs.gla.ac.uk/pub/haskell/glasgow">.  ``Important''
 238 bits are mirrored at other Haskell archive sites (and we have their
 239 stuff, too).