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