Go to the first, previous, next, last section, table of contents.

Getting the build you want

When you build `fptools' you will be compiling code on a particular host platform, to run on a particular target platform (usually the same as the host platform). 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.

There are also knobs you can turn to control how the `fptools' 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.

All of this stuff is called the configuration of your build. You set the configuration using an exciting three-step process.

Step 1: get ready for configuration.
Change directory to `$(FPTOOLS)' and issue the command `autoconf' (with no arguments). This GNU program converts `$(FPTOOLS)/configure.in' to a shell script called `$(FPTOOLS)/configure'. Both these steps are completely platform-independent; they just mean that the human-written file (`configure.in') can be short, although the resulting shell script, `configure', and `mk/config.h.in', are long. In case you don't have `autoconf' we distribute the results, `configure', and `mk/config.h.in', with the source distribution. They aren't kept in the repository, though.
Step 2: system configuration.
Runs the newly-created `configure' script, thus: 
  ./configure
`configure''s mission is to scurry round your computer working out what architecture it has, what operating system, whether it has the `vfork' system call, where `yacc' is kept, whether `gcc' is available, where various obscure `#include' 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: `configure' caches the results of its run in `config.cache'. Quite often you don't want that; you're running `configure' a second time because something has changed. In that case, simply delete `config.cache'.
Step 3: build configuration.
Next, you say how this build of `fptools' is to differ from the standard 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 keep a private directory of `build.mk' files, and use a symbolic link in each build tree to point to the appropriate one.) So `mk/build.mk' never exists in the source tree -- you create one in each build tree from the template. We'll discuss what to put in it 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 `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, what you do is edit `mk/config.mk.in' (read-only), and add definitions in `mk/build.mk' that override any of the `config.mk' definitions that you want to change. (The override occurs because the main boilerplate file, `mk/boilerplate.mk', includes `build.mk' after `config.mk'.)

For example, `config.mk.in' contains the definition: 

  ProjectsToBuild = glafp-utils literate happy ghc hslibs
The accompanying comment explains that this is the list of enabled projects; that is, if (after configuring) you type `gmake all' in `FPTOOLS_TOP' three specified projects will be made. If you want to add `green-card', you can add this line to `build.mk': 
  ProjectsToBuild += green-card
or, if you prefer, 
  ProjectsToBuild = glafp-utils literate happy ghc hslibs green-card
(GNU `make' allows existing definitions to have new text appended using the "`+='" operator, which is quite a convenient feature.)

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 line that says: 

  YACC = @Yacc@
This defines the Make variables `YACC' to the pathname for a Yacc that `configure' finds somewhere. If you have your own pet Yacc you want to use instead, that's fine. Just add this line to `mk/build.mk': 
  YACC = myyacc
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 can also use `build.mk' to override anything that `configure' got wrong. One place where this happens often is with the definition of `FPTOOLS_TOP_ABS': this 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 that `configure' has got it wrong, just put the correct definition in `build.mk'.

Go to the first, previous, next, last section, table of contents.