[[project @ 2002-02-26 12:15:11 by simonmar] simonmar**20020226121511 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. ] { hunk ./docs/building/building.sgml 3166 - -Way management + <sect2 id="sec-ways"> + <title>Way management + way management hunk ./docs/building/building.sgml 3170 -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. hunk ./docs/building/building.sgml 3180 - -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: - + 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. hunk ./docs/building/building.sgml 3187 - + 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. hunk ./docs/building/building.sgml 3201 - - + 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. hunk ./docs/building/building.sgml 3226 - - 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. - - - + So how does make ever get recursively + invoked with way set? There are two ways + in which this happens: hunk ./docs/building/building.sgml 3230 - - 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. + hunk ./docs/building/building.sgml 3247 + + 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: hunk ./docs/building/building.sgml 3266 + Neat, eh? + hunk ./docs/building/building.sgml 3269 -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. hunk ./docs/building/building.sgml 3275 - + +$ make way=p + hunk ./docs/building/building.sgml 3279 - + will build files for the profiling way only in the current + directory. + + hunk ./docs/building/building.sgml 3648 + }