Skip to content

Changes

Page history
Re-run import authored by Tobias Dammers's avatar Tobias Dammers
Hide whitespace changes
Inline Side-by-side
attic/building/old/using.md
View page @ cc1a7a6a
......@@ -187,38 +187,41 @@ communicates these snippets of information in two ways:
to get a list of the available arguments. Here are some of
the ones you might need:
<table><tr><th>`--with-ghc=<path>`</th>
<table><tr><th><tt>--with-ghc=<path></tt></th>
<td>
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 *cannot* be specified using `build.mk`
(see later), because `configure` needs to auto-detect the
version of GHC you're using. The default is to look for a compiler
named `ghc` in your path.
itself). This option <i>cannot</i> be specified using <tt>build.mk</tt>
(see later), because <tt>configure</tt> needs to auto-detect the
version of GHC you&apos;re using. The default is to look for a compiler
named <tt>ghc</tt> in your path.
</td></tr>
<tr><th>`--with-hc=<path>`</th>
<tr><th><tt>--with-hc=<path></tt></th>
<td>
Specifies the path to any installed Haskell compiler. This compiler
will be used for compiling generic Haskell code. The default is to
use `ghc`. (NOTE: I'm not sure it actually works to specify a
compiler other than GHC here; unless you really know what you're
use <tt>ghc</tt>. (NOTE: I&apos;m not sure it actually works to specify a
compiler other than GHC here; unless you really know what you&apos;re
doing I suggest not using this option at all.)
</td></tr>
<tr><th>`--with-gcc=<path>`</th>
<tr><th><tt>--with-gcc=<path></tt></th>
<td>
Specifies the path to the installed GCC. This compiler will be used
to compile all C files, *except* any generated by the installed
to compile all C files, <i>except</i> 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 `gcc`.
(if any) to use. The default is to use <tt>gcc</tt>.
</td></tr></table>
### Step 3: build configuration.
Next, you say how this build of GHC is to differ from the standard
defaults by creating a new file `mk/build.mk`*in the build
defaults by creating a new file `mk/build.mk` *in the build
tree*. 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
......@@ -232,9 +235,11 @@ shortly.
And that's it for configuration. Simple, eh?
What do you put in your build-specific configuration file
`mk/build.mk`? *For almost all purposes all you will do is put
make variable definitions that override those in*`mk/config.mk.in`. The whole point of
make variable definitions that override those in*
`mk/config.mk.in`. The whole point of
`mk/config.mk.in` — and its derived counterpart
`mk/config.mk` — is to define the build configuration. It is
heavily commented, as you will see if you look at it. So generally,
......@@ -249,60 +254,69 @@ For your convenience, there's a file called `build.mk.sample` that
can serve as a starting point for your `build.mk`.
For example, `config.mk.in` contains the definition:
<table><tr><th>`GhcHcOpts = -Rghc-timing`</th>
<table><tr><th><tt>GhcHcOpts = -Rghc-timing</tt></th>
<td>
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 `-DDEBUG`, to enable debugging code. So you
would add the following to `build.mk`:
is wise to add <tt>-DDEBUG</tt>, to enable debugging code. So you
would add the following to <tt>build.mk</tt>:
</td></tr>
<tr><th>`GhcHcOpts += -DDEBUG`</th>
<tr><th><tt>GhcHcOpts += -DDEBUG</tt></th>
<td>
GNU `make` allows existing definitions to have new text appended
using the "`+=`" operator, which is quite a convenient feature.
Haskell compilations by default have `-O` turned on, by virtue
of this setting from `config.mk`:
GNU <tt>make</tt> allows existing definitions to have new text appended
using the &quot;<tt>+=</tt>&quot; operator, which is quite a convenient feature.
<br><br>
Haskell compilations by default have <tt>-O</tt> turned on, by virtue
of this setting from <tt>config.mk</tt>:
</td></tr></table>
<table><tr><th>`SRC_HC_OPTS += -H16m -O`</th>
<td>`SRC_HC_OPTS` means "options for HC from the source tree", where
HC stands for Haskell Compiler. `SRC_HC_OPTS` are added to
<table><tr><th><tt>SRC_HC_OPTS += -H16m -O</tt></th>
<td>
<tt>SRC_HC_OPTS</tt> means &quot;options for HC from the source tree&quot;, where
HC stands for Haskell Compiler. <tt>SRC_HC_OPTS</tt> are added to
every Haskell compilation. To turn off optimisation, you could add
this to `build.mk`:
this to <tt>build.mk</tt>:
</td></tr></table>
<table><tr><th>`SRC_HC_OPTS = -H16m -O0`</th>
<table><tr><th><tt>SRC_HC_OPTS = -H16m -O0</tt></th>
<td>
Or you could just add `-O0` to `GhcHcOpts` to turn off
optimisation for the compiler. See [Building/Hacking](building/hacking)
Or you could just add <tt>-O0</tt> to <tt>GhcHcOpts</tt> to turn off
optimisation for the compiler. See <a href="building/hacking">Building/Hacking</a>
for some more suggestions.
When reading `config.mk.in`, remember that anything between
"@...@" signs is going to be substituted by `configure` later.
You *can* override the resulting definition if you want, but you
need to be a bit surer what you are doing. For example, there's a
<br><br>
When reading <tt>config.mk.in</tt>, remember that anything between
&quot;@...@&quot; signs is going to be substituted by <tt>configure</tt> later.
You <i>can</i> override the resulting definition if you want, but you
need to be a bit surer what you are doing. For example, there&apos;s a
line that says:
</td></tr></table>
<table><tr><th>`TAR = @TarCmd@`</th>
<table><tr><th><tt>TAR = @TarCmd@</tt></th>
<td>
This defines the Make variables `TAR` to the pathname for a
`tar` that `configure` finds somewhere. If you have your
own pet `tar` you want to use instead, that's fine. Just add
this line to `mk/build.mk`:
This defines the Make variables <tt>TAR</tt> to the pathname for a
<tt>tar</tt> that <tt>configure</tt> finds somewhere. If you have your
own pet <tt>tar</tt> you want to use instead, that&apos;s fine. Just add
this line to <tt>mk/build.mk</tt>:
</td></tr></table>
<table><tr><th>`TAR = mytar`</th>
<table><tr><th><tt>TAR = mytar</tt></th>
<td>
You do not *have* to have a `mk/build.mk` file at all; if you
don't, you'll get all the default settings from
`mk/config.mk.in`.
You do not <i>have</i> to have a <tt>mk/build.mk</tt> file at all; if you
don&apos;t, you&apos;ll get all the default settings from
<tt>mk/config.mk.in</tt>.
</td></tr></table>
>
>
> You can also use `build.mk` to override anything that
> `configure` got wrong. One place where this happens often is
......@@ -311,6 +325,8 @@ don't, you'll get all the default settings from
> system uses an automounter then the correct directory is hard to
> find automatically. If you find that `configure` has got it
> wrong, just put the correct definition in `build.mk`.
>
>
## The story so far
......@@ -416,49 +432,57 @@ best to start `make` from the top of the tree. The top-level
`Makefile` is set up to do a 2-stage bootstrap by default (when
you say `make`). Some other targets it supports are:
<table><tr><th>`stage1`</th>
<table><tr><th><tt>stage1</tt></th>
<td>
Build everything as normal, including the stage 1 compiler.
</td></tr></table>
<table><tr><th>`stage2`</th>
<table><tr><th><tt>stage2</tt></th>
<td>
Build the stage 2 compiler only.
</td></tr></table>
<table><tr><th>`stage3`</th>
<table><tr><th><tt>stage3</tt></th>
<td>
Build the stage 3 compiler only.
</td></tr></table>
<table><tr><th>`bootstrap`, `bootstrap2`</th>
<table><tr><th><tt>bootstrap</tt>, <tt>bootstrap2</tt></th>
<td>
Build stage 1 followed by stage 2.
</td></tr></table>
<table><tr><th>`bootstrap3`</th>
<table><tr><th><tt>bootstrap3</tt></th>
<td>
Build stages 1, 2 and 3.
</td></tr></table>
<table><tr><th>`install`</th>
<table><tr><th><tt>install</tt></th>
<td>
Install everything, including the compiler built in stage 2. To
override the stage, say `make install stage=n` where `n` is
override the stage, say <tt>make install stage=n</tt> where <tt>n</tt> is
the stage to install.
</td></tr></table>
<table><tr><th>`binary-dist`</th>
<table><tr><th><tt>binary-dist</tt></th>
<td>
make a binary distribution. This is the target we
use to build the binary distributions of GHC.
</td></tr></table>
<table><tr><th>`dist`</th>
<table><tr><th><tt>dist</tt></th>
<td>
make a source distribution. Note that this target
does `make distclean` as part of its work;
don't use it if you want to keep what you've built.
does <tt>make distclean</tt> as part of its work;
don&apos;t use it if you want to keep what you&apos;ve built.
</td></tr></table>
......@@ -481,84 +505,93 @@ before `make stage2` in `compiler`.
## Standard Targets
In any directory you should be able to make the following:
<table><tr><th>`boot`</th>
<table><tr><th><tt>boot</tt></th>
<td>
does the one-off preparation required to get ready for the real
work, e.g. building the module dependency graph.
Invoking the `boot` target explicitly is not normally necessary.
From the top-level directory, invoking `make` causes `make boot`
<br><br>
Invoking the <tt>boot</tt> target explicitly is not normally necessary.
From the top-level directory, invoking <tt>make</tt> causes <tt>make boot</tt>
to be invoked in various subdirectories, in the right
order. Unless you really know what you are doing, it is best to
always say `make` from the top level first.
If you're working in a subdirectory somewhere and need to update the
dependencies, `make boot` is a good way to do it.
always say <tt>make</tt> from the top level first.
<br><br>
If you&apos;re working in a subdirectory somewhere and need to update the
dependencies, <tt>make boot</tt> is a good way to do it.
</td></tr></table>
<table><tr><th>`all`</th>
<table><tr><th><tt>all</tt></th>
<td>
makes all the final target(s) for this Makefile. Depending on which
directory you are in a "final target" may be an executable program,
directory you are in a &quot;final target&quot; may be an executable program,
a library archive, a shell script, or a Postscript file. Typing
`make` alone is generally the same as typing `make all`.
<tt>make</tt> alone is generally the same as typing <tt>make all</tt>.
</td></tr></table>
<table><tr><th>`install`</th>
<table><tr><th><tt>install</tt></th>
<td>
installs the things built by `all` (except for the
installs the things built by <tt>all</tt> (except for the
documentation). Where does it install them? That is specified by
`mk/config.mk.in`; you can override it in `mk/build.mk`, or
by running `configure` with command-line arguments like
`--bindir=/home/simonpj/bin`; see `./configure --help` for
<tt>mk/config.mk.in</tt>; you can override it in <tt>mk/build.mk</tt>, or
by running <tt>configure</tt> with command-line arguments like
<tt>--bindir=/home/simonpj/bin</tt>; see <tt>./configure --help</tt> for
the full details.
</td></tr></table>
<table><tr><th>`install-docs`</th>
<table><tr><th><tt>install-docs</tt></th>
<td>
installs the documentation. Otherwise behaves just like
`install`.
<tt>install</tt>.
</td></tr></table>
<table><tr><th>`clean`</th>
<table><tr><th><tt>clean</tt></th>
<td>
Delete all files from the current directory that are normally
created by building the program. Don't delete the files that record
the configuration, or files generated by `make boot`. Also
preserve files that could be made by building, but normally aren't
created by building the program. Don&apos;t delete the files that record
the configuration, or files generated by <tt>make boot</tt>. Also
preserve files that could be made by building, but normally aren&apos;t
because the distribution comes with them.
</td></tr></table>
<table><tr><th>`distclean`</th>
<table><tr><th><tt>distclean</tt></th>
<td>
Delete all files from the current directory that are created by
configuring or building the program. If you have unpacked the source
and built the program without creating any other files, `make distclean`
and built the program without creating any other files, <tt>make distclean</tt>
should leave only the files that were in the distribution.
</td></tr></table>
<table><tr><th>`mostlyclean`</th>
<table><tr><th><tt>mostlyclean</tt></th>
<td>
Like `clean`, but may refrain from deleting a few files that
people normally don't want to recompile.
Like <tt>clean</tt>, but may refrain from deleting a few files that
people normally don&apos;t want to recompile.
</td></tr></table>
<table><tr><th>`maintainer-clean`</th>
<table><tr><th><tt>maintainer-clean</tt></th>
<td>
Delete everything from the current directory that can be
reconstructed with this Makefile. This typically includes
everything deleted by `distclean`, plus more: C source files
everything deleted by <tt>distclean</tt>, plus more: C source files
produced by Bison, tags tables, Info files, and so on.
One exception, however: `make maintainer-clean` should not
delete `configure` even if `configure` can be remade using a
rule in the `Makefile`. More generally, `make maintainer-clean`
<br><br>
One exception, however: <tt>make maintainer-clean</tt> should not
delete <tt>configure</tt> even if <tt>configure</tt> can be remade using a
rule in the <tt>Makefile</tt>. More generally, <tt>make maintainer-clean</tt>
should not delete anything that needs to exist in order to run
`configure` and then begin to build the program.
After a `maintainer-clean`, a `configure` will be necessary
<tt>configure</tt> and then begin to build the program.
<br><br>
After a <tt>maintainer-clean</tt>, a <tt>configure</tt> will be necessary
before building again.
</td></tr></table>
......@@ -566,23 +599,24 @@ before building again.
All of these standard targets automatically recurse into
sub-directories. Certain other standard targets do not:
<table><tr><th>`depend`</th>
<table><tr><th><tt>depend</tt></th>
<td>
make a `.depend` file in each directory that needs it. This
`.depend` file contains mechanically-generated dependency
make a <tt>.depend</tt> file in each directory that needs it. This
<tt>.depend</tt> file contains mechanically-generated dependency
information; for example, suppose a directory contains a Haskell
source module `Foo.lhs` which imports another module `Baz`.
Then the generated `.depend` file will contain the dependency:
source module <tt>Foo.lhs</tt> which imports another module <tt>Baz</tt>.
Then the generated <tt>.depend</tt> file will contain the dependency:
```wiki
Foo.o : Baz.hi
```
which says that the object file `Foo.o` depends on the interface
file `Baz.hi` generated by compiling module `Baz`. The
`.depend` file is automatically included by every Makefile.
which says that the object file <tt>Foo.o</tt> depends on the interface
file <tt>Baz.hi</tt> generated by compiling module <tt>Baz</tt>. The
<tt>.depend</tt> file is automatically included by every Makefile.
Now that we are using Cabal for most of the building, most directories
don't support the `depend` target any more. Use `boot` instead.
don&apos;t support the <tt>depend</tt> target any more. Use <tt>boot</tt> instead.
</td></tr></table>
......