building.xml 155 KB
Newer Older
1
2
<?xml version="1.0" encoding="iso-8859-1"?>
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
3
   "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
4
  <!ENTITY hacking SYSTEM "../../HACKING">
5
]>
rrt's avatar
rrt committed
6

7
<article id="building-guide">
rrt's avatar
rrt committed
8

9
<articleinfo>
rrt's avatar
rrt committed
10

11
<title>Building and developing GHC</title>
12
13
<author><othername>The GHC Team</othername></author>
<address><email>glasgow-haskell-&lcub;users,bugs&rcub;@haskell.org</email></address>
rrt's avatar
rrt committed
14

15
    <abstract>
16
17
18
19
20
      <para>This Guide is primarily aimed at those who want to build and/or
	hack on GHC.  It describes how to get started with building GHC on your
	machine, and how to tweak the settings to get the kind of build you
	want.  It also describes the inner workings of the build system, so you
	can extend it, modify it, and use it to build your code.</para>
rrt's avatar
rrt committed
21

22
      <para>The bulk of this guide applies to building on Unix
23
      systems; see <xref linkend="winbuild"/> for Windows notes.</para>
24
    </abstract>
rrt's avatar
rrt committed
25

26
</articleinfo>
rrt's avatar
rrt committed
27
28


29
  <sect1 id="sec-getting">
30
31
    <title>Getting the sources</title>
    
32
    <para>You can get your hands on the GHC sources in two ways:</para>
rrt's avatar
rrt committed
33

34
    <variablelist>
35

36
37
38
39
40
41
42
43
44
45
46
      <varlistentry>
	<term><indexterm><primary>Source
	distributions</primary></indexterm>Source distributions</term>
	<listitem>
	  <para>You have a supported platform, but (a)&nbsp;you like
          the warm fuzzy feeling of compiling things yourself;
          (b)&nbsp;you want to build something ``extra&rdquo;&mdash;e.g., a
          set of libraries with strictness-analysis turned off; or
          (c)&nbsp;you want to hack on GHC yourself.</para>

	  <para>A source distribution contains complete sources for
47
          GHC.  Not only that, but the more awkward
48
49
50
51
52
53
54
55
          machine-independent steps are done for you.  For example, if
          you don't have
          <command>happy</command><indexterm><primary>happy</primary></indexterm>
          you'll find it convenient that the source distribution
          contains the result of running <command>happy</command> on
          the parser specifications.  If you don't want to alter the
          parser then this saves you having to find and install
          <command>happy</command>. You will still need a working
56
          version of GHC (version 5.x or later) on your machine in
57
58
59
          order to compile (most of) the sources, however.</para>
	</listitem>
      </varlistentry>
rrt's avatar
rrt committed
60

61
      <varlistentry>
62
	<term>The darcs repository.<indexterm><primary>darcs repository</primary></indexterm></term>
63
64
65
	<listitem>
	  <para>We make releases infrequently.  If you want more
          up-to-the minute (but less tested) source code then you need
66
          to get access to our darcs repository.</para>
67

68
69
70
71
	  <para>Information on accessing the darcs repository is on
	    the wiki: <ulink
	    url="http://hackage.haskell.org/trac/ghc/wiki/GhcDarcs"
	    />.</para>
72
73
74

	  <para>The repository holds source code only. It holds no
          mechanically generated files at all.  So if you check out a
75
          source tree from darcs you will need to install every utility
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
          so that you can build all the derived files from
          scratch.</para>
	</listitem>
      </varlistentry>
    </variablelist>
  </sect1>

  <sect1 id="sec-build-checks">
    <title>Things to check before you start</title>

    <para>Here's a list of things to check before you get
    started.</para>

    <orderedlist>

91
92
      <listitem><para><indexterm><primary>Disk space needed</primary></indexterm>Disk
        space needed: from about 100Mb for a basic GHC
93
94
95
96
97
98
	build, up to probably 500Mb for a GHC build with everything
	included (libraries built several different ways,
	etc.).</para>
      </listitem>

      <listitem>
99
100
101
102
103
104
	<para>Use an appropriate machine / operating system.  <ulink
	url="http://hackage.haskell.org/trac/ghc/wiki/Platforms">GHC
	Platform Support</ulink> lists the currently supported
	platforms; if yours isn't amongst these then you can try
	porting GHC (see <xref linkend="sec-porting-ghc"/>).</para>
	</listitem>
105
106

      <listitem>
107
	<para>Be sure that the &ldquo;pre-supposed&rdquo; utilities are
108
        installed.  <xref linkend="sec-pre-supposed"/>
109
110
111
112
113
        elaborates.</para>
      </listitem>

      <listitem>
	<para>If you have any problem when building or installing the
114
        Glasgow tools, please check the &ldquo;known pitfalls&rdquo; (<xref
115
        linkend="sec-build-pitfalls"/>).  Also check the FAQ for the
116
        version you're building, which is part of the User's Guide and
117
        available on the <ulink url="http://www.haskell.org/ghc/" >GHC web
118
        site</ulink>.</para>
119

120
	<indexterm><primary>bugs</primary><secondary>known</secondary></indexterm>
121
122
123
124

	<para>If you feel there is still some shortcoming in our
        procedure or instructions, please report it.</para>

125
126
127
128
	<para>For GHC, please see the <ulink
	url="http://www.haskell.org/ghc/docs/latest/set/bug-reporting.html">bug-reporting
	section of the GHC Users' Guide</ulink>, to maximise the
	usefulness of your report.</para>
129
130
131

	<indexterm><primary>bugs</primary><secondary>seporting</secondary></indexterm>
	<para>If in doubt, please send a message to
132
133
134
	<email>glasgow-haskell-bugs@haskell.org</email>.
	<indexterm><primary>bugs</primary><secondary>mailing
	list</secondary></indexterm></para>
135
136
137
      </listitem>
    </orderedlist>
  </sect1>
rrt's avatar
rrt committed
138

139
140
  <sect1 id="sec-pre-supposed">
    <title>Installing pre-supposed utilities</title>
rrt's avatar
rrt committed
141

142
143
    <indexterm><primary>pre-supposed utilities</primary></indexterm>
    <indexterm><primary>utilities, pre-supposed</primary></indexterm>
rrt's avatar
rrt committed
144

145
146
147
148
149
150
151
    <para>Here are the gory details about some utility programs you
    may need; <command>perl</command>, <command>gcc</command> and
    <command>happy</command> are the only important
    ones. (PVM<indexterm><primary>PVM</primary></indexterm> is
    important if you're going for Parallel Haskell.)  The
    <command>configure</command><indexterm><primary>configure</primary></indexterm>
    script will tell you if you are missing something.</para>
rrt's avatar
rrt committed
152

153
    <variablelist>
rrt's avatar
rrt committed
154

155
      <varlistentry>
156
157
158
159
	<term>GHC
          <indexterm><primary>pre-supposed: GHC</primary></indexterm>
          <indexterm><primary>GHC, pre-supposed</primary></indexterm>
        </term>
160
	<listitem>
161
162
163
164
165
166
	  <para>GHC is required to build GHC, because GHC itself is
	  written in Haskell, and uses GHC extensions.  It is possible
	  to build GHC using just a C compiler, and indeed some
	  distributions of GHC do just that, but it isn't the best
	  supported method, and you may encounter difficulties.  Full
	  instructions are in <xref linkend="sec-porting-ghc"/>.</para>
167

168
169
170
171
172
173
174
175
176
	  <para>GHC can be built using either an earlier released
	  version of GHC (currently 5.04 and later are supported), or
	  bootstrapped using a GHC built from exactly the same
	  sources.  Note that this means you cannot in general build
	  GHC using an arbitrary development snapshot, or a build from
	  say last week.  It might work, it might not - we don't
	  guarantee anything.  To be on the safe side, start your
	  build using the most recently released stable version of
	  GHC.</para>
177
178
179
	</listitem>
      </varlistentry>

180
      <varlistentry>
181
182
183
184
	<term>Perl
          <indexterm><primary>pre-supposed: Perl</primary></indexterm>
          <indexterm><primary>Perl, pre-supposed</primary></indexterm>
        </term>
185
186
187
188
189
	<listitem>
	  <para><emphasis>You have to have Perl to proceed!</emphasis>
          Perl version 5 at least is required.  GHC has been known to
          tickle bugs in Perl, so if you find that Perl crashes when
          running GHC try updating (or downgrading) your Perl
190
191
192
          installation.  Versions of Perl before 5.6 have been known to have
          various bugs tickled by GHC, so the configure script
          will look for version 5.6 or later.</para>
193
194
195
196
197
198
199
200
201
202
203
204

	  <para>For Win32 platforms, you should use the binary
          supplied in the InstallShield (copy it to
          <filename>/bin</filename>).  The Cygwin-supplied Perl seems
          not to work.</para>

	  <para>Perl should be put somewhere so that it can be invoked
          by the <literal>&num;!</literal> script-invoking
          mechanism. The full pathname may need to be less than 32
          characters long on some systems.</para>
	</listitem>
      </varlistentry>
rrt's avatar
rrt committed
205

206
      <varlistentry>
207
208
209
210
	<term>GNU C (<command>gcc</command>)
          <indexterm><primary>pre-supposed: GCC (GNU C compiler)</primary></indexterm>
          <indexterm><primary>GCC (GNU C compiler), pre-supposed</primary></indexterm>
        </term>
211
	<listitem>
212
213
214
215
216
217
	  <para>Most GCC versions should work with the most recent GHC
	    sources.  Expect trouble if you use a recent GCC with
	    an older GHC, though (trouble in the form of mis-compiled code,
	    link errors, and errors from the <literal>ghc-asm</literal>
	    script).</para>

218
219
	  <para>If your GCC dies with &ldquo;internal error&rdquo; on
          some GHC source file, please let us know, so we can report
220
          it and get things improved.  (Exception: on x86
221
222
223
224
225
          boxes&mdash;you may need to fiddle with GHC's
          <option>-monly-N-regs</option> option; see the User's
          Guide)</para>
	</listitem>
      </varlistentry>
rrt's avatar
rrt committed
226

227
      <varlistentry>
228
229
230
	<term>GNU Make
          <indexterm><primary>make</primary><secondary>GNU</secondary></indexterm>
        </term>
231
	<listitem>
232
	  <para>The GHC build system makes heavy use of features
233
	  specific to GNU <command>make</command>, so you must have
234
	  this installed in order to build GHC.</para>
235
236
237

	  <para>NB. it has been reported that version 3.79 no longer
	  works to build GHC, and 3.80 is required.</para>
238
239
	</listitem>
      </varlistentry>
rrt's avatar
rrt committed
240

241
      <varlistentry>
242
	<term><ulink url="http://www.haskell.org/happy">Happy</ulink>
243
244
          <indexterm><primary>Happy</primary></indexterm>
        </term>
245
246
	<listitem>
	  <para>Happy is a parser generator tool for Haskell, and is
247
248
          used to generate GHC's parsers.</para>

249
	  <para>If you start from a source tarball of GHC (i.e. not a darcs
250
251
	    checkout), then you don't need Happy, because we supply the
	    pre-processed versions of the Happy parsers.  If you intend to
252
	    modify the compiler and/or you're using a darcs checkout, then you
253
254
	    need Happy.</para>

255
256
257
258
	  <para>Happy version 1.15 is currently required to build GHC.
	  Grab a copy from <ulink
	  url="http://www.haskell.org/happy/">Happy's Web
	  Page</ulink>.</para>
259
260
	</listitem>
      </varlistentry>
rrt's avatar
rrt committed
261

262
      <varlistentry>
263
264
265
	<term>Alex
          <indexterm><primary>Alex</primary></indexterm>
        </term>
266
267
	<listitem>
	  <para>Alex is a lexical-analyser generator for Haskell,
268
269
270
271
	  which GHC uses to generate its lexer.</para>

	  <para>Like Happy, you don't need Alex if you're building GHC from a
	    source tarball, but you do need it if you're modifying GHC and/or
272
	    building a darcs checkout.</para>
273
274

	  <para>Alex is
275
	  written in Haskell and is a project in the darcs repository.
276
	  Alex distributions are available from <ulink url="http://www.haskell.org/alex/">Alex's Web
277
278
279
280
	  Page</ulink>.</para>
	</listitem>
      </varlistentry>

281
      <varlistentry>
282
283
284
285
	<term>autoconf
          <indexterm><primary>pre-supposed: autoconf</primary></indexterm>
          <indexterm><primary>autoconf, pre-supposed</primary></indexterm>
        </term>
286
	<listitem>
287
	  <para>GNU autoconf is needed if you intend to build from the
288
          darcs sources, it is <emphasis>not</emphasis> needed if you
289
290
          just intend to build a standard source distribution.</para>

291
292
	  <para>Version 2.52 or later of the autoconf package is required.
	  NB. version 2.13 will no longer work, as of GHC version
293
294
	  6.1.</para>

295
296
297
298
299
300
	  <para><command>autoreconf</command> (from the autoconf package)
          recursively builds <command>configure</command> scripts from
          the corresponding <filename>configure.ac</filename> and
          <filename>aclocal.m4</filename> files.  If you modify one of
          the latter files, you'll need <command>autoreconf</command> to
          rebuild the corresponding <filename>configure</filename>.</para>
301
302
	</listitem>
      </varlistentry>
rrt's avatar
rrt committed
303

304
      <varlistentry>
305
306
307
308
	<term><command>sed</command>
          <indexterm><primary>pre-supposed: sed</primary></indexterm>
          <indexterm><primary>sed, pre-supposed</primary></indexterm>
        </term>
309
310
311
312
313
314
315
316
317
318
	<listitem>
	  <para>You need a working <command>sed</command> if you are
          going to build from sources.  The build-configuration stuff
          needs it.  GNU sed version 2.0.4 is no good!  It has a bug
          in it that is tickled by the build-configuration.  2.0.5 is
          OK. Others are probably OK too (assuming we don't create too
          elaborate configure scripts.)</para>
	</listitem>
      </varlistentry>
    </variablelist>
rrt's avatar
rrt committed
319

320
321
    <sect2 id="pre-supposed-gph-tools">
      <title>Tools for building parallel GHC (GPH)</title>
rrt's avatar
rrt committed
322

323
324
      <variablelist>
	<varlistentry>
325
	  <term>PVM version 3:
326
	  <indexterm><primary>pre-supposed: PVM3 (Parallel Virtual Machine)</primary></indexterm>
327
328
            <indexterm><primary>PVM3 (Parallel Virtual Machine), pre-supposed</primary></indexterm>
          </term>
329
330
331
	  <listitem>
	    <para>PVM is the Parallel Virtual Machine on which
            Parallel Haskell programs run.  (You only need this if you
332
            plan to run Parallel Haskell.  Concurrent Haskell, which
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
            runs concurrent threads on a uniprocessor doesn't need
            it.)  Underneath PVM, you can have (for example) a network
            of workstations (slow) or a multiprocessor box
            (faster).</para>

	    <para>The current version of PVM is 3.3.11; we use 3.3.7.
            It is readily available on the net; I think I got it from
            <literal>research.att.com</literal>, in
            <filename>netlib</filename>.</para>

	    <para>A PVM installation is slightly quirky, but easy to
            do.  Just follow the <filename>Readme</filename>
            instructions.</para>
	  </listitem>
	</varlistentry>
rrt's avatar
rrt committed
348

349
	<varlistentry>
350
351
352
	  <term><command>bash</command>:
            <indexterm><primary>bash, presupposed (Parallel Haskell only)</primary></indexterm>
          </term>
353
354
355
356
357
358
359
360
	  <listitem>
	    <para>Sadly, the <command>gr2ps</command> script, used to
            convert &ldquo;parallelism profiles&rdquo; to PostScript,
            is written in Bash (GNU's Bourne Again shell).  This bug
            will be fixed (someday).</para>
	  </listitem>
	</varlistentry>
      </variablelist>
rrt's avatar
rrt committed
361

362
363
      <para>More tools are required if you want to format the
      documentation that comes with GHC.  See <xref
364
      linkend="building-docs"/>.</para>
365
366
    </sect2>
  </sect1>
rrt's avatar
rrt committed
367

368
369
  <sect1 id="sec-building-from-source">
    <title>Building from source</title>
rrt's avatar
rrt committed
370

371
372
    <indexterm><primary>Building from source</primary></indexterm>
    <indexterm><primary>Source, building from</primary></indexterm>
rrt's avatar
rrt committed
373

374
    <para>&ldquo;I just want to build it!&rdquo;</para>
rrt's avatar
rrt committed
375

376
377
378
    <para>No problem.  This recipe should build and install a working GHC with
      all the default settings.  (unless you're
      on Windows, in which case go to <xref linkend="winbuild" />).</para>
rrt's avatar
rrt committed
379

380
381
<screen>$ autoreconf<footnote><para>not necessary if you started from a source tarball</para>
      </footnote>
382
$ ./configure
383
$ make
384
$ make install</screen>
385
386
387

      <para>For GHC, this will do a 2-stage bootstrap build of the
      compiler, with profiling libraries, and install the
388
389
390
391
392
393
394
      results in the default location (under <filename>/usr/local</filename> on
      Unix, for example).</para>

    <para>The <literal>configure</literal> script is a standard GNU
      <literal>autoconf</literal> script, and accepts the usual options for
      changing install locations and the like.  Run
      <literal>./configure&nbsp;--help</literal> for a list of options.</para>
395
396
397

      <para>If you want to do anything at all non-standard, or you
      want to do some development, read on...</para>
398
399
400
401
402
403
    </sect1>
    
    <sect1 id="quick-start">
      <title>Quick start for GHC developers</title>
      
      <para>This section is a copy of the file
404
	<literal>HACKING</literal> from the GHC source tree.  It describes
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
	how to get started with setting up your build tree for developing GHC
	or its libraries, and how to start building.</para>

<screen>     
&hacking;
      </screen>
    </sect1>

  <sect1 id="sec-working-with-the-build-system">
    <title>Working with the build system</title>
    
    <para>This rest of this guide is intended for duffers like me, who
    aren't really interested in Makefiles and systems configurations,
    but who need a mental model of the interlocking pieces so that
    they can make them work, extend them consistently when adding new
    software, and lay hands on them gently when they don't
    work.</para>
422

423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
    <sect2>
      <title>History</title>

      <para>First, a historical note.  The GHC build system used to be
      called "fptools": a generic build system used to build multiple
      projects (GHC, Happy, GreenCard, H/Direct, etc.).  It had a
      concept of the generic project-independent parts, and
      project-specific parts that resided in a project
      subdirectory.</para>

      <para>Nowadays, most of these other projects are using <ulink
      url="http://www.haskell.org/cabal/">Cabal</ulink>, or have faded
      away, and GHC is the only regular user of the fptools build
      system.  We decided therefore to simplify the situation for
      developers, and specialise the build system for GHC.  This
      resulted in a simpler organisation of the source tree and the
      build system, which hopefully makes the whole thing easier to
      understand.</para>

      <para>You might find old comments that refer to "projects" or
      "fptools" in the documentation and/or source; please let us know
      if you do.</para>
445
    </sect2>
rrt's avatar
rrt committed
446

447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
    <sect2>
      <title>Build trees</title>
      <indexterm><primary>build trees</primary></indexterm>
      <indexterm><primary>link trees, for building</primary></indexterm>

      <para>If you just want to build the software once on a single
      platform, then your source tree can also be your build tree, and
      you can skip the rest of this section.</para>

      <para>We often want to build multiple versions of our software
      for different architectures, or with different options
      (e.g. profiling).  It's very desirable to share a single copy of
      the source code among all these builds.</para>

      <para>So for every source tree we have zero or more
      <emphasis>build trees</emphasis>.  Each build tree is initially
      an exact copy of the source tree, except that each file is a
      symbolic link to the source file, rather than being a copy of
      the source file.  There are &ldquo;standard&rdquo; Unix
      utilities that make such copies, so standard that they go by
      different names:
      <command>lndir</command><indexterm><primary>lndir</primary></indexterm>,
      <command>mkshadowdir</command><indexterm><primary>mkshadowdir</primary></indexterm>
      are two (If you don't have either, the source distribution
      includes sources for the X11
      <command>lndir</command>&mdash;check out
473
      <filename>utils/lndir</filename>). See <xref
474
      linkend="sec-storysofar"/> for a typical invocation.</para>
475
476
477
478
479
480
481

      <para>The build tree does not need to be anywhere near the
      source tree in the file system.  Indeed, one advantage of
      separating the build tree from the source is that the build tree
      can be placed in a non-backed-up partition, saving your systems
      support people from backing up untold megabytes of
      easily-regenerated, and rapidly-changing, gubbins.  The golden
482
      rule is that (with a single exception&mdash;<xref
483
      linkend="sec-build-config"/>) <emphasis>absolutely everything in
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
      the build tree is either a symbolic link to the source tree, or
      else is mechanically generated</emphasis>.  It should be
      perfectly OK for your build tree to vanish overnight; an hour or
      two compiling and you're on the road again.</para>

      <para>You need to be a bit careful, though, that any new files
      you create (if you do any development work) are in the source
      tree, not a build tree!</para>

      <para>Remember, that the source files in the build tree are
      <emphasis>symbolic links</emphasis> to the files in the source
      tree.  (The build tree soon accumulates lots of built files like
      <filename>Foo.o</filename>, as well.)  You can
      <emphasis>delete</emphasis> a source file from the build tree
      without affecting the source tree (though it's an odd thing to
      do).  On the other hand, if you <emphasis>edit</emphasis> a
      source file from the build tree, you'll edit the source-tree
      file directly.  (You can set up Emacs so that if you edit a
      source file from the build tree, Emacs will silently create an
      edited copy of the source file in the build tree, leaving the
      source file unchanged; but the danger is that you think you've
      edited the source file whereas actually all you've done is edit
      the build-tree copy.  More commonly you do want to edit the
      source file.)</para>

      <para>Like the source tree, the top level of your build tree
510
511
      must be (a linked copy of) the root directory of the GHC source
      tree..  Inside Makefiles, the root of your build tree is called
512
      <constant>&dollar;(GHC&lowbar;TOP)</constant><indexterm><primary>GHC&lowbar;TOP</primary></indexterm>.
513
      In the rest of this document path names are relative to
514
      <constant>&dollar;(GHC&lowbar;TOP)</constant> unless
515
      otherwise stated.  For example, the file
516
      <filename>mk/target.mk</filename> is actually
517
      <filename>&dollar;(GHC&lowbar;TOP)/mk/target.mk</filename>.</para>
518
    </sect2>
rrt's avatar
rrt committed
519

520
521
522
    <sect2 id="sec-build-config">
      <title>Getting the build you want</title>

523
524
525
526
      <para>When you build GHC you will be compiling code on a
      particular <emphasis>host platform</emphasis>, to run on a
      particular <emphasis>target platform</emphasis> (usually the
      same as the host
527
528
529
530
531
532
533
534
      platform)<indexterm><primary>platform</primary></indexterm>.
      The difficulty is that there are minor differences between
      different platforms; minor, but enough that the code needs to be
      a bit different for each.  There are some big differences too:
      for a different architecture we need to build GHC with a
      different native-code generator.</para>

      <para>There are also knobs you can turn to control how the
535
536
537
538
539
      software is built.  For example, you might want to build GHC
      optimised (so that it runs fast) or unoptimised (so that you can
      compile it fast after you've modified it.  Or, you might want to
      compile it with debugging on (so that extra consistency-checking
      code gets included) or off.  And so on.</para>
540
541
542
543

      <para>All of this stuff is called the
      <emphasis>configuration</emphasis> of your build.  You set the
      configuration using a three-step process.</para>
rrt's avatar
rrt committed
544

545
546
547
548
      <variablelist>
	<varlistentry>
	  <term>Step 1: get ready for configuration.</term>
	  <listitem>
549
	    <para>NOTE: if you're starting from a source distribution,
550
	    rather than darcs sources, you can skip this step.</para>
551

552
	    <para>Change directory to
553
            <constant>&dollar;(GHC&lowbar;TOP)</constant> and
554
            issue the command</para>
555
<screen>$ autoreconf</screen>
556
            <indexterm><primary>autoreconf</primary></indexterm>
557
            <para>(with no arguments). This GNU program (recursively) converts
558
559
            <filename>&dollar;(GHC&lowbar;TOP)/configure.ac</filename> and
            <filename>&dollar;(GHC&lowbar;TOP)/aclocal.m4</filename>
560
            to a shell script called
561
            <filename>&dollar;(GHC&lowbar;TOP)/configure</filename>.
562
563
564
565
	      If <command>autoreconf</command> bleats that it can't write the file <filename>configure</filename>,
	      then delete the latter and try again.  Note that you must use <command>autoreconf</command>,
	      and not the old <command>autoconf</command>!  If you erroneously use the latter, you'll get 
	      a message like "No rule to make target 'mk/config.h.in'".
566
567
            </para>

568
569
	    <para>Some parts of the source tree, particularly
            libraries, have their own configure script.
570
571
            <command>autoreconf</command> takes care of that, too, so all you have
             to do is calling <command>autoreconf</command> in the top-level directory
572
            <filename>&dollar;(GHC&lowbar;TOP)</filename>.</para>
573
574
575
576
577
578

	    <para>These steps are completely platform-independent; they just mean
            that the human-written files (<filename>configure.ac</filename> and
            <filename>aclocal.m4</filename>) can be short, although the resulting
            files (the <command>configure</command> shell scripts and the C header
            template <filename>mk/config.h.in</filename>) are long.</para>
579
580
	  </listitem>
	</varlistentry>
rrt's avatar
rrt committed
581

582
583
584
585
586
	<varlistentry>
	  <term>Step 2: system configuration.</term>
	  <listitem>
	    <para>Runs the newly-created <command>configure</command>
	    script, thus:</para>
rrt's avatar
rrt committed
587

588
<screen>$ ./configure <optional><parameter>args</parameter></optional></screen>
rrt's avatar
rrt committed
589

590
591
592
	    <para><command>configure</command>'s mission is to scurry
            round your computer working out what architecture it has,
            what operating system, whether it has the
593
            <function>vfork</function> system call, where
594
            <command>tar</command> is kept, whether
595
596
597
598
599
            <command>gcc</command> is available, where various obscure
            <literal>&num;include</literal> files are, whether it's a
            leap year, and what the systems manager had for lunch.  It
            communicates these snippets of information in two
            ways:</para>
rrt's avatar
rrt committed
600

601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
	    <itemizedlist>
	      <listitem>
		
		<para>It translates
                <filename>mk/config.mk.in</filename><indexterm><primary>config.mk.in</primary></indexterm>
                to
                <filename>mk/config.mk</filename><indexterm><primary>config.mk</primary></indexterm>,
                substituting for things between
                &ldquo;<literal>@</literal>&rdquo; brackets.  So,
                &ldquo;<literal>@HaveGcc@</literal>&rdquo; will be
                replaced by &ldquo;<literal>YES</literal>&rdquo; or
                &ldquo;<literal>NO</literal>&rdquo; depending on what
                <command>configure</command> finds.
                <filename>mk/config.mk</filename> is included by every
                Makefile (directly or indirectly), so the
                configuration information is thereby communicated to
                all Makefiles.</para>
		</listitem>
rrt's avatar
rrt committed
619

620
621
622
623
624
625
626
627
628
629
	      <listitem>
		<para> It translates
                <filename>mk/config.h.in</filename><indexterm><primary>config.h.in</primary></indexterm>
                to
                <filename>mk/config.h</filename><indexterm><primary>config.h</primary></indexterm>.
                The latter is <literal>&num;include</literal>d by
                various C programs, which can thereby make use of
                configuration information.</para>
	      </listitem>
	    </itemizedlist>
rrt's avatar
rrt committed
630

631
632
633
634
	    <para><command>configure</command> takes some optional
	    arguments.  Use <literal>./configure --help</literal> to
	    get a list of the available arguments.  Here are some of
	    the ones you might need:</para>
rrt's avatar
rrt committed
635

636
637
	    <variablelist>
	      <varlistentry>
638
639
640
		<term><literal>--with-ghc=<parameter>path</parameter></literal>
                  <indexterm><primary><literal>--with-ghc</literal></primary></indexterm>
                </term>
641
		<listitem>
642
643
644
645
646
647
648
649
650
		  <para>Specifies the path to an installed GHC which
		  you would like to use.  This compiler will be used
		  for compiling GHC-specific code (eg. GHC itself).
		  This option <emphasis>cannot</emphasis> be specified
		  using <filename>build.mk</filename> (see later),
		  because <command>configure</command> needs to
		  auto-detect the version of GHC you're using.  The
		  default is to look for a compiler named
		  <literal>ghc</literal> in your path.</para>
651
		</listitem>
652
653
654
	      </varlistentry>
	      
	      <varlistentry>
655
656
657
		<term><literal>--with-hc=<parameter>path</parameter></literal>
                  <indexterm><primary><literal>--with-hc</literal></primary></indexterm>
                </term>
658
		<listitem>
659
660
661
		  <para>Specifies the path to any installed Haskell
		  compiler.  This compiler will be used for compiling
		  generic Haskell code.  The default is to use
662
663
664
665
		  <literal>ghc</literal>. (NOTE: I'm not sure it
		  actually works to specify a compiler other than GHC
		  here; unless you really know what you're doing I
		  suggest not using this option at all.)</para>
666
		</listitem>
667
668
669
	      </varlistentry>
	      
	      <varlistentry>
670
671
672
		<term><literal>--with-gcc=<parameter>path</parameter></literal>
                  <indexterm><primary><literal>--with-gcc</literal></primary></indexterm>
                </term>
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
		<listitem>
		  <para>Specifies the path to the installed GCC. This
		  compiler will be used to compile all C files,
		  <emphasis>except</emphasis> any generated by the
		  installed Haskell compiler, which will have its own
		  idea of which C compiler (if any) to use.  The
		  default is to use <literal>gcc</literal>.</para>
		</listitem>
	      </varlistentry>
	    </variablelist>
	  </listitem>
	</varlistentry>
	
	<varlistentry>
	  <term>Step 3: build configuration.</term>
	  <listitem>
	    <para>Next, you say how this build of
690
            GHC is to differ from the standard
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
            defaults by creating a new file
            <filename>mk/build.mk</filename><indexterm><primary>build.mk</primary></indexterm>
            <emphasis>in the build tree</emphasis>.  This file is the
            one and only file you edit in the build tree, precisely
            because it says how this build differs from the source.
            (Just in case your build tree does die, you might want to
            keep a private directory of <filename>build.mk</filename>
            files, and use a symbolic link in each build tree to point
            to the appropriate one.)  So
            <filename>mk/build.mk</filename> never exists in the
            source tree&mdash;you create one in each build tree from
            the template.  We'll discuss what to put in it
            shortly.</para>
	  </listitem>
	</varlistentry>
      </variablelist>
rrt's avatar
rrt committed
707

708
      <para>And that's it for configuration. Simple, eh?</para>
709
710

      <para>What do you put in your build-specific configuration file
711
      <filename>mk/build.mk</filename>?  <emphasis>For almost all
712
      purposes all you will do is put make variable definitions that
713
      override those in</emphasis>
714
715
716
717
718
719
720
721
722
      <filename>mk/config.mk.in</filename>.  The whole point of
      <filename>mk/config.mk.in</filename>&mdash;and its derived
      counterpart <filename>mk/config.mk</filename>&mdash;is to define
      the build configuration. It is heavily commented, as you will
      see if you look at it.  So generally, what you do is look at
      <filename>mk/config.mk.in</filename>, and add definitions in
      <filename>mk/build.mk</filename> that override any of the
      <filename>config.mk</filename> definitions that you want to
      change.  (The override occurs because the main boilerplate file,
723
      <filename>mk/boilerplate.mk</filename><indexterm><primary>boilerplate.mk</primary></indexterm>,
724
725
726
      includes <filename>build.mk</filename> after
      <filename>config.mk</filename>.)</para>

727
728
729
     <para>For your convenience, there's a file called
     <filename>build.mk.sample</filename> that can serve as a starting
     point for your <filename>build.mk</filename>.</para>
730

731
732
      <para>For example, <filename>config.mk.in</filename> contains
      the definition:</para>
rrt's avatar
rrt committed
733

734
<programlisting>GhcHcOpts=-Rghc-timing</programlisting>
rrt's avatar
rrt committed
735

736
737
738
739
740
      <para>The accompanying comment explains that this is the list of
      flags passed to GHC when building GHC itself.  For doing
      development, it is wise to add <literal>-DDEBUG</literal>, to
      enable debugging code.  So you would add the following to
      <filename>build.mk</filename>:</para>
741
      
742
<programlisting>GhcHcOpts += -DDEBUG</programlisting>
rrt's avatar
rrt committed
743

744
745
      <para>GNU <command>make</command> allows existing definitions to
      have new text appended using the &ldquo;<literal>+=</literal>&rdquo;
746
747
748
749
750
      operator, which is quite a convenient feature.</para>

      <para>Haskell compilations by default have <literal>-O</literal>
      turned on, by virtue of this setting from
      <filename>config.mk</filename>:</para>
rrt's avatar
rrt committed
751

752
753
754
755
756
757
758
<programlisting>SRC_HC_OPTS += -H16m -O</programlisting>

      <para><literal>SRC_HC_OPTS</literal> means "options for HC from
      the source tree", where HC stands for Haskell Compiler.
      <literal>SRC_HC_OPTS</literal> are added to every Haskell
      compilation.  To turn off optimisation, you could add this to
      <filename>build.mk</filename>:</para>
rrt's avatar
rrt committed
759

760
761
762
763
764
765
<programlisting>SRC_HC_OPTS = -H16m -O0</programlisting>

      <para>Or you could just add <literal>-O0</literal> to
      <literal>GhcHcOpts</literal> to turn off optimisation for the
      compiler.  See <xref linkend="quick-start" /> for some more
      suggestions.</para>
rrt's avatar
rrt committed
766

767
      <para>When reading <filename>config.mk.in</filename>, remember
768
769
770
      that anything between &ldquo;@...@&rdquo; signs is going to be substituted
      by <command>configure</command> later.  You
      <emphasis>can</emphasis> override the resulting definition if
771
772
      you want, but you need to be a bit surer what you are doing.
      For example, there's a line that says:</para>
rrt's avatar
rrt committed
773

774
<programlisting>TAR = @TarCmd@</programlisting>
rrt's avatar
rrt committed
775

776
777
      <para>This defines the Make variables <constant>TAR</constant>
      to the pathname for a <command>tar</command> that
778
      <command>configure</command> finds somewhere.  If you have your
779
      own pet <command>tar</command> you want to use instead, that's
780
      fine. Just add this line to <filename>mk/build.mk</filename>:</para>
rrt's avatar
rrt committed
781

782
<programlisting>TAR = mytar</programlisting>
rrt's avatar
rrt committed
783

784
      <para>You do not <emphasis>have</emphasis> to have a
785
786
787
788
789
      <filename>mk/build.mk</filename> file at all; if you don't,
      you'll get all the default settings from
      <filename>mk/config.mk.in</filename>.</para>

      <para>You can also use <filename>build.mk</filename> to override
790
      anything that <command>configure</command> got wrong.  One place
791
      where this happens often is with the definition of
792
      <constant>GHC&lowbar;TOP&lowbar;ABS</constant>: this
793
794
795
      variable is supposed to be the canonical path to the top of your
      source tree, but if your system uses an automounter then the
      correct directory is hard to find automatically.  If you find
796
      that <command>configure</command> has got it wrong, just put the
797
      correct definition in <filename>build.mk</filename>.</para>
798
    </sect2>
rrt's avatar
rrt committed
799

800
801
802
803
804
805
806
807
    <sect2 id="sec-storysofar">
      <title>The story so far</title>

      <para>Let's summarise the steps you need to carry to get
      yourself a fully-configured build tree from scratch.</para>

      <orderedlist>
	<listitem>
808
	  <para> Get your source tree from somewhere (darcs repository
809
          or source distribution).  Say you call the root directory
810
811
          <filename>myghc</filename> (it does not have to be
          called <filename>ghc</filename>).</para>
812
813
814
	</listitem>

	<listitem>
815
816
	  <para>(Optional) Use <command>lndir</command> or
	  <command>mkshadowdir</command> to create a build tree.</para>
817

818
819
<screen>$ cd myghc
$ mkshadowdir . /scratch/joe-bloggs/myghc-x86</screen>
820

821
	  <para>(N.B. <command>mkshadowdir</command>'s first argument
822
823
824
825
826
827
828
829
830
831
          is taken relative to its second.) You probably want to give
          the build tree a name that suggests its main defining
          characteristic (in your mind at least), in case you later
          add others.</para>
	</listitem>

	<listitem>
	  <para>Change directory to the build tree.  Everything is
          going to happen there now.</para>

832
<screen>$ cd /scratch/joe-bloggs/myghc-x86</screen>
833
834
835
836
837
838

	</listitem>

	<listitem>
	  <para>Prepare for system configuration:</para>

839
<screen>$ autoreconf</screen>
840
841
842
843
844
845
846
847
848
849

	  <para>(You can skip this step if you are starting from a
          source distribution, and you already have
          <filename>configure</filename> and
          <filename>mk/config.h.in</filename>.)</para>
	</listitem>

	<listitem>
	  <para>Do system configuration:</para>

850
<screen>$ ./configure</screen>
851
852
853
854
855

	  <para>Don't forget to check whether you need to add any
	  arguments to <literal>configure</literal>; for example, a
	  common requirement is to specify which GHC to use with
	  <option>--with-ghc=<replaceable>ghc</replaceable></option>.</para>
856
857
858
859
	</listitem>

	<listitem>
	  <para>Create the file <filename>mk/build.mk</filename>,
860
861
          adding definitions for your desired configuration
          options.</para>
862
863
864
865
866
867
868
	</listitem>
      </orderedlist>

      <para>You can make subsequent changes to
      <filename>mk/build.mk</filename> as often as you like.  You do
      not have to run any further configuration programs to make these
      changes take effect. In theory you should, however, say
869
870
871
      <command>make clean; make</command>, because configuration
      option changes could affect anything&mdash;but in practice you
      are likely to know what's affected.</para>
872
873
874
    </sect2>

    <sect2>
875
      <title>Making things</title>
rrt's avatar
rrt committed
876

877
878
879
      <para>At this point you have made yourself a fully-configured
      build tree, so you are ready to start building real
      things.</para>
rrt's avatar
rrt committed
880

881
      <para>The first thing you need to know is that <emphasis>you
882
      must use GNU <command>make</command></emphasis>.  On some
883
884
885
      systems (eg. FreeBSD) this is called <command>gmake</command>,
      whereas on others it is the standard <command>make</command>
      command.  In this document we will always refer to it as
886
887
888
889
      <command>make</command>; please substitute with
      <command>gmake</command> if your system requires it.  If you use
      a the wrong <command>make</command> you will get all sorts of
      error messages (but no damage) because the GHC
890
      <command>Makefiles</command> use GNU <command>make</command>'s
891
      facilities extensively.</para>
rrt's avatar
rrt committed
892

893
      <para>To just build the whole thing, <command>cd</command> to
894
895
896
897
898
      the top of your build tree and type <command>make</command>.
      This will prepare the tree and build the various parts in the
      correct order, resulting in a complete build of GHC that can
      even be used directly from the tree, without being installed
      first.</para>
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
    </sect2>

    <sect2 id="sec-bootstrapping">
      <title>Bootstrapping GHC</title>

      <para>GHC requires a 2-stage bootstrap in order to provide 
      full functionality, including GHCi.  By a 2-stage bootstrap, we
      mean that the compiler is built once using the installed GHC,
      and then again using the compiler built in the first stage.  You
      can also build a stage 3 compiler, but this normally isn't
      necessary except to verify that the stage 2 compiler is working
      properly.</para>

      <para>Note that when doing a bootstrap, the stage 1 compiler
      must be built, followed by the runtime system and libraries, and
      then the stage 2 compiler.  The correct ordering is implemented
915
916
917
918
919
920
      by the top-level <filename>Makefile</filename>, so if you want
      everything to work automatically it's best to start
      <command>make</command> from the top of the tree.  The top-level
      <filename>Makefile</filename> is set up to do a 2-stage
      bootstrap by default (when you say <command>make</command>).
      Some other targets it supports are:</para>
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967

      <variablelist>
	<varlistentry>
	  <term>stage1</term>
	  <listitem>
	    <para>Build everything as normal, including the stage 1
	    compiler.</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term>stage2</term>
	  <listitem>
	    <para>Build the stage 2 compiler only.</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term>stage3</term>
	  <listitem>
	    <para>Build the stage 3 compiler only.</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term>bootstrap</term> <term>bootstrap2</term>
	  <listitem>
	    <para>Build stage 1 followed by stage 2.</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term>bootstrap3</term>
	  <listitem>
	    <para>Build stages 1, 2 and 3.</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term>install</term>
	  <listitem>
	    <para>Install everything, including the compiler built in
	    stage 2.  To override the stage, say <literal>make install
	    stage=<replaceable>n</replaceable></literal> where
	    <replaceable>n</replaceable> is the stage to install.</para>
	  </listitem>
	</varlistentry>
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984

	<varlistentry>
	  <term><literal>binary-dist</literal></term>
	  <listitem>
	    <para>make a binary distribution.  This is the target we
            use to build the binary distributions of GHC.</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term><literal>dist</literal></term>
	  <listitem>
	    <para>make a source distribution.  Note that this target
            does &ldquo;make distclean&rdquo; as part of its work;
            don't use it if you want to keep what you've built.</para>
	  </listitem>
	</varlistentry>
985
986
987
988
989
990
991
992
      </variablelist>

      <para>The top-level <filename>Makefile</filename> also arranges
      to do the appropriate <literal>make boot</literal> steps (see
      below) before actually building anything.</para>

      <para>The <literal>stage1</literal>, <literal>stage2</literal>
      and <literal>stage3</literal> targets also work in the
993
      <literal>compiler</literal> directory, but don't forget that
994
995
996
997
      each stage requires its own <literal>make boot</literal> step:
      for example, you must do</para>

      <screen>$ make boot stage=2</screen>
998

999
      <para>before <literal>make stage2</literal> in
1000
      <literal>compiler</literal>.</para>
For faster browsing, not all history is shown. View entire blame