From fb18dd5a4157aba23a7059491b43b369114a2749 Mon Sep 17 00:00:00 2001 From: simonmar Date: Thu, 31 Jan 2002 14:32:04 +0000 Subject: [PATCH] [project @ 2002-01-31 14:32:04 by simonmar] Update the building guide w.r.t. the enhanced source-file-searching mechanisms now in fptools/mk/paths.mk. Also, add a small section on Makefile debugging while I'm here, mentioning in particular 'make show'. --- docs/building/building.sgml | 1071 ++++++++++++++++++++++++------------------- 1 file changed, 603 insertions(+), 468 deletions(-) diff --git a/docs/building/building.sgml b/docs/building/building.sgml index 481f876..49fce4c 100644 --- a/docs/building/building.sgml +++ b/docs/building/building.sgml @@ -45,8 +45,8 @@ -Binary distributionBinary distribution. - +Binary distributionBinary distribution. + If your only purpose is to install some of the fptools suite then the easiest thing to do is to @@ -70,10 +70,10 @@ off. The second reason a binary distribution may not be what you want is if you want to read or modify the souce code. - + -Source distributionSource distribution. - +Source distributionSource distribution. + You have a supported platform, but (a) you like the warm fuzzy feeling of compiling things @@ -87,7 +87,7 @@ A source distribution contains complete sources for one or more projects in the fptools suite. Not only that, but the more awkward machine-independent steps are done for you. For example, if you don't have -happyhappy +happyhappy you'll find it convenient that the source distribution contains the result of running happy on the parser specifications. If you don't want to alter the parser then this saves @@ -96,7 +96,7 @@ still need a working version of GHC (preferably version 4.08+) on your machine in order to compile (most of) the sources, however. - + The CVS repository. @@ -125,7 +125,7 @@ machine in order to compile (most of) the sources, however. - Build GHC from intermediate C .hc fileshc files: + Build GHC from intermediate C .hc fileshc files: You need a working GHC to use a source distribution. What if you don't have a working GHC? Then you may be able @@ -889,10 +889,10 @@ list -ports, GHC -GHC ports -supported platforms -platforms, supported +ports, GHC +GHC ports +supported platforms +platforms, supported The main question is whether or not the Haskell compiler (GHC) runs on your platform. @@ -921,10 +921,10 @@ supports the underlying BSDisms. What platforms the Haskell compiler (GHC) runs on -fully-supported platforms -native-code generator -registerised ports -unregisterised ports +fully-supported platforms +native-code generator +registerised ports +unregisterised ports The GHC hierarchy of Porting Goodness: (a) Best is a native-code generator; (b) next best is a ``registerised'' port; (c) the bare minimum is an ``unregisterised'' port. @@ -1050,7 +1050,7 @@ or higher) powerpc-ibm-aix powerpc-ibm-aix - + 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 @@ -1085,16 +1085,16 @@ or higher) Installing pre-supposed utilities -<IndexTerm><Primary>pre-supposed utilities</Primary></IndexTerm> -<IndexTerm><Primary>utilities, pre-supposed</Primary></IndexTerm> +pre-supposed utilities +utilities, pre-supposed Here are the gory details about some utility programs you may need; perl, gcc and happy are the only important -ones. (PVMPVM is important +ones. (PVMPVM is important if you're going for Parallel Haskell.) The -configureconfigure +configureconfigure script will tell you if you are missing something. @@ -1102,10 +1102,10 @@ script will tell you if you are missing something. -Perl: -pre-supposed: Perl -Perl, pre-supposed - +Perl: +pre-supposed: Perl +Perl, pre-supposed + You have to have Perl to proceed! It is pretty easy to install. @@ -1124,12 +1124,12 @@ pathname may need to be less than 32 characters long on some systems. - + -GNU C (gcc): -pre-supposed: GCC (GNU C compiler) -GCC (GNU C compiler), pre-supposed - +GNU C (gcc): +pre-supposed: GCC (GNU C compiler) +GCC (GNU C compiler), pre-supposed + We recommend using GCC version 2.95.2 on all platforms. Failing that, @@ -1145,7 +1145,7 @@ please let us know, so we can report it and get things improved. (Exception: on iX86 boxes—you may need to fiddle with GHC's option; see the User's Guide) - + Happy: @@ -1164,10 +1164,10 @@ url="http://www.haskell.org/happy/">Happy's Web Page. -Autoconf: -pre-supposed: Autoconf -Autoconf, pre-supposed - +Autoconf: +pre-supposed: Autoconf +Autoconf, pre-supposed + GNU Autoconf is needed if you intend to build from the CVS sources, it is not needed if you just intend to build a @@ -1181,12 +1181,12 @@ If you modify either of these files, you'll need autoconf to rebuild configure. - + -sed -pre-supposed: sed -sed, pre-supposed - +sed +pre-supposed: sed +sed, pre-supposed + You need a working sed if you are going to build from sources. The build-configuration stuff needs it. GNU sed @@ -1194,7 +1194,7 @@ 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.) - + @@ -1214,10 +1214,10 @@ particularly Glasgow-ish, but Occasionally Indispensable. Like -PVM version 3: -pre-supposed: PVM3 (Parallel Virtual Machine) -PVM3 (Parallel Virtual Machine), pre-supposed - +PVM version 3: +pre-supposed: PVM3 (Parallel Virtual Machine) +PVM3 (Parallel Virtual Machine), pre-supposed + PVM is the Parallel Virtual Machine on which Parallel Haskell programs @@ -1237,17 +1237,17 @@ available on the net; I think I got it from A PVM installation is slightly quirky, but easy to do. Just follow the Readme instructions. - + -bash: -bash, presupposed (Parallel Haskell only) - +bash: +bash, presupposed (Parallel Haskell only) + Sadly, the gr2ps script, used to convert ``parallelism profiles'' to PostScript, is written in Bash (GNU's Bourne Again shell). This bug will be fixed (someday). - + @@ -1266,28 +1266,28 @@ documentation that comes with the fptools projects: -DocBook: -pre-supposed: DocBook -DocBook, pre-supposed - +DocBook: +pre-supposed: DocBook +DocBook, pre-supposed + All our documentation is written in SGML, using the DocBook DTD. Instructions on installing and configuring the DocBook tools are in the installation guide (in the GHC user guide). - + -TeX: -pre-supposed: TeX -TeX, pre-supposed - +TeX: +pre-supposed: TeX +TeX, pre-supposed + A decent TeX distribution is required if you want to produce printable documentation. We recomment teTeX, which includes just about everything you need. - + @@ -1308,10 +1308,10 @@ everything you need. -Flex: -pre-supposed: flex -flex, pre-supposed - +Flex: +pre-supposed: flex +flex, pre-supposed + This is a quite-a-bit-better-than-Lex lexer. Used to build a couple @@ -1319,7 +1319,7 @@ of utilities in glafp-utils. Depending on your operating system, the supplied lex may or may not work; you should get the GNU version. - + @@ -1329,8 +1329,8 @@ work; you should get the GNU version. Building from source -<IndexTerm><Primary>Building from source</Primary></IndexTerm> -<IndexTerm><Primary>Source, building from</Primary></IndexTerm> +Building from source +Source, building from You've been rash enough to want to build some of @@ -1366,33 +1366,33 @@ contain the following directories and files: - + Makefile: the root Makefile. - - + + mk/: the directory that contains the main Makefile code, shared by all the fptools software. - - + + configure.in, config.sub, config.guess: these files support the configuration process. - - + + install-sh. - + @@ -1418,8 +1418,8 @@ just the happy/ directory. Build trees -<IndexTerm><Primary>build trees</Primary></IndexTerm> -<IndexTerm><Primary>link trees, for building</Primary></IndexTerm> +build trees +link trees, for building While you can build a system in the source tree, we don't recommend it. @@ -1435,7 +1435,7 @@ 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 ``standard'' Unix utilities that make such copies, so standard that they go by different names: -lndirlndir, mkshadowdirmkshadowdir are two (If you +lndirlndir, mkshadowdirmkshadowdir are two (If you don't have either, the source distribution includes sources for the X11 lndir—check out fptools/glafp-utils/lndir). See for a typical invocation. @@ -1478,10 +1478,10 @@ copy. More commonly you do want to edit the source file.) Like the source tree, the top level of your build tree must be (a linked copy of) the root directory of the fptools suite. Inside Makefiles, the root of your build tree is called -$(FPTOOLS_TOP)FPTOOLS_TOP. In the rest of this document path -names are relative to $(FPTOOLS_TOP) unless otherwise stated. For +$(FPTOOLS_TOP)FPTOOLS_TOP. In the rest of this document path +names are relative to $(FPTOOLS_TOP) unless otherwise stated. For example, the file ghc/mk/target.mk is actually -$(FPTOOLS_TOP)/ghc/mk/target.mk. +$(FPTOOLS_TOP)/ghc/mk/target.mk. @@ -1493,7 +1493,7 @@ example, the file ghc/mk/target.mk is actually 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)platform. The +(usually the same as the host platform)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 @@ -1516,21 +1516,21 @@ You set the configuration using a three-step process. -Step 1: get ready for configuration. - +Step 1: get ready for configuration. + Change directory to - $(FPTOOLS_TOP) and + $(FPTOOLS_TOP) and issue the command - autoconfautoconf + autoconfautoconf (with no arguments). This GNU program converts - $(FPTOOLS_TOP)/configure.in + $(FPTOOLS_TOP)/configure.in to a shell script called - $(FPTOOLS_TOP)/configure. + $(FPTOOLS_TOP)/configure. Some projects, including GHC, have their own configure script. If there's an - $(FPTOOLS_TOP)/<project>/configure.in, + $(FPTOOLS_TOP)/<project>/configure.in, then you need to run autoconf in that directory too. @@ -1574,9 +1574,9 @@ You set the configuration using a three-step process. It translates - mk/config.mk.inconfig.mk.in + mk/config.mk.inconfig.mk.in to - mk/config.mkconfig.mk, + mk/config.mkconfig.mk, substituting for things between ``@'' brackets. So, ``@HaveGcc@'' will be replaced by @@ -1587,13 +1587,13 @@ You set the configuration using a three-step process. every Makefile (directly or indirectly), so the configuration information is thereby communicated to all Makefiles. - + It translates - mk/config.h.inconfig.h.in + mk/config.h.inconfig.h.in to - mk/config.hconfig.h. + mk/config.hconfig.h. The latter is #included by various C programs, which can thereby make use of configuration information. @@ -1660,11 +1660,11 @@ You set the configuration using a three-step process. -Step 3: build configuration. - +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.mkbuild.mk +standard defaults by creating a new file mk/build.mkbuild.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 @@ -1674,7 +1674,7 @@ symbolic link in each build tree to point to the appropriate one.) So each build tree from the template. We'll discuss what to put in it shortly. - + @@ -1695,7 +1695,7 @@ And that's it for configuration. Simple, eh? 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.mkboilerplate.mk, + mk/boilerplate.mkboilerplate.mk, includes build.mk after config.mk.) @@ -1742,7 +1742,7 @@ GhcHcOpts=-DDEBUG -Rghc-timing YACC = @YaccCmd@ - This defines the Make variables 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 @@ -1760,7 +1760,7 @@ YACC = myyacc 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 + 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 @@ -1892,16 +1892,16 @@ $ emacs mk/build.mk Standard Targets - targets, standard makefile - makefile targets + targets, standard makefile + makefile targets In any directory you should be able to make the following: -boot: - +boot: + does the one-off preparation required to get ready for the real work. Notably, it does gmake depend in all directories that contain programs. It also builds the necessary tools @@ -1918,20 +1918,20 @@ subdirectories, in the order specified by If you're working in a subdirectory somewhere and need to update the dependencies, gmake boot is a good way to do it. - + -all: - +all: + makes all the final target(s) for this Makefile. Depending on which directory you are in a ``final target'' may be an executable program, a library archive, a shell script, or a Postscript file. Typing gmake alone is generally the same as typing gmake all. - + -install: - +install: + installs the things built by all (except for the documentation). Where does it install them? That is specified by @@ -1941,32 +1941,32 @@ install them? That is specified by --bindir=/home/simonpj/bin; see ./configure --help for the full details. - + -install-docs: - +install-docs: + installs the documentation. Otherwise behaves just like install. - + -uninstall: - +uninstall: + reverses the effect of install. - + -clean: - +clean: + 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 gmake boot. Also preserve files that could be made by building, but normally aren't because the distribution comes with them. - + distclean: @@ -1988,8 +1988,8 @@ few files that people normally don't want to recompile. -maintainer-clean: - +maintainer-clean: + Delete everything from the current directory that can be reconstructed with this Makefile. This typically includes everything deleted by @@ -2007,12 +2007,12 @@ build the program. -check: - +check: + run the test suite. - + @@ -2025,16 +2025,16 @@ sub-directories. Certain other standard targets do not: -configure: - +configure: + is only available in the root directory -$(FPTOOLS_TOP); it has been discussed in . +$(FPTOOLS_TOP); it has been discussed in . - + -depend: - +depend: + make a .depend file in each directory that needs it. This .depend file contains mechanically-generated dependency @@ -2056,24 +2056,24 @@ which says that the object file Foo.o depends on the interf Baz.hi generated by compiling module Baz. The .depend file is automatically included by every Makefile. - + -binary-dist: - +binary-dist: + make a binary distribution. This is the target we use to build the binary distributions of GHC and Happy. - + -dist: - +dist: + 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. - + @@ -2106,10 +2106,10 @@ Happy can similarly be run from the build tree, using -Fast Making <IndexTerm><Primary>fastmake</Primary></IndexTerm> -<IndexTerm><Primary>dependencies, omitting</Primary></IndexTerm> -<IndexTerm><Primary>FAST, makefile -variable</Primary></IndexTerm> +Fast Making <indexterm><primary>fastmake</primary></indexterm> +<indexterm><primary>dependencies, omitting</primary></indexterm> +<indexterm><primary>FAST, makefile +variable</primary></indexterm> Sometimes the dependencies get in the way: if you've made a small @@ -2147,7 +2147,7 @@ User's Guide section on "Separate Compilation"). The <filename>Makefile</filename> architecture -<IndexTerm><Primary>makefile architecture</Primary></IndexTerm> +makefile architecture make is great if everything works—you type gmake install and @@ -2162,19 +2162,40 @@ The purpose of this section is to give you a road-map to help you figure out what is going right and what is going wrong. + + Debugging + + Debugging Makefiles is something of a + black art, but here's a couple of tricks that we find + particularly useful. The following command allows you to see + the contents of any make variable in the context of the current + Makefile: + +$ make show VALUE=HS_SRCS + + where you can replace HS_SRCS with the + name of any variable you wish to see the value of. + + GNU make has a option which generates + a dump of the decision procedure used to arrive at a conclusion + about which files should be recompiled. Sometimes useful for + tracking down problems with superfluous or missing + recompilations. + + A small project To get started, let us look at the Makefile for an imaginary small fptools project, small. Each project in fptools has its own -directory in FPTOOLS_TOP, so the small project will have its own -directory FPOOLS_TOP/small/. Inside the small/ directory there +directory in FPTOOLS_TOP, so the small project will have its own +directory FPOOLS_TOP/small/. Inside the small/ directory there will be a Makefile, looking something like this: -Makefile, minimal +Makefile, minimal # Makefile for fptools project "small" @@ -2197,7 +2218,7 @@ This Makefile has three sections: - + The first section includes @@ -2213,15 +2234,15 @@ directive. a file of ``boilerplate'' code from the level above (which in this case will be -FPTOOLS_TOP/mk/boilerplate.mkboilerplate.mk). As its name +FPTOOLS_TOP/mk/boilerplate.mkboilerplate.mk). As its name suggests, boilerplate.mk consists of a large quantity of standard Makefile code. We discuss this boilerplate in more detail in . -include, directive in Makefiles -Makefile inclusion +include, directive in Makefiles +Makefile inclusion Before the include statement, you must define the make variable -TOPTOP to be the directory containing the mk directory in +TOPTOP to be the directory containing the mk directory in which the boilerplate.mk file is. It is not OK to simply say @@ -2235,41 +2256,41 @@ that it can, in turn, include other files. (Unfortunately, w included file does an include, the filename is treated relative to the directory in which gmake is being run, not the directory in which the included sits.) In general, every file foo.mk -assumes that $(TOP)/mk/foo.mk refers to itself. It is up to the +assumes that $(TOP)/mk/foo.mk refers to itself. It is up to the Makefile doing the include to ensure this is the case. Files intended for inclusion in other Makefiles are written to have the following property: after foo.mk is included, it leaves -TOP containing the same value as it had just before the include +TOP containing the same value as it had just before the include statement. In our example, this invariant guarantees that the include for target.mk will look in the same directory as that for boilerplate.mk. - - + + The second section defines the following standard make -variables: SRCSSRCS (the source files from which is to be -built), and HS_PROGHS_PROG (the executable binary to be +variables: SRCSSRCS (the source files from which is to be +built), and HS_PROGHS_PROG (the executable binary to be built). We will discuss in more detail what the ``standard variables'' are, and how they affect what happens, in . -The definition for SRCS uses the useful GNU make construct -$(wildcard $pat$)wildcard, which expands to a list of all +The definition for SRCS uses the useful GNU make construct +$(wildcard $pat$)wildcard, which expands to a list of all the files matching the pattern pat in the current directory. In -this example, SRCS is set to the list of all the .lhs and .c +this example, SRCS is set to the list of all the .lhs and .c files in the directory. (Let's suppose there is one of each, Foo.lhs and Baz.c.) - - + + The last section includes a second file of standard code, -called target.mktarget.mk. It contains the rules that tell +called target.mktarget.mk. It contains the rules that tell gmake how to make the standard targets (). Why, you ask, can't this standard code be part of boilerplate.mk? Good question. We discuss the reason later, in . @@ -2281,7 +2302,7 @@ in target.mk; the price tag is that you have to understand canned rules get enabled, and what they do (). - + @@ -2296,15 +2317,15 @@ happen: - + gmake figures out that the object files are Foo.o and Baz.o. - - + + It uses a boilerplate pattern rule to compile Foo.lhs to @@ -2312,27 +2333,27 @@ happen: build configuration.) - - + + It uses another standard pattern rule to compile Baz.c to Baz.o, using a C compiler. (Ditto.) - - + + It links the resulting .o files together to make small, using the Haskell compiler to do the link step. (Why not use ld? Because the Haskell compiler knows what standard libraries to link in. How did gmake know to use the Haskell compiler to do the link, -rather than the C compiler? Because we set the variable HS_PROG -rather than C_PROG.) +rather than the C compiler? Because we set the variable HS_PROG +rather than C_PROG.) - + @@ -2381,7 +2402,7 @@ $(FPTOOLS_TOP)/ghc/ The sub-directories docs, driver, compiler, and so on, each contains a sub-component of GHC, and each has its own Makefile. -There must also be a Makefile in $(FPTOOLS_TOP)/ghc. It does most +There must also be a Makefile in $(FPTOOLS_TOP)/ghc. It does most of its work by recursively invoking gmake on the Makefiles in the sub-directories. We say that ghc/Makefile is a non-leaf Makefile, because it does little except organise its children, @@ -2407,7 +2428,7 @@ contains GHC-specific Makefile boilerplate code. More prec - + ghc/mk/boilerplate.mk is included at the top of @@ -2417,8 +2438,8 @@ sub-directories. It in turn includes the main boilerplate fi - - + + ghc/mk/target.mk is included at the bottom of @@ -2426,7 +2447,7 @@ sub-directories. It in turn includes the main boilerplate fi sub-directories. It in turn includes the file mk/target.mk. - + @@ -2441,12 +2462,12 @@ of the standard boilerplate. Boilerplate architecture -<IndexTerm><Primary>boilerplate architecture</Primary></IndexTerm> +<indexterm><primary>boilerplate architecture</primary></indexterm> -Every Makefile includes a boilerplate.mkboilerplate.mk file -at the top, and target.mktarget.mk file at the bottom. In +Every Makefile includes a boilerplate.mkboilerplate.mk file +at the top, and target.mktarget.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: @@ -2454,30 +2475,30 @@ be two of them. In general: - + boilerplate.mk consists of: - + Definitions of millions of make variables that collectively specify the build configuration. Examples: -HC_OPTSHC_OPTS, the options to feed to the Haskell compiler; -NoFibSubDirsNoFibSubDirs, the sub-directories to enable within the -nofib project; GhcWithHcGhcWithHc, the name of the Haskell +HC_OPTSHC_OPTS, the options to feed to the Haskell compiler; +NoFibSubDirsNoFibSubDirs, the sub-directories to enable within the +nofib project; GhcWithHcGhcWithHc, 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. - + @@ -2497,11 +2518,11 @@ SRC_HC_OPTS += -O -thereby adding ``'' to the end of SRC_HC_OPTSSRC_HC_OPTS. +thereby adding ``'' to the end of SRC_HC_OPTSSRC_HC_OPTS. - - + + target.mk contains make rules for the standard @@ -2515,7 +2536,7 @@ variables are usually set in the middle section of the - + gmake commits target and dependency lists earlier than @@ -2529,8 +2550,8 @@ $(HS_PROG) : $(OBJS) -If this rule was in boilerplate.mk then $(HS_PROG)HS_PROG -and $(OBJS)OBJS would not have their final values at the +If this rule was in boilerplate.mk then $(HS_PROG)HS_PROG +and $(OBJS)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 @@ -2538,8 +2559,8 @@ 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 @@ -2548,19 +2569,19 @@ error message). Including ordinary rules in boilerplate.mk 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. - + - + @@ -2571,118 +2592,232 @@ matter too much. The main <filename>mk/boilerplate.mk</filename> file -<IndexTerm><Primary>boilerplate.mk</Primary></IndexTerm> +boilerplate.mk -If you look at $(FPTOOLS_TOP)/mk/boilerplate.mk you will find +If you look at $(FPTOOLS_TOP)/mk/boilerplate.mk you will find that it consists of the following sections, each held in a separate file: - - + - -config.mkconfig.mk - - -is the build configuration file we -discussed at length in . - - - -paths.mkpaths.mk - - -defines make variables for -pathnames and file lists. In particular, it gives definitions for: - + + config.mk + config.mk + + is the build configuration file we discussed at + length in . + + - - + + paths.mk + paths.mk + + defines make variables for + pathnames and file lists. This file contains code for + automatically compiling lists of source files and deriving + lists of object files from those. The results can be + overriden in the Makefile, but in + most cases the automatic setup should do the right + thing. + + The following variables may be set in the + Makefile to affect how the automatic + source file search is done: + + + + ALL_DIRS + ALL_DIRS + + + Set to a list of directories to search in + addition to the current directory for source + files. + + - -SRCSSRCS: - - -all source files in the current directory. - - - -HS_SRCSHS_SRCS: - - -all Haskell source files in the current directory. -It is derived from $(SRCS), so if you override SRCS with a new value -HS_SRCS will follow suit. - - - -C_SRCSC_SRCS: - - -similarly for C source files. - - - -HS_OBJSHS_OBJS: - - -the .o files derived from $(HS_SRCS). - - - -C_OBJSC_OBJS: - - -similarly for $(C_SRCS). - - - -OBJSOBJS: - - -the concatenation of $(HS_OBJS) and $(C_OBJS). - - - - + + EXCLUDE_SRCS + EXCLUDE_SRCS + + + Set to a list of source files (relative to the + current directory) to omit from the automatic + search. The source searching machinery is clever + enough to know that if you exclude a source file + from which other sources are derived, then the + derived sources should also be excluded. For + example, if you set EXCLUDED_SRCS + to include Foo.y, then + Foo.hs will also be + excluded. + + - -Any or all of these definitions can easily be overriden by giving new -definitions in your Makefile. For example, if there are things in -the current directory that look like source files but aren't, then -you'll need to set SRCS manually in your Makefile. The other -definitions will then work from this new definition. - + + EXTRA_SRCS + EXCLUDE_SRCS + + + Set to a list of extra source files (perhaps + in directories not listed in + ALL_DIRS) that should be + considered. + + + - -What, exactly, does paths.mk consider a ``source file'' to be? It's -based on the file's suffix (e.g. .hs, .lhs, .c, .lc, etc), but -this is the kind of detail that changes, so rather than -enumerate the source suffices here the best thing to do is to look in -paths.mk. - - - -opts.mkopts.mk - - -defines make variables for option -strings to pass to each program. For example, it defines -HC_OPTSHC_OPTS, the option strings to pass to the Haskell -compiler. See . - - - -suffix.mksuffix.mk - - -defines standard pattern rules—see . - - - - + The results of the automatic source file search are + placed in the following make variables: + + + + SRCS + SRCS + + All source files found, sorted and without + duplicates, including those which might not exist + yet but will be derived from other existing sources. + SRCS can be + overriden if necessary, in which case the variables + below will follow suit. + + + + + HS_SRCS + HS_SRCS + + all Haskell source files in the current + directory, including those derived from other source + files (eg. Happy sources also give rise to Haskell + sources). + + + + + HS_OBJS + HS_OBJS + + Object files derived from + HS_SRCS. + + + + + HS_IFACES + HS_IFACES + + Interface files (.hi files) + derived from HS_SRCS. + + + + + C_SRCS + C_SRCS + + All C source files found. + + + + + C_OBJS + C_OBJS + + Object files derived from + C_SRCS. + + + + + SCRIPT_SRCS + SCRIPT_SRCS + + All script source files found + (.lprl files). + + + + + SCRIPT_OBJS + SCRIPT_OBJS + + object files derived from + SCRIPT_SRCS + (.prl files). + + + + + HSC_SRCS + HSC_SRCS + + All hsc2hs source files + (.hsc files). + + + + + HAPPY_SRCS + HAPPY_SRCS + + All happy source files + (.y or .hy files). + + + + + OBJS + OBJS + + the concatenation of + $(HS_OBJS), + $(C_OBJS), and + $(SCRIPT_OBJS). + + + + + Any or all of these definitions can easily be + overriden by giving new definitions in your + Makefile. + + What, exactly, does paths.mk + consider a source file to be? It's based + on the file's suffix (e.g. .hs, + .lhs, .c, + .hy, etc), but this is the kind of + detail that changes, so rather than enumerate the source + suffices here the best thing to do is to look in + paths.mk. + + + + + opts.mk + opts.mk + + defines make variables for option + strings to pass to each program. For example, it defines + HC_OPTSHC_OPTS, + the option strings to pass to the Haskell compiler. See + . + + + + + suffix.mk + suffix.mk + + defines standard pattern rules—see . + + + Any of the variables and pattern rules defined by the boilerplate file @@ -2696,10 +2831,10 @@ directive simply override the default ones in boilerplate.mk Pattern rules and options -<IndexTerm><Primary>Pattern rules</Primary></IndexTerm> +Pattern rules -The file suffix.mksuffix.mk defines standard pattern +The file suffix.mksuffix.mk defines standard pattern rules that say how to build one kind of file from another, for example, how to build a .o file from a .c file. (GNU make's pattern rules are more powerful and easier to use than Unix @@ -2724,8 +2859,8 @@ Almost all the rules look something like this: Here's how to understand the rule. It says that something.o (say Foo.o) can be built from something.c (Foo.c), by invoking the C compiler -(path name held in $(CC)), passing to it the options -$(CC_OPTS) and the rule's dependent file of the rule +(path name held in $(CC)), passing to it the options +$(CC_OPTS) and the rule's dependent file of the rule $< (Foo.c in this case), and putting the result in the rule's target $@ (Foo.o in this case). @@ -2734,12 +2869,12 @@ the rule's target $@ (Foo.o in th Every program is held in a make variable defined in mk/config.mk—look in mk/config.mk for the complete list. One important one is the Haskell compiler, which is -called $(HC). +called $(HC). Every program's options are are held in a make variables called -<prog>_OPTS. the <prog>_OPTS variables are defined in +<prog>_OPTS. the <prog>_OPTS variables are defined in mk/opts.mk. Almost all of them are defined like this: @@ -2752,45 +2887,45 @@ CC_OPTS = $(SRC_CC_OPTS) $(WAY$(_way)_CC_OPTS) $($*_CC_OPTS) $(EXTRA_CC_OPTS) -The four variables from which CC_OPTS is built have the following meaning: +The four variables from which CC_OPTS is built have the following meaning: - -SRC_CC_OPTSSRC_CC_OPTS: - + +SRC_CC_OPTSSRC_CC_OPTS: + options passed to all C compilations. - - -WAY_<way>_CC_OPTS: - + + +WAY_<way>_CC_OPTS: + options passed to C compilations for way <way>. For example, -WAY_mp_CC_OPTS gives options to pass to the C compiler when -compiling way mp. The variable WAY_CC_OPTS holds +WAY_mp_CC_OPTS gives options to pass to the C compiler when +compiling way mp. The variable WAY_CC_OPTS holds options to pass to the C compiler when compiling the standard way. ( dicusses multi-way compilation.) - - -<module>_CC_OPTS: - + + +<module>_CC_OPTS: + options to -pass to the C compiler that are specific to module <module>. For example, SMap_CC_OPTS gives the specific options +pass to the C compiler that are specific to module <module>. For example, SMap_CC_OPTS gives the specific options to pass to the C compiler when compiling SMap.c. - - -EXTRA_CC_OPTSEXTRA_CC_OPTS: - + + +EXTRA_CC_OPTSEXTRA_CC_OPTS: + extra options to pass to all C compilations. This is intended for command line use, thus: @@ -2803,7 +2938,7 @@ gmake libHS.a EXTRA_CC_OPTS="-v" - + @@ -2812,7 +2947,7 @@ gmake libHS.a EXTRA_CC_OPTS="-v" The main <filename>mk/target.mk</filename> file -<IndexTerm><Primary>target.mk</Primary></IndexTerm> +target.mk target.mk contains canned rules for all the standard targets @@ -2830,75 +2965,75 @@ special cases yourself. - -HS_PROGHS_PROG. - + +HS_PROGHS_PROG. + -If HS_PROG is defined, you get +If HS_PROG is defined, you get rules with the following targets: - -HS_PROGHS_PROG - + +HS_PROGHS_PROG + -itself. This rule links $(OBJS) +itself. This rule links $(OBJS) with the Haskell runtime system to get an executable called -$(HS_PROG). +$(HS_PROG). - - -installinstall - + + +installinstall + -installs $(HS_PROG) -in $(bindir). +installs $(HS_PROG) +in $(bindir). - + - - -C_PROGC_PROG - + + +C_PROGC_PROG + -is similar to HS_PROG, except that -the link step links $(C_OBJS) with the C runtime system. +is similar to HS_PROG, except that +the link step links $(C_OBJS) with the C runtime system. - - -LIBRARYLIBRARY - + + +LIBRARYLIBRARY + -is similar to HS_PROG, except that -it links $(LIB_OBJS) to make the library archive $(LIBRARY), and -install installs it in $(libdir). +is similar to HS_PROG, except that +it links $(LIB_OBJS) to make the library archive $(LIBRARY), and +install installs it in $(libdir). - - -LIB_DATALIB_DATA - + + +LIB_DATALIB_DATA + … - - -LIB_EXECLIB_EXEC - + + +LIB_EXECLIB_EXEC + … - - -HS_SRCSHS_SRCS, C_SRCSC_SRCS. - + + +HS_SRCSHS_SRCS, C_SRCSC_SRCS. + -If HS_SRCS +If HS_SRCS is defined and non-empty, a rule for the target depend is included, which generates dependency information for Haskell programs. -Similarly for C_SRCS. +Similarly for C_SRCS. - + @@ -2919,7 +3054,7 @@ install :: $(HS_PROG) GNU make treats double-colon rules as separate entities. If there are several double-colon rules for the same target it takes each in turn and fires it if its dependencies say to do so. This means that -you can, for example, define both HS_PROG and LIBRARY, which will +you can, for example, define both HS_PROG and LIBRARY, which will generate two rules for install. When you type gmake install both rules will be fired, and both the program and the library will be installed, just as you wanted. @@ -2930,25 +3065,25 @@ installed, just as you wanted. Recursion -<IndexTerm><Primary>recursion, in makefiles</Primary></IndexTerm> -<IndexTerm><Primary>Makefile, recursing into subdirectories</Primary></IndexTerm> +recursion, in makefiles +Makefile, recursing into subdirectories -In leaf Makefiles the variable SUBDIRSSUBDIRS is undefined. -In non-leaf Makefiles, SUBDIRS is set to the list of +In leaf Makefiles the variable SUBDIRSSUBDIRS is undefined. +In non-leaf Makefiles, SUBDIRS is set to the list of sub-directories that contain subordinate Makefiles. It is up to -you to set SUBDIRS in the Makefile. There is no automation here—SUBDIRS is too important to automate. +you to set SUBDIRS in the Makefile. There is no automation here—SUBDIRS is too important to automate. -When SUBDIRS is defined, target.mk includes a rather +When SUBDIRS is defined, target.mk includes a rather neat rule for the standard targets ( that simply invokes make recursively in each of the sub-directories. These recursive invocations are guaranteed to occur in the order -in which the list of directories is specified in SUBDIRS. This +in which the list of directories is specified in SUBDIRS. This guarantee can be important. For example, when you say gmake boot it can be important that the recursive invocation of make boot is done in one sub-directory (the include files, say) before another (the @@ -2961,7 +3096,7 @@ first, and the most dependent last. Way management -<IndexTerm><Primary>way management</Primary></IndexTerm> +way management We sometimes want to build essentially the same system in several @@ -2975,7 +3110,7 @@ the build tree need to be constructed in multiple ways. -Instead, the target.mktarget.mk contains some clever magic to +Instead, the target.mktarget.mk contains some clever magic to allow you to build several versions of a system; and to control locally how many versions are built and how they differ. This section explains the magic. @@ -2993,47 +3128,47 @@ side of the dot, for boring reasons; thus, libHS_mp.a -A make variable called way holds the current way tag. way +A make variable called way holds the current way tag. way is only ever set on the command line of a recursive invocation of gmake. It is never set inside a Makefile. So it is a global constant for any one invocation of gmake. Two other make -variables, way_ and _way are immediately derived from $(way) and -never altered. If way is not set, then neither are way_ and -_way, and the invocation of make will build the ``normal way''. -If way is set, then the other two variables are set in sympathy. -For example, if $(way) is ``mp'', then way_ is set to ``mp_'' -and _way is set to ``_mp''. These three variables are then used +variables, way_ and _way are immediately derived from $(way) and +never altered. If way is not set, then neither are way_ and +_way, and the invocation of make will build the ``normal way''. +If way is set, then the other two variables are set in sympathy. +For example, if $(way) is ``mp'', then way_ is set to ``mp_'' +and _way is set to ``_mp''. These three variables are then used when constructing file names. -So how does make ever get recursively invoked with way set? There +So how does make ever get recursively invoked with way set? There are two ways in which this happens: - + For some (but not all) of the standard targets, when in a leaf sub-directory, make is recursively invoked for each way tag in -$(WAYS). You set WAYS to the list of way tags you want these +$(WAYS). You set WAYS to the list of way tags you want these targets built for. The mechanism here is very much like the recursive invocation of make in sub-directories (). -It is up to you to set WAYS in your Makefile; this is how you +It is up to you to set WAYS in your Makefile; this is how you control what ways will get built. - - + + For a useful collection of targets (such as libHS_mp.a, Foo.mp_o) there is a rule which recursively invokes make to make the specified target, setting the -way variable. So if you say gmake Foo.mp_o you should see a +way variable. So if you say gmake Foo.mp_o you should see a recursive invocation gmake Foo.mp_o way=mp, and in this recursive invocation the pattern rule for compiling a Haskell file into a .o file will match. The key pattern rules (in suffix.mk) @@ -3048,7 +3183,7 @@ look like this: Neat, eh? - + @@ -3063,7 +3198,7 @@ Neat, eh? Sometimes the canned rule just doesn't do the right thing. For example, in the nofib suite we want the link step to print out timing information. The thing to do here is not to define -HS_PROG or C_PROG, and instead define a special purpose rule in +HS_PROG or C_PROG, and instead define a special purpose rule in your own Makefile. By using different variable names you will avoid the canned rules being included, and conflicting with yours. @@ -3075,9 +3210,9 @@ the canned rules being included, and conflicting with yours. Booting/porting from C (<filename>.hc</filename>) files -<IndexTerm><Primary>building GHC from .hc files</Primary></IndexTerm> -<IndexTerm><Primary>booting GHC from .hc files</Primary></IndexTerm> -<IndexTerm><Primary>porting GHC</Primary></IndexTerm> +building GHC from .hc files +booting GHC from .hc files +porting GHC This section is for people trying to get GHC going by using the supplied @@ -3112,7 +3247,7 @@ command will execute the whole build process (it won't install yet): foo% distrib/hc-build --prefix=INSTALL_DIRECTORY ---hc-build +--hc-build By default, the installation directory is /usr/local. If that is what you want, you may omit the argument to @@ -3138,9 +3273,9 @@ the adventure…(ToDo: porting tips—stuff to look out for, etc.) Known pitfalls in building Glasgow Haskell -<IndexTerm><Primary>problems, building</Primary></IndexTerm> -<IndexTerm><Primary>pitfalls, in building</Primary></IndexTerm> -<IndexTerm><Primary>building pitfalls</Primary></IndexTerm> +problems, building +pitfalls, in building +building pitfalls WARNINGS about pitfalls and known ``problems'': @@ -3149,16 +3284,16 @@ WARNINGS about pitfalls and known ``problems'': - + One difficulty that comes up from time to time is running out of space in TMPDIR. (It is impossible for the configuration stuff to compensate for the vagaries of different sysadmin approaches to temp space.) -tmp, running out of space in +tmp, running out of space in -The quickest way around it is setenv TMPDIR /usr/tmpTMPDIR or +The quickest way around it is setenv TMPDIR /usr/tmpTMPDIR or even setenv TMPDIR . (or the equivalent incantation with your shell of choice). @@ -3174,8 +3309,8 @@ in all cases. - - + + In compiling some support-code bits, e.g., in ghc/rts/gmp and even @@ -3183,16 +3318,16 @@ in ghc/lib, you may get a few C-compiler warnings. We thin are OK. - - + + When compiling via C, you'll sometimes get ``warning: assignment from incompatible pointer type'' out of GCC. Harmless. - - + + Similarly, archiving warning messages like the following are not @@ -3206,8 +3341,8 @@ ar: filename GlaIOMonad__2_2s.o truncated to GlaIOMonad_ - - + + In compiling the compiler proper (in compiler/), you may @@ -3216,7 +3351,7 @@ vagaries of different systems, it seems. The solution is simple: - + If you're compiling with GHC 4.00 or later, then the @@ -3224,26 +3359,26 @@ vagaries of different systems, it seems. The solution is simple: is somewhat unlikely, since the maximum is set to 64M by default. Anyway, you can raise it with the flag (add this flag to -<module>_HC_OPTS +<module>_HC_OPTS make variable in the appropriate Makefile). - - + + For GHC < 4.00, add a suitable flag to the Makefile, as above. - + and try again: gmake. (see for information about -<module>_HC_OPTS.) +<module>_HC_OPTS.) Alternatively, just cut to the chase: @@ -3254,8 +3389,8 @@ Alternatively, just cut to the chase: - - + + If you try to compile some Haskell, and you get errors from GCC about @@ -3267,11 +3402,11 @@ this bug also suggests that you have an old GCC. - - + + -You may need to re-ranlibranlib your libraries (on Sun4s). +You may need to re-ranlibranlib your libraries (on Sun4s). @@ -3287,8 +3422,8 @@ We'd be interested to know if this is still necessary. - - + + GHC's sources go through cpp before being compiled, and cpp varies @@ -3314,7 +3449,7 @@ Alas, cpp doesn't tell you the offending file! Workaround: don't put weird things in string args to cpp macros. - + @@ -3345,7 +3480,7 @@ by typign mount). Before you start, you need to make sure that the user environment variable -MAKE_MODE is set to UNIX. If you +MAKE_MODE is set to UNIX. If you don't do this you get very weird messages when you type make, such as: @@ -3356,7 +3491,7 @@ don't do this you get very weird messages when you type - + Generate a key, by running c:/user/local/bin/ssh-keygen1. This generates a public key in .ssh/identity.pub, and a @@ -3387,9 +3522,9 @@ Generate a key, by running c:/user/local/bin/ssh-keygen1. c:\tmp> set CYGWIN32=tty c:\tmp> c:/user/local/bin/ssh-keygen1 - + - + If you don't have an account on cvs.haskell.org, send your .ssh/identity.pub to the CVS repository administrator @@ -3404,7 +3539,7 @@ If you don't have an account on cvs.haskell.org, send your ~/.ssh/authorized_keys. Make sure that the new version of authorized_keys still has 600 file permission. - + @@ -3415,50 +3550,50 @@ If you don't have an account on cvs.haskell.org, send - + From the System control panel, set the following user environment variables (see the GHC user guide) - + -HOME: points to your home directory. This is where CVS +HOME: points to your home directory. This is where CVS will look for its .cvsrc file. - + - + -CVS_RSH: c:/path_to_ghc/extra-bin/ssh +CVS_RSH: c:/path_to_ghc/extra-bin/ssh - + - + -CVSROOT: :ext:username@cvs.haskell.org:/home/cvs/root, +CVSROOT: :ext:username@cvs.haskell.org:/home/cvs/root, where username is your userid - + - + -CVSEDITOR: bin/gnuclient.exe if you want to use an Emacs buffer for typing in those long commit messages. +CVSEDITOR: bin/gnuclient.exe if you want to use an Emacs buffer for typing in those long commit messages. - + - + -SHELL: To use bash as the shell in Emacs, you need to +SHELL: To use bash as the shell in Emacs, you need to set this to point to bash.exe. - + - + - + Put the following in $HOME/.cvsrc: @@ -3483,9 +3618,9 @@ been lifted by now (i.e., you're using VFAT or later filesystems.) If you're still having problems creating it, don't worry; .cvsrc is entirely optional. - + - + Try doing cvs co fpconfig. All being well, bytes should start to trickle through, leaving a directory fptools @@ -3505,9 +3640,9 @@ for some reason bombed out. This was from a bash shell running in Emacs. I solved this by invoking a Cygnus shell, and running CVS from there. Once things are dialogue free, it seems to work OK from within Emacs. - + - + If you want to check out part of large tree, proceed as follows: @@ -3530,7 +3665,7 @@ in this case bogus. The cvs update command sucks in a named sub-directory. - + @@ -3548,7 +3683,7 @@ I have not tried it yet. - + You should give the option to @@ -3559,9 +3694,9 @@ I have not tried it yet. Cygwin gcc, or to explicitly specify . - + - + You have to run autoconf both in fptools and in fptools/ghc. If you omit the latter step you'll @@ -3577,15 +3712,15 @@ running /bin/sh ./configure --cache-file=.././config.cache --srcdir=. ./configure: ./configure: No such file or directory configure: error: ./configure failed for ghc - + - + -You need ghc to be in your PATH before you run +You need ghc to be in your PATH before you run configure. The InstallShield tells you the path when you install it. - + -- 1.7.10.4