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.
./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:
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 hslibsThe 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-cardor, 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 = myyaccYou 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'.