From: simonmar Date: Tue, 26 Feb 2002 12:15:11 +0000 (+0000) Subject: [project @ 2002-02-26 12:15:11 by simonmar] X-Git-Tag: Approx_11550_changesets_converted~2351 X-Git-Url: http://git.megacz.com/?a=commitdiff_plain;h=93bd5753cc7b571367e86715d6b6b9d45eea2b2e;p=ghc-hetmet.git [project @ 2002-02-26 12:15:11 by simonmar] Mention that you can say 'make way=foo' to build a particular way only in the current directory. Clean up some markup, and fix a markup error at the same time. --- diff --git a/docs/building/building.sgml b/docs/building/building.sgml index 62b3a38..3bcb9f3 100644 --- a/docs/building/building.sgml +++ b/docs/building/building.sgml @@ -3163,101 +3163,123 @@ first, and the most dependent last. - -Way management + <sect2 id="sec-ways"> + <title>Way management + way management + + We sometimes want to build essentially the same system in + several different ``ways''. For example, we want to build GHC's + Prelude libraries with and without profiling, + so that there is an appropriately-built library archive to link + with when the user compiles his program. It would be possible + to have a completely separate build tree for each such ``way'', + but it would be horribly bureaucratic, especially since often + only parts of the build tree need to be constructed in multiple + ways. + + 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. + + The files for a particular way are distinguished by + munging the suffix. The normal way is always + built, and its files have the standard suffices + .o, .hi, and so on. + In addition, you can build one or more extra ways, each + distinguished by a way tag. The object + files and interface files for one of these extra ways are + distinguished by their suffix. For example, way + mp has files + .mp_o and + .mp_hi. Library archives have their + way tag the other side of the dot, for boring reasons; thus, + libHS_mp.a. + + A make variable called + way holds the current way tag. + way is only ever set on the + command line of gmake (usually in + a recursive invocation of gmake by the + system). 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 when constructing file names. + + So how does make ever get recursively + invoked with way set? There are two ways + in which this happens: -way management - - -We sometimes want to build essentially the same system in several -different ``ways''. For example, we want to build GHC's Prelude -libraries with and without profiling, with and without concurrency, -and so on, so that there is an appropriately-built library archive to -link with when the user compiles his program. It would be possible to -have a completely separate build tree for each such ``way'', but it -would be horribly bureaucratic, especially since often only parts of -the build tree need to be constructed in multiple ways. - - - -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. - - - -The files for a particular way are distinguished by munging the -suffix. The ``normal way'' is always built, and its files have the -standard suffices .o, .hi, and so on. In addition, you can build -one or more extra ways, each distinguished by a way tag. The -object files and interface files for one of these extra ways are -distinguished by their suffix. For example, way mp has files -.mp_o and .mp_hi. Library archives have their way tag the other -side of the dot, for boring reasons; thus, libHS_mp.a. - - - -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 -when constructing file names. - - - -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 -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 -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 -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) -look like this: + + + 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 in the + Makefile 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 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 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) look like this: %.$(way_)o : %.lhs $(HC) $(HC_OPTS) $< -o $@ + Neat, eh? + -Neat, eh? - - + + You can invoke make with a + particular way setting yourself, in order + to build files related to a particular + way in the current directory. eg. - + +$ make way=p + - + will build files for the profiling way only in the current + directory. + + @@ -3623,6 +3645,7 @@ running /bin/sh ./configure --cache-file=.././config.cache --srcdir=. ./configure: ./configure: No such file or directory configure: error: ./configure failed for ghc +