building.xml 170 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
	<para>Use an appropriate machine / operating system.  <xref
100
	linkend="sec-port-info"/> lists the supported platforms; if
101
	yours isn't amongst these then you can try porting GHC (see
102
	<xref linkend="sec-porting-ghc"/>).</para>
103
104
105
      </listitem>

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

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

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

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

124
125
126
127
	<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>
128
129
130

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

138
  <sect1 id="sec-port-info">
139
    <title>What machines GHC runs on</title>
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162

<indexterm><primary>ports</primary><secondary>GHC</secondary></indexterm>
<indexterm><primary>GHC</primary><secondary>ports</secondary></indexterm>
<indexterm><primary>platforms</primary><secondary>supported</secondary></indexterm>

    <para>A &ldquo;platform&rdquo; is a
    architecture/manufacturer/operating-system combination, such as
    <literal>sparc-sun-solaris2</literal>.  Other common ones are
    <literal>alpha-dec-osf2</literal>,
    <literal>hppa1.1-hp-hpux9</literal>,
    <literal>i386-unknown-linux</literal>,
    <literal>i386-unknown-solaris2</literal>,
    <literal>i386-unknown-freebsd</literal>,
    <literal>i386-unknown-cygwin32</literal>,
    <literal>m68k-sun-sunos4</literal>,
    <literal>mips-sgi-irix5</literal>,
    <literal>sparc-sun-sunos4</literal>,
    <literal>sparc-sun-solaris2</literal>,
    <literal>powerpc-ibm-aix</literal>.</para>

    <para>Some libraries may only work on a limited number of
    platforms; for example, a sockets library is of no use unless the
    operating system supports the underlying BSDisms.</para>
rrt's avatar
rrt committed
163

Simon Marlow's avatar
Simon Marlow committed
164
165
166
167
    <indexterm><primary>fully-supported platforms</primary></indexterm>
    <indexterm><primary>native-code generator</primary></indexterm>
    <indexterm><primary>registerised ports</primary></indexterm>
    <indexterm><primary>unregisterised ports</primary></indexterm>
rrt's avatar
rrt committed
168

169
170
171
172
173
174
      <para>The GHC hierarchy of Porting Goodness: (a)&nbsp;Best is a
      native-code generator; (b)&nbsp;next best is a
      &ldquo;registerised&rdquo; port; (c)&nbsp;the bare minimum is an
      &ldquo;unregisterised&rdquo; port.
      (&ldquo;Unregisterised&rdquo; is so terrible that we won't say
      more about it).</para>
rrt's avatar
rrt committed
175

176
177
178
      <para>Here's everything that's known about GHC ports.  We
      identify platforms by their &ldquo;canonical&rdquo;
      CPU/Manufacturer/OS triple.</para>
rrt's avatar
rrt committed
179

180
181
      <variablelist>
	<varlistentry>
182
	  <term>alpha-dec-{osf,linux,freebsd,openbsd,netbsd}:
183
184
185
186
187
	  <indexterm><primary>alpha-dec-osf</primary></indexterm>
	  <indexterm><primary>alpha-dec-linux</primary></indexterm>
	  <indexterm><primary>alpha-dec-freebsd</primary></indexterm>
	  <indexterm><primary>alpha-dec-openbsd</primary></indexterm>
	  <indexterm><primary>alpha-dec-netbsd</primary></indexterm>
188
          </term>
189
190
191
192
193
194
195
196
197
	  <listitem>
	    <para>The OSF port is currently working (as of GHC version
	    5.02.1) and well supported.  The native code generator is
	    currently non-working.  Other operating systems will
	    require some minor porting.</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
198
199
200
	  <term>sparc-sun-sunos4
	    <indexterm><primary>sparc-sun-sunos4</primary></indexterm>
          </term>
201
202
203
204
205
206
207
	  <listitem>
	    <para>Probably works with minor tweaks, hasn't been tested
	    for a while.</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
208
209
210
	  <term>sparc-sun-solaris2
            <indexterm><primary>sparc-sun-solaris2</primary></indexterm>
          </term>
211
	  <listitem>
dons's avatar
dons committed
212
	    <para>Fully supported (at least for Solaris 2.7 and 2.6),
213
	    including native-code generator.</para>
214
215
216
	  </listitem>
	</varlistentry>

dons's avatar
dons committed
217
	<varlistentry>
218
219
220
	  <term>sparc-unknown-openbsd
            <indexterm><primary>sparc-unknown-openbsd</primary></indexterm>
          </term>
dons's avatar
dons committed
221
222
223
224
225
226
	  <listitem>
	    <para>Supported, including native-code generator. The
	    same should also be true of NetBSD</para>
	  </listitem>
	</varlistentry>

227
	<varlistentry>
228
229
230
	  <term>hppa1.1-hp-hpux (HP-PA boxes running HPUX 9.x)
            <indexterm><primary>hppa1.1-hp-hpux</primary></indexterm>
          </term>
231
	  <listitem>
232
233
234
	    <para>A registerised port is available for version 4.08,
	    but GHC hasn't been built on that platform since (as far
	    as we know).  No native-code generator.</para>
235
236
237
238
	  </listitem>
	</varlistentry>

	<varlistentry>
239
240
241
	  <term>i386-unknown-linux (PCs running Linux, ELF binary format)
            <indexterm><primary>i386-*-linux</primary></indexterm>
          </term>
242
243
	  <listitem>
	    <para>GHC works registerised and has a native code
244
            generator.  You <emphasis>must</emphasis> have GCC 2.7.x
245
246
247
248
249
250
251
252
253
254
255
            or later.  NOTE about <literal>glibc</literal> versions:
            GHC binaries built on a system running <literal>glibc
            2.0</literal> won't work on a system running
            <literal>glibc 2.1</literal>, and vice versa.  In general,
            don't expect compatibility between
            <literal>glibc</literal> versions, even if the shared
            library version hasn't changed.</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
256
257
258
	  <term>i386-unknown-freebsd (PCs running FreeBSD 2.2 or higher)
            <indexterm><primary>i386-unknown-freebsd</primary></indexterm>
          </term>
259
260
261
262
	  <listitem>
	    <para>GHC works registerised.  Pre-built packages are
            available in the native package format, so if you just
            need binaries you're better off just installing the
263
264
            package (it might even be on your installation
            CD!).</para>
265
266
	  </listitem>
	</varlistentry>
267

268
	<varlistentry>
269
270
271
	  <term>i386-unknown-openbsd (PCs running OpenBSD)
            <indexterm><primary>i386-unknown-openbsd</primary></indexterm> 
          </term>
272
273
274
275
276
277
278
279
	  <listitem>
	    <para>Supported, with native code generator.  Packages are
	    available through the ports system in the native package
	    format.</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
280
281
282
	  <term>i386-unknown-netbsd (PCs running NetBSD)
            <indexterm><primary>i386-unknown-netbsd</primary></indexterm>
          </term>
283
284
285
286
287
288
289
	  <listitem>
	    <para>Will require some minor porting effort, but should
	    work registerised.</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
290
291
292
	  <term>i386-unknown-mingw32 (PCs running Windows)
            <indexterm><primary>i386-unknown-mingw32</primary></indexterm>
          </term>
293
	  <listitem>
294
295
	    <para>Fully supported under Win9x, WinNT, Win2k, and
            WinXP.  Includes a native code generator.  Building from
296
297
298
            source requires a recent <ulink
            url="http://www.cygwin.com/">Cygwin</ulink> distribution
            to be installed.</para>
299
300
301
	  </listitem>
	</varlistentry>

302
	<varlistentry>
303
304
305
	  <term>ia64-unknown-linux
            <indexterm><primary>ia64-unknown-linux</primary></indexterm>
          </term>
306
	  <listitem>
307
308
	    <para>Supported, except there is no native code
	    generator.</para>
309
310
311
	  </listitem>
	</varlistentry>

312
	<varlistentry>
313
314
315
	  <term>x86_64-unknown-linux
            <indexterm><primary>x86_64-unknown-linux</primary></indexterm>
          </term>
316
<term>amd64-unknown-openbsd
317
318
            <indexterm><primary>amd64-unknown-linux</primary></indexterm>
          </term>
dons's avatar
dons committed
319
	  <listitem>
320
	    <para>Fully supported, with a native code generator and GHCi.</para>
dons's avatar
dons committed
321
322
323
	  </listitem>
	</varlistentry>

324
	<varlistentry>
325
326
327
	  <term>mips-sgi-irix5
            <indexterm><primary>mips-sgi-irix[5-6]</primary></indexterm>
          </term>
328
	  <listitem>
329
330
331
332
333
	    <para>Port has worked in the past, but hasn't been tested
            for some time (and will certainly have rotted in various
            ways).  As usual, we don't have access to machines and
            there hasn't been an overwhelming demand for this port,
            but feel free to get in touch.</para>
334
335
336
	  </listitem>
	</varlistentry>

dons's avatar
dons committed
337
	<varlistentry>
338
339
340
	  <term>mips64-sgi-irix6
            <indexterm><primary>mips-sgi-irix6</primary></indexterm>
          </term>
dons's avatar
dons committed
341
342
343
344
345
	  <listitem>
	    <para>GHC currently works unregisterised.</para>
	  </listitem>
	</varlistentry>

346
	<varlistentry>
347
348
349
	  <term>powerpc-ibm-aix
            <indexterm><primary>powerpc-ibm-aix</primary></indexterm>
          </term>
350
	  <listitem>
351
352
353
354
355
356
357
358
	    <para>Port currently doesn't work, needs some minimal
            porting effort.  As usual, we don't have access to
            machines and there hasn't been an overwhelming demand for
            this port, but feel free to get in touch.</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
359
360
361
	  <term>powerpc-apple-darwin
            <indexterm><primary>powerpc-apple-darwin</primary></indexterm> 
          </term>
362
	  <listitem>
363
364
	    <para>Supported registerised.  Native code generator is
	    almost working.</para>
365
366
367
368
	  </listitem>
	</varlistentry>

	<varlistentry>
369
370
371
	  <term>powerpc-apple-linux
            <indexterm><primary>powerpc-apple-linux</primary></indexterm> 
          </term>
372
373
	  <listitem>
	    <para>Not supported (yet).</para>
374
375
376
377
378
379
380
381
382
	  </listitem>
	</varlistentry>
      </variablelist>

      <para>Various other systems have had GHC ported to them in the
      distant past, including various Motorola 68k boxes.  The 68k
      support still remains, but porting to one of these systems will
      certainly be a non-trivial task.</para>
  </sect1>
rrt's avatar
rrt committed
383

384
385
  <sect1 id="sec-pre-supposed">
    <title>Installing pre-supposed utilities</title>
rrt's avatar
rrt committed
386

387
388
    <indexterm><primary>pre-supposed utilities</primary></indexterm>
    <indexterm><primary>utilities, pre-supposed</primary></indexterm>
rrt's avatar
rrt committed
389

390
391
392
393
394
395
396
    <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
397

398
    <variablelist>
rrt's avatar
rrt committed
399

400
      <varlistentry>
401
402
403
404
	<term>GHC
          <indexterm><primary>pre-supposed: GHC</primary></indexterm>
          <indexterm><primary>GHC, pre-supposed</primary></indexterm>
        </term>
405
406
407
408
	<listitem>
	  <para>GHC is required to build many of the tools, including
	  GHC itself.  If you need to port GHC to your platform
	  because there isn't a binary distribution of GHC available,
409
	  then see <xref linkend="sec-porting-ghc"/>.</para>
410
411
412
413
414
415
416
417

	  <para>Which version of GHC you need will depend on the
	  packages you intend to build.  GHC itself will normally
	  build using one of several older versions of itself - check
	  the announcement or release notes for details.</para>
	</listitem>
      </varlistentry>

418
      <varlistentry>
419
420
421
422
	<term>Perl
          <indexterm><primary>pre-supposed: Perl</primary></indexterm>
          <indexterm><primary>Perl, pre-supposed</primary></indexterm>
        </term>
423
424
425
426
427
	<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
428
429
430
          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>
431
432
433
434
435
436
437
438
439
440
441
442

	  <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
443

444
      <varlistentry>
445
446
447
448
	<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>
449
	<listitem>
450
451
452
453
454
455
	  <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>

456
457
	  <para>If your GCC dies with &ldquo;internal error&rdquo; on
          some GHC source file, please let us know, so we can report
458
          it and get things improved.  (Exception: on x86
459
460
461
462
463
          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
464

465
      <varlistentry>
466
467
468
	<term>GNU Make
          <indexterm><primary>make</primary><secondary>GNU</secondary></indexterm>
        </term>
469
470
471
472
473
	<listitem>
	  <para>The fptools build system makes heavy use of features
	  specific to GNU <command>make</command>, so you must have
	  this installed in order to build any of the fptools
	  suite.</para>
474
475
476

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

480
      <varlistentry>
481
	<term><ulink url="http://www.haskell.org/happy">Happy</ulink>
482
483
          <indexterm><primary>Happy</primary></indexterm>
        </term>
484
485
	<listitem>
	  <para>Happy is a parser generator tool for Haskell, and is
486
487
          used to generate GHC's parsers.</para>

488
	  <para>If you start from a source tarball of GHC (i.e. not a darcs
489
490
	    checkout), then you don't need Happy, because we supply the
	    pre-processed versions of the Happy parsers.  If you intend to
491
	    modify the compiler and/or you're using a darcs checkout, then you
492
493
494
495
496
	    need Happy.</para>

	  <para>Happy version 1.15 is currently required to build GHC.</para>

	  <para>Happy is written in
497
498
499
500
          Haskell, and is a project in the CVS repository
          (<literal>fptools/happy</literal>).  It can be built from
          source, but bear in mind that you'll need GHC installed in
          order to build it.  To avoid the chicken/egg problem,
501
          install a binary distribution of either Happy or GHC to get
502
          started.  Happy distributions are available from <ulink url="http://www.haskell.org/happy/">Happy's Web
503
504
505
          Page</ulink>.</para>
	</listitem>
      </varlistentry>
rrt's avatar
rrt committed
506

507
      <varlistentry>
508
509
510
	<term>Alex
          <indexterm><primary>Alex</primary></indexterm>
        </term>
511
512
	<listitem>
	  <para>Alex is a lexical-analyser generator for Haskell,
513
514
515
516
	  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
517
	    building a darcs checkout.</para>
518
519

	  <para>Alex is
520
	  written in Haskell and is a project in the darcs repository.
521
	  Alex distributions are available from <ulink url="http://www.haskell.org/alex/">Alex's Web
522
523
524
525
	  Page</ulink>.</para>
	</listitem>
      </varlistentry>

526
      <varlistentry>
527
528
529
530
	<term>autoconf
          <indexterm><primary>pre-supposed: autoconf</primary></indexterm>
          <indexterm><primary>autoconf, pre-supposed</primary></indexterm>
        </term>
531
	<listitem>
532
	  <para>GNU autoconf is needed if you intend to build from the
533
          darcs sources, it is <emphasis>not</emphasis> needed if you
534
535
          just intend to build a standard source distribution.</para>

536
537
	  <para>Version 2.52 or later of the autoconf package is required.
	  NB. version 2.13 will no longer work, as of GHC version
538
539
	  6.1.</para>

540
541
542
543
544
545
	  <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>
546
547
	</listitem>
      </varlistentry>
rrt's avatar
rrt committed
548

549
      <varlistentry>
550
551
552
553
	<term><command>sed</command>
          <indexterm><primary>pre-supposed: sed</primary></indexterm>
          <indexterm><primary>sed, pre-supposed</primary></indexterm>
        </term>
554
555
556
557
558
559
560
561
562
563
	<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
564

565
566
567
568
569
570
    <para>One <literal>fptools</literal> project is worth a quick note
    at this point, because it is useful for all the others:
    <literal>glafp-utils</literal> contains several utilities which
    aren't particularly Glasgow-ish, but Occasionally Indispensable.
    Like <command>lndir</command> for creating symbolic link
    trees.</para>
rrt's avatar
rrt committed
571

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

575
576
      <variablelist>
	<varlistentry>
577
	  <term>PVM version 3:
578
	  <indexterm><primary>pre-supposed: PVM3 (Parallel Virtual Machine)</primary></indexterm>
579
580
            <indexterm><primary>PVM3 (Parallel Virtual Machine), pre-supposed</primary></indexterm>
          </term>
581
582
583
	  <listitem>
	    <para>PVM is the Parallel Virtual Machine on which
            Parallel Haskell programs run.  (You only need this if you
584
            plan to run Parallel Haskell.  Concurrent Haskell, which
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
            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
600

601
	<varlistentry>
602
603
604
	  <term><command>bash</command>:
            <indexterm><primary>bash, presupposed (Parallel Haskell only)</primary></indexterm>
          </term>
605
606
607
608
609
610
611
612
613
	  <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>
    </sect2>
rrt's avatar
rrt committed
614

615
616
    <sect2 id="pre-supposed-other-tools">
      <title>Other useful tools</title>
rrt's avatar
rrt committed
617

618
619
      <variablelist>
	<varlistentry>
620
621
622
623
	  <term>Flex
            <indexterm><primary>pre-supposed: flex</primary></indexterm> 
            <indexterm><primary>flex, pre-supposed</primary></indexterm>
          </term>
624
625
626
627
628
629
630
631
632
	  <listitem>
	    <para>This is a quite-a-bit-better-than-Lex lexer.  Used
            to build a couple of utilities in
            <literal>glafp-utils</literal>.  Depending on your
            operating system, the supplied <command>lex</command> may
            or may not work; you should get the GNU version.</para>
	  </listitem>
	</varlistentry>
      </variablelist>
633
634
635

      <para>More tools are required if you want to format the documentation
      that comes with GHC and other fptools projects.  See <xref
636
      linkend="building-docs"/>.</para>
637
638
    </sect2>
  </sect1>
rrt's avatar
rrt committed
639

640
641
  <sect1 id="sec-building-from-source">
    <title>Building from source</title>
rrt's avatar
rrt committed
642

643
644
    <indexterm><primary>Building from source</primary></indexterm>
    <indexterm><primary>Source, building from</primary></indexterm>
rrt's avatar
rrt committed
645

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

648
649
650
    <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
651

652
653
<screen>$ autoreconf<footnote><para>not necessary if you started from a source tarball</para>
      </footnote>
654
$ ./configure
655
$ make
656
$ make install</screen>
657
658
659

      <para>For GHC, this will do a 2-stage bootstrap build of the
      compiler, with profiling libraries, and install the
660
661
662
663
664
665
666
      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>
667
668
669

      <para>If you want to do anything at all non-standard, or you
      want to do some development, read on...</para>
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
    </sect1>
    
    <sect1 id="quick-start">
      <title>Quick start for GHC developers</title>
      
      <para>This section is a copy of the file
	<literal>ghc/HACKING</literal> from the GHC source tree.  It describes
	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>
694

695
696
    <sect2 id="sec-source-tree">
      <title>Your source tree</title>
rrt's avatar
rrt committed
697

698
699
700
701
      <para>The source code is held in your <emphasis>source
      tree</emphasis>.  The root directory of your source tree
      <emphasis>must</emphasis> contain the following directories and
      files:</para>
rrt's avatar
rrt committed
702

703
704
705
706
707
      <itemizedlist>
	<listitem>
	  <para><filename>Makefile</filename>: the root
	  Makefile.</para>
	</listitem>
rrt's avatar
rrt committed
708

709
710
711
712
713
	<listitem>
	  <para><filename>mk/</filename>: the directory that contains
          the main Makefile code, shared by all the
          <literal>fptools</literal> software.</para>
	</listitem>
rrt's avatar
rrt committed
714

715
	<listitem>
716
	  <para><filename>configure.ac</filename>,
717
718
719
720
          <filename>config.sub</filename>,
          <filename>config.guess</filename>: these files support the
          configuration process.</para>
	</listitem>
rrt's avatar
rrt committed
721

722
723
724
725
	<listitem>
	  <para><filename>install-sh</filename>.</para>
	</listitem>
      </itemizedlist>
rrt's avatar
rrt committed
726

727
728
729
730
731
732
733
734
735
736
737
738
      <para>All the other directories are individual
      <emphasis>projects</emphasis> of the <literal>fptools</literal>
      system&mdash;for example, the Glasgow Haskell Compiler
      (<literal>ghc</literal>), the Happy parser generator
      (<literal>happy</literal>), the <literal>nofib</literal>
      benchmark suite, and so on.  You can have zero or more of these.
      Needless to say, some of them are needed to build others.</para>

      <para>The important thing to remember is that even if you want
      only one project (<literal>happy</literal>, say), you must have
      a source tree whose root directory contains
      <filename>Makefile</filename>, <filename>mk/</filename>,
739
      <filename>configure.ac</filename>, and the project(s) you want
740
741
742
      (<filename>happy/</filename> in this case).  You cannot get by
      with just the <filename>happy/</filename> directory.</para>
    </sect2>
rrt's avatar
rrt committed
743

744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
    <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
770
      <filename>fptools/glafp-utils/lndir</filename>). See <xref
771
      linkend="sec-storysofar"/> for a typical invocation.</para>
772
773
774
775
776
777
778

      <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
779
      rule is that (with a single exception&mdash;<xref
780
      linkend="sec-build-config"/>) <emphasis>absolutely everything in
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
      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
      must be (a linked copy of) the root directory of the
      <literal>fptools</literal> suite.  Inside Makefiles, the root of
      your build tree is called
      <constant>&dollar;(FPTOOLS&lowbar;TOP)</constant><indexterm><primary>FPTOOLS&lowbar;TOP</primary></indexterm>.
      In the rest of this document path names are relative to
      <constant>&dollar;(FPTOOLS&lowbar;TOP)</constant> unless
      otherwise stated.  For example, the file
      <filename>ghc/mk/target.mk</filename> is actually
815
      <filename>&dollar;(FPTOOLS&lowbar;TOP)/ghc/mk/target.mk</filename>.</para>
816
    </sect2>
rrt's avatar
rrt committed
817

818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
    <sect2 id="sec-build-config">
      <title>Getting the build you want</title>

      <para>When you build <literal>fptools</literal> 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
      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
      <literal>fptools</literal> 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>

      <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
843

844
845
846
847
      <variablelist>
	<varlistentry>
	  <term>Step 1: get ready for configuration.</term>
	  <listitem>
848
	    <para>NOTE: if you're starting from a source distribution,
849
	    rather than darcs sources, you can skip this step.</para>
850

851
852
	    <para>Change directory to
            <constant>&dollar;(FPTOOLS&lowbar;TOP)</constant> and
853
            issue the command</para>
854
<screen>$ autoreconf</screen>
855
            <indexterm><primary>autoreconf</primary></indexterm>
856
            <para>(with no arguments). This GNU program (recursively) converts
857
858
            <filename>&dollar;(FPTOOLS&lowbar;TOP)/configure.ac</filename> and
            <filename>&dollar;(FPTOOLS&lowbar;TOP)/aclocal.m4</filename>
859
            to a shell script called
860
            <filename>&dollar;(FPTOOLS&lowbar;TOP)/configure</filename>.
861
862
863
864
	      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'".
865
866
            </para>

867
868
869
	    <para>Some projects, including GHC, have their own configure script.
            <command>autoreconf</command> takes care of that, too, so all you have
             to do is calling <command>autoreconf</command> in the top-level directory
870
            <filename>&dollar;(FPTOOLS&lowbar;TOP)</filename>.</para>
871
872
873
874
875
876

	    <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>
877
878
	  </listitem>
	</varlistentry>
rrt's avatar
rrt committed
879

880
881
882
883
884
	<varlistentry>
	  <term>Step 2: system configuration.</term>
	  <listitem>
	    <para>Runs the newly-created <command>configure</command>
	    script, thus:</para>
rrt's avatar
rrt committed
885

886
<screen>$ ./configure <optional><parameter>args</parameter></optional></screen>
rrt's avatar
rrt committed
887

888
889
890
	    <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
891
            <function>vfork</function> system call, where
892
            <command>tar</command> is kept, whether
893
894
895
896
897
            <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
898

899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
	    <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
917

918
919
920
921
922
923
924
925
926
927
	      <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
928

929
930
931
932
	    <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
933

934
935
	    <variablelist>
	      <varlistentry>
936
937
938
		<term><literal>--with-ghc=<parameter>path</parameter></literal>
                  <indexterm><primary><literal>--with-ghc</literal></primary></indexterm>
                </term>
939
		<listitem>
940
941
942
943
944
945
946
947
948
		  <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>
949
		</listitem>
950
951
952
	      </varlistentry>
	      
	      <varlistentry>
953
954
955
		<term><literal>--with-hc=<parameter>path</parameter></literal>
                  <indexterm><primary><literal>--with-hc</literal></primary></indexterm>
                </term>
956
		<listitem>
957
958
959
960
		  <para>Specifies the path to any installed Haskell
		  compiler.  This compiler will be used for compiling
		  generic Haskell code.  The default is to use
		  <literal>ghc</literal>.</para>
961
		</listitem>
962
963
964
	      </varlistentry>
	      
	      <varlistentry>
965
966
967
		<term><literal>--with-gcc=<parameter>path</parameter></literal>
                  <indexterm><primary><literal>--with-gcc</literal></primary></indexterm>
                </term>
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
		<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
            <literal>fptools</literal> is to differ from the standard
            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
1002

1003
      <para>And that's it for configuration. Simple, eh?</para>
1004
1005

      <para>What do you put in your build-specific configuration file
1006
      <filename>mk/build.mk</filename>?  <emphasis>For almost all
1007
      purposes all you will do is put make variable definitions that
1008
      override those in</emphasis>
1009
1010
1011
1012
1013
1014
1015
1016
1017
      <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,
1018
      <filename>mk/boilerplate.mk</filename><indexterm><primary>boilerplate.mk</primary></indexterm>,
1019
1020
1021
      includes <filename>build.mk</filename> after
      <filename>config.mk</filename>.)</para>

1022
1023
1024
     <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>

1025
1026
      <para>For example, <filename>config.mk.in</filename> contains
      the definition:</para>
rrt's avatar
rrt committed
1027

1028
<programlisting>GhcHcOpts=-O -Rghc-timing</programlisting>
rrt's avatar
rrt committed
1029

1030
1031
1032
1033
1034
      <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>
1035
      
1036
      <para>or, if you prefer,</para>
rrt's avatar
rrt committed
1037

1038
<programlisting>GhcHcOpts += -DDEBUG</programlisting>
rrt's avatar
rrt committed
1039

1040
1041
      <para>GNU <command>make</command> allows existing definitions to
      have new text appended using the &ldquo;<literal>+=</literal>&rdquo;
1042
      operator, which is quite a convenient feature.)</para>
rrt's avatar
rrt committed
1043

1044
1045
1046
1047
      <para>If you want to remove the <literal>-O</literal> as well (a
      good idea when developing, because the turn-around cycle gets a
      lot quicker), you can just override
      <literal>GhcLibHcOpts</literal> altogether:</para>
rrt's avatar
rrt committed
1048

1049
<programlisting>GhcHcOpts=-DDEBUG -Rghc-timing</programlisting>
rrt's avatar
rrt committed
1050

1051
      <para>When reading <filename>config.mk.in</filename>, remember
1052
1053
1054
      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
1055
1056
      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
1057

1058
<programlisting>TAR = @TarCmd@</programlisting>
rrt's avatar
rrt committed
1059

1060
1061
      <para>This defines the Make variables <constant>TAR</constant>
      to the pathname for a <command>tar</command> that
1062
      <command>configure</command> finds somewhere.  If you have your
1063
      own pet <command>tar</command> you want to use instead, that's
1064
      fine. Just add this line to <filename>mk/build.mk</filename>:</para>
rrt's avatar
rrt committed
1065

1066
<programlisting>TAR = mytar</programlisting>
rrt's avatar
rrt committed
1067

1068
      <para>You do not <emphasis>have</emphasis> to have a
1069
1070
1071
1072
1073
      <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
1074
      anything that <command>configure</command> got wrong.  One place
1075
      where this happens often is with the definition of
1076
      <constant>FPTOOLS&lowbar;TOP&lowbar;ABS</constant>: this
1077
1078
1079
      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
1080
      that <command>configure</command> has got it wrong, just put the
1081
      correct definition in <filename>build.mk</filename>.</para>
rrt's avatar
rrt committed
1082

1083
    </sect2>
rrt's avatar
rrt committed
1084

1085
1086
1087
1088
1089
1090
1091
1092
    <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>
1093
	  <para> Get your source tree from somewhere (darcs repository
1094
1095
1096
          or source distribution).  Say you call the root directory
          <filename>myfptools</filename> (it does not have to be
          called <filename>fptools</filename>).  Make sure that you
1097
          have the essential files (see <xref
1098
          linkend="sec-source-tree"/>).</para>
1099
1100
1101
1102
	</listitem>

	<listitem>

1103
1104
	  <para>(Optional) Use <command>lndir</command> or
	  <command>mkshadowdir</command> to create a build tree.</para>
1105

1106
1107
<screen>$ cd myfptools
$ mkshadowdir . /scratch/joe-bloggs/myfptools-sun4</screen>
1108

1109
	  <para>(N.B. <command>mkshadowdir</command>'s first argument
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
          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>

1120
<screen>$ cd /scratch/joe-bloggs/myfptools-sun4</screen>
1121
1122
1123
1124
1125
1126

	</listitem>

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

1127
<screen>$ autoreconf</screen>
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137

	  <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>

1138
<screen>$ ./configure</screen>
1139
1140
1141
1142
1143

	  <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>
1144
1145
1146
1147
	</listitem>

	<listitem>
	  <para>Create the file <filename>mk/build.mk</filename>,
1148
1149
          adding definitions for your desired configuration
          options.</para>
1150

1151
<screen>$ emacs mk/build.mk</screen>
1152
1153
1154
1155
1156
1157
1158
	</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
1159
      <command>gmake clean</command>, <command>gmake all</command>,
1160
1161
1162
1163
1164
1165
      because configuration option changes could affect
      anything&mdash;but in practice you are likely to know what's
      affected.</para>
    </sect2>

    <sect2>
1166
      <title>Making things</title>
rrt's avatar
rrt committed
1167

1168
1169
1170
      <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
1171

1172
1173
1174
1175
1176
1177
1178
      <para>The first thing you need to know is that <emphasis>you
      must use GNU <command>make</command>, usually called
      <command>gmake</command>, not standard Unix
      <command>make</command></emphasis>.  If you use standard Unix
      <command>make</command> you will get all sorts of error messages
      (but no damage) because the <literal>fptools</literal>
      <command>Makefiles</command> use GNU <command>make</command>'s
1179
      facilities extensively.</para>
rrt's avatar
rrt committed
1180

1181
1182
1183
1184
      <para>To just build the whole thing, <command>cd</command> to
      the top of your <literal>fptools</literal> tree and type
      <command>gmake</command>.  This will prepare the tree and build
      the various projects in the correct order.</para>
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
    </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
      by the top-level fptools <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.  When building
      GHC, the top-level fptools <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>

      <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>
      </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
      <literal>ghc/compiler</literal> directory, but don't forget that
      each stage requires its own <literal>make boot</literal> step:
      for example, you must do</para>

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

1269
1270
      <para>before <literal>make stage2</literal> in
      <literal>ghc/compiler</literal>.</para>
1271
    </sect2>
rrt's avatar
rrt committed
1272

1273
1274
    <sect2 id="sec-standard-targets">
      <title>Standard Targets</title>
1275
1276
      <indexterm><primary>targets, standard makefile</primary></indexterm>
      <indexterm><primary>makefile targets</primary></indexterm>
rrt's avatar
rrt committed
1277

1278
      <para>In any directory you should be able to make the following:</para>
rrt's avatar
rrt committed
1279

1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
      <variablelist>
	<varlistentry>
	  <term><literal>boot</literal></term>
	  <listitem>
	    <para>does the one-off preparation required to get ready
            for the real work.  Notably, it does <command>gmake
            depend</command> in all directories that contain programs.
            It also builds the necessary tools for compilation to
            proceed.</para>

	    <para>Invoking the <literal>boot</literal> target
            explicitly is not normally necessary.  From the top-level
            <literal>fptools</literal> directory, invoking
            <literal>gmake</literal> causes <literal>gmake boot
            all</literal> to be invoked in each of the project
            subdirectories, in the order specified by
            <literal>&dollar;(AllTargets)</literal> in
            <literal>config.mk</literal>.</para>

	    <para>If you're working in a subdirectory somewhere and
            need to update the dependencies, <literal>gmake
            boot</literal> is a good way to do it.</para>
	  </listitem>
	</varlistentry>
rrt's avatar
rrt committed
1304