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 program</Primary></IndexTerm>
  48 <Literal>ghc</Literal><IndexTerm><Primary>ghc</Primary></IndexTerm>&mdash;which
  49 you usually think of as &ldquo;the compiler&rdquo;&mdash;is a program that merely
  50 invokes/glues-together the other pieces of the system (listed below),
  51 passing the right options to each, slurping in the right libraries, etc.
  52 </Para>
  53 </ListItem>
  54
  55 <ListItem>
  56 <Para>
  57 A <Emphasis>literate pre-processor</Emphasis>
  58 <IndexTerm><Primary>literate pre-processor</Primary></IndexTerm>
  59 <IndexTerm><Primary>pre-processor, literate</Primary></IndexTerm>
  60 <Literal>unlit</Literal><IndexTerm><Primary>unlit</Primary></IndexTerm> that extracts Haskell
  61 code from a literate script; used if you believe in that sort of
  62 thing.
  63 </Para>
  64 </ListItem>
  65
  66 <ListItem>
  67 <Para>
  68 The <Emphasis>Haskellised C pre-processor</Emphasis>
  69 <IndexTerm><Primary>Haskellised C pre-processor</Primary></IndexTerm>
  70 <IndexTerm><Primary>C pre-processor, Haskellised</Primary></IndexTerm>
  71 <IndexTerm><Primary>pre-processor, Haskellised C</Primary></IndexTerm>
  72 <Literal>hscpp</Literal>,<IndexTerm><Primary>hscpp</Primary></IndexTerm> only needed by people requiring conditional
  73 compilation, probably for large systems.  The &ldquo;Haskellised&rdquo; part
  74 just means that <Literal>&num;line</Literal> directives in the output have been
  75 converted into proper Haskell <Literal>&lcub;-&num; LINE ... -&rcub;</Literal> pragmas. You must give an explicit <Literal>-cpp</Literal> option
  76 <IndexTerm><Primary>-cpp option</Primary></IndexTerm> for the C pre-processor to be invoked.
  77 </Para>
  78 </ListItem>
  79
  80 <ListItem>
  81 <Para>
  82 The <Emphasis>Haskell compiler</Emphasis>
  83 <IndexTerm><Primary>Haskell compiler</Primary></IndexTerm>
  84 <IndexTerm><Primary>compiler, Haskell</Primary></IndexTerm>
  85 <Literal>hsc</Literal>,<IndexTerm><Primary>hsc</Primary></IndexTerm>
  86 which&mdash;in normal use&mdash;takes its input from the C pre-processor
  87 and produces assembly-language output (sometimes: ANSI C output).
  88 </Para>
  89 </ListItem>
  90
  91 <ListItem>
  92 <Para>
  93 The <Emphasis>ANSI&nbsp;C Haskell high-level assembler :-)</Emphasis>
  94 <IndexTerm><Primary>ANSI C compiler</Primary></IndexTerm>
  95 <IndexTerm><Primary>high-level assembler</Primary></IndexTerm>
  96 <IndexTerm><Primary>assembler, high-level</Primary></IndexTerm>
  97 compiles <Literal>hsc</Literal>'s C output into assembly language for a particular
  98 target architecture.  In fact, the only C compiler we currently
  99 support is <Literal>gcc</Literal>, because we make use of certain extensions to the
 100 C language only supported by gcc.  Version 2.x is a must; we recommend
 101 version 2.7.2.1 for stability (we've heard both good and bad reports
 102 of later versions).
 103 </Para>
 104 </ListItem>
 105
 106 <ListItem>
 107 <Para>
 108 The <Emphasis>assembler</Emphasis><IndexTerm><Primary>assembler</Primary></IndexTerm>&mdash;a standard UNIX one, probably
 109 <Literal>as</Literal><IndexTerm><Primary>as</Primary></IndexTerm>.
 110 </Para>
 111 </ListItem>
 112
 113 <ListItem>
 114 <Para>
 115 The <Emphasis>linker</Emphasis><IndexTerm><Primary>linker</Primary></IndexTerm>&mdash;a standard UNIX one, probably
 116 <Literal>ld</Literal>.<IndexTerm><Primary>ld</Primary></IndexTerm>
 117 </Para>
 118 </ListItem>
 119
 120 <ListItem>
 121 <Para>
 122 A <Emphasis>runtime system</Emphasis>,<IndexTerm><Primary>runtime system</Primary></IndexTerm> including (most notably)
 123 a storage manager; the linker links in the code for this.
 124 </Para>
 125 </ListItem>
 126
 127 <ListItem>
 128 <Para>
 129 The <Emphasis>Haskell standard prelude</Emphasis><IndexTerm><Primary>standard prelude</Primary></IndexTerm>, a
 130 large library of standard functions, is linked in as well.
 131 </Para>
 132 </ListItem>
 133
 134 <ListItem>
 135 <Para>
 136 Parts of other <Emphasis>installed libraries</Emphasis> that you have at your site may be linked in also.
 137 </Para>
 138 </ListItem>
 139
 140 </OrderedList>
 141 </Para>
 142
 143 </Sect1>
 144
 145 <Sect1 id="compile-what-really-happens">
 146 <Title>What really happens when I &ldquo;compile&rdquo; a Haskell program?
 147 </Title>
 148
 149 <Para>
 150 You invoke the Glasgow Haskell compilation system through the
 151 driver program <Literal>ghc</Literal>.<IndexTerm><Primary>ghc</Primary></IndexTerm> For example, if you had typed a
 152 literate &ldquo;Hello, world!&rdquo; program into <Literal>hello.lhs</Literal>, and you then
 153 invoked:
 154
 155 <Screen>
 156 ghc hello.lhs
 157 </Screen>
 158
 159 </Para>
 160
 161 <Para>
 162 the following would happen:
 163
 164 <OrderedList>
 165 <ListItem>
 166
 167 <Para>
 168 The file <Literal>hello.lhs</Literal> is run through the literate-program
 169 code extractor <Literal>unlit</Literal><IndexTerm><Primary>unlit</Primary></IndexTerm>, feeding its output to
 170
 171 </Para>
 172 </ListItem>
 173 <ListItem>
 174
 175 <Para>
 176 The Haskell compiler proper <Literal>hsc</Literal><IndexTerm><Primary>hsc</Primary></IndexTerm>, which produces
 177 input for
 178
 179 </Para>
 180 </ListItem>
 181 <ListItem>
 182
 183 <Para>
 184 The assembler (or that ubiquitous &ldquo;high-level assembler,&rdquo; a C
 185 compiler), which produces an object file and passes it to
 186
 187 </Para>
 188 </ListItem>
 189 <ListItem>
 190
 191 <Para>
 192 The linker, which links your code with the appropriate libraries
 193 (including the standard prelude), producing an executable program in
 194 the default output file named <Literal>a.out</Literal>.
 195 </Para>
 196 </ListItem>
 197
 198 </OrderedList>
 199
 200 </Para>
 201
 202 <Para>
 203 You have considerable control over the compilation process.  You feed
 204 command-line arguments (call them &ldquo;options,&rdquo; for short) to the
 205 driver, <Literal>ghc</Literal>; the &ldquo;types&rdquo; of the input files (as encoded in
 206 their names' suffixes) also matter.
 207 </Para>
 208
 209 <Para>
 210 Here's hoping this is enough background so that you can read the rest
 211 of this guide!
 212 </Para>
 213
 214 </Sect1>
 215
 216 <Sect1 id="mailing-lists-GHC">
 217 <Title>Meta-information: Web sites, mailing lists, etc.
 218 </Title>
 219
 220 <Para>
 221 <IndexTerm><Primary>mailing lists, Glasgow Haskell</Primary></IndexTerm>
 222 <IndexTerm><Primary>Glasgow Haskell mailing lists</Primary></IndexTerm>
 223 </Para>
 224
 225 <Para>
 226 On the World-Wide Web, there are several URLs of likely interest:
 227 </Para>
 228
 229 <Para>
 230
 231 <ItemizedList>
 232 <ListItem>
 233
 234 <Para>
 235   <ULink
 236 URL="http://www.haskell.org/"
 237 >Haskell home page</ULink
 238 >
 239 </Para>
 240 </ListItem>
 241 <ListItem>
 242
 243 <Para>
 244   <ULink
 245 URL="http://www.haskell.org/ghc/"
 246 >GHC home page</ULink
 247 >
 248 </Para>
 249 </ListItem>
 250 <ListItem>
 251
 252 <Para>
 253   <ULink
 254 URL="http://www.cs.nott.ac.uk/Department/Staff/mpj/faq.html"
 255 >comp.lang.functional FAQ</ULink
 256 >
 257 </Para>
 258 </ListItem>
 259
 260 </ItemizedList>
 261
 262 </Para>
 263
 264 <Para>
 265 We run two mailing lists about Glasgow Haskell.  We encourage you to
 266 join, as you feel is appropriate.
 267 </Para>
 268
 269 <Para>
 270 <VariableList>
 271
 272 <VarListEntry>
 273 <Term>glasgow-haskell-users:</Term>
 274 <ListItem>
 275 <Para>
 276 This list is for GHC users to chat among themselves.  Subscribe by
 277 sending mail to <email>majordomo@haskell.org</email>, with a message
 278 body (not header) like this:
 279 </Para>
 280
 281 <Para>
 282
 283 <Screen>
 284 subscribe glasgow-haskell-users MyName &#60;m.y.self@bigbucks.com&#62;
 285 </Screen>
 286
 287 </Para>
 288
 289 <Para>
 290 (The last bit is your all-important e-mail address, of course.)
 291 </Para>
 292
 293 <Para>
 294 To communicate with your fellow users, send mail to <email>glasgow-haskell-users@haskell.org</email>.
 295 </Para>
 296
 297 <Para>
 298 To contact the list administrator, send mail to
 299 <email>owner-glasgow-haskell-users@haskell.org</email>.  An archive
 300 of the list is available on the Web at the <ULink
 301 URL="http://www.mail-archive.com/glasgow-haskell-users@haskell.org">glasgow-haskell-users
 302 mailing list archive</ULink>.
 303 </Para>
 304 </ListItem>
 305 </VarListEntry>
 306 <VarListEntry>
 307 <Term>glasgow-haskell-bugs:</Term>
 308 <ListItem>
 309 <Para>
 310 Send bug reports for GHC to this address!  The sad and lonely people
 311 who subscribe to this list will muse upon what's wrong and what you
 312 might do about it.
 313 </Para>
 314
 315 <Para>
 316 Subscribe via <email>majordomo@haskell.org</email> with:
 317 </Para>
 318
 319 <Para>
 320
 321 <Screen>
 322 subscribe glasgow-haskell-bugs My Name &#60;m.y.self@hackers.r.us&#62;
 323 </Screen>
 324
 325 </Para>
 326
 327 <Para>
 328 Again, you may contact the list administrator at <email>owner-glasgow-haskell-bugs@haskell.org</email>.
 329 And, yes, an archive of the list is available on the Web at the <ULink
 330 URL="http://www.mail-archive.com/glasgow-haskell-bugs@haskell.org">
 331 glasgow-haskell-bugs mailing list archive</ULink
 332 >
 333 </Para>
 334 </ListItem>
 335 </VarListEntry>
 336 </VariableList>
 337 </Para>
 338
 339 <Para>
 340 There is also the general Haskell mailing list.  Subscribe by sending
 341 email to <email>majordomo@haskell.org</email>, with the usual message body:
 342 </Para>
 343
 344 <Para>
 345
 346 <Screen>
 347 subscribe haskell My Name &#60;m.y.self@fp.rules.ok.org&#62;
 348 </Screen>
 349
 350 </Para>
 351
 352 <Para>
 353 Some Haskell-related discussion takes place in the Usenet newsgroup
 354 <Literal>comp.lang.functional</Literal>.
 355 </Para>
 356
 357 </Sect1>
 358
 359 &relnotes
 360
 361 </Chapter>
 362
 363 <!-- Emacs stuff:
 364      ;;; Local Variables: ***
 365      ;;; mode: sgml ***
 366      ;;; sgml-parent-document: ("users_guide.sgml" "book" "chapter") ***
 367      ;;; End: ***
 368  -->