Boilerplate architecture

Every `Makefile' includes a `boilerplate.mk' file at the top, and `target.mk' file at the bottom. In this section we discuss what is in these files, and why there have to be two of them. In general:

• `boilerplate.mk' consists of:
  • Definitions of millions of `make' variables that collectively specify the build configuration. Examples: `HC_OPTS', the options to feed to the Haskell compiler; `NoFibSubDirs', the sub-directories to enable within the `nofib' project; `GhcWithHc', the name of the Haskell compiler to use when compiling `GHC' in the `ghc' project.
  • Standard pattern rules that tell `gmake' how to construct one file from another.
  `boilerplate.mk' needs to be `include'd at the top of each `Makefile', so that the user can replace the boilerplate definitions or pattern rules by simply giving a new definition or pattern rule in the `Makefile'. `gmake' simply takes the last definition as the definitive one. Instead of replacing boilerplate definitions, it is also quite common to augment them. For example, a `Makefile' might say:

    SRC_HC_OPTS += -O
  

  thereby adding "`-O'" to the end of `SRC_HC_OPTS'.
• `target.mk' contains `make' rules for the standard targets described in Section See section Standard targets. These rules are selectively included, depending on the setting of certain `make' variables. These variables are usually set in the middle section of the `Makefile' between the two `include's. `target.mk' must be included at the end (rather than being part of `boilerplate.mk') for several tiresome reasons:
  • `gmake' commits target and dependency lists earlier than it should. For example, `target.mk' has a rule that looks like this:

      $(HS_PROG) : $(OBJS)
            $(HC) $(LD_OPTS) $< -o $@
    

    If this rule was in `boilerplate.mk' then `$(HS_PROG)' and `$(OBJS)' would not have their final values at the moment `gmake' encountered the rule. Alas, `gmake' takes a snapshot of their current values, and wires that snapshot into the rule. (In contrast, the commands executed when the rule "fires" are only substituted at the moment of firing.) So, the rule must follow the definitions given in the `Makefile' itself.
  • Unlike pattern rules, ordinary rules cannot be overriden or replaced by subsequent rules for the same target (at least not without an error message). Including ordinary rules in `boilerplate.mk' would prevent the user from writing rules for specific targets in specific cases.
  • There are a couple of other reasons I've forgotten, but it doesn't matter too much.