Changes between Version 22 and Version 23 of Building/Using


Ignore:
Timestamp:
Apr 1, 2009 9:31:22 AM (6 years ago)
Author:
simonmar
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • Building/Using

    v22 v23  
    402402if all you wanted to do was to test a small change to GHC. 
    403403 
    404 === Just building a single component === 
     404=== Rebuilding the GHC binary after making changes === 
    405405 
    406406Suppose you want to make a small change to GHC itself and test it. 
     
    410410{{{ 
    411411$ cd ghc 
    412 $ make stage2 
    413 }}} 
    414  
    415 This will bring the stage2 compiler up to date only.  In particular, 
    416 it will ignore the fact that by modifying GHC you have thereby made 
    417 the stage 1 compiler out of date, and hence possibly all the libraries 
    418 and the whole of stage 2 are now also out of date.  If you did `make` 
     412$ make stage=2 
     413}}} 
     414 
     415This will bring the stage 2 compiler up to date only.  Setting `stage=2` has the effect of disabling all the 
     416rules that build the stage 1 compiler, so the build system will ignore the fact that the stage 1 compiler is also out of date, and hence all the libraries are also potentially out of date.  If you did `make` 
    419417from the top-level, all of these dependencies would be taken into 
    420 account, and a lot of rebuilding would probably ensue. 
     418account, and a lot of rebuilding would probably ensue.  There's another target 
     419that takes an even quicker shortcut: 
     420 
     421{{{ 
     422$ cd ghc 
     423$ make 2 
     424}}} 
     425 
     426This is like `make stage=2`, except that it omits the dependency-building phase.  If you have changed the imports in any modules, those new dependencies will not be taken into account by the build system, so you might get a build failure.  On the other hand, this shortcut usually works and the few seconds it saves can make GHC development a much more interactive experience.  There are also `make 1` and `make 3` targets to make the stage 1 and stage 3 compilers respectively.  These targets work in both the `ghc` and `compiler` subdirectories. 
     427 
     428=== Building a single component in general === 
    421429 
    422430Each subdirectory of the source tree has a 
     
    440448 
    441449{{{ 
    442 $ (cd ..; make all_rts) 
    443 }}} 
    444  
    445 where `make all_rts` makes every target in the `rts` subdirectory. 
     450$ make -C .. all_rts 
     451}}} 
     452 
     453where "`-C ..`" tells make to invoke the `Makefile` in the directory "`..`", and `all_rts` is the target that makes everything in the `rts` subdirectory. 
    446454Equivalently, `make all_libraries/base` at the top level would build 
    447455everything in the `libraries/base` subdirectory.  To understand how 
     
    453461command at the top of the tree of the form `make clean_libraries/base`. 
    454462 
    455 The `stage2` target in the `ghc` directory does something else: it 
    456 also disables the dependencies that would otherwise cause the stage 1 
    457 compiler and the libraries to be rebuilt.  It does this by simply 
    458 setting `ASSUME_STAGE1=YES` and `ASSUME_LIBRARIES=YES` when invoking 
    459 the top-level `make`. 
     463== Building a single file == 
     464 
     465It's possible to tell make to build a single file, from any subdirectory in the tree.  For example, suppose I want to build just the module `Control.Monad` in the `base` package, I can do it like this: 
     466 
     467{{{ 
     468$ make libraries/base/dist-install/build/Control/Monad.o 
     469}}} 
     470 
     471(you have to know that `dist-install` is the distdir for a package, and object files are put in the subdirectory `build`).  It's also possible to do this from the `libraries/base` subdirectory: 
     472 
     473{{{ 
     474$ cd libraries/base 
     475$ make dist-install/build/Control/Monad.o 
     476}}} 
     477 
     478suppose you wanted to build this module with a few extra flags, perhaps because you want to see what GHC's optimiser is doing on this module: 
     479 
     480{{{ 
     481$ rm dist-install/build/Control/Monad.o 
     482$ make dist-install/build/Control/Monad.o EXTRA_HC_OPTS=-dcore-lint 
     483}}} 
     484 
     485you could also cut-and-paste the command-line to add flags, but sometimes the `EXTRA_HC_OPTS` method is more convenient. 
    460486 
    461487== Standard Targets == 
    462488 
    463 The main targets understood by the top-level `Makefile` are as 
    464 follows: 
     489The following targets work both at the top level, and in any subdirectory of the tree.  When used in a subdirectory, they apply only to the components of the system in that directory. 
    465490 
    466491 `all`:: 
    467   (default target, can be omitted).  Builds everything that needs to 
     492  (default target, can be omitted).  Builds all the targets for this 
     493  directory.  At the top level, builds everything that needs to 
    468494  be built for a GHC installation, including the stage 2 GHC, all 
    469495  libraries and documentation.  After `make`, `make install` will not 
    470496  need to do any further rebuilding. 
     497 
     498 `clean`:: 
     499  Delete all files from the current directory that are normally 
     500  created by `make`.  Don't delete the files that record the 
     501  configuration. 
     502 
     503To see how these targets are defined: [wiki:Building/Architecture/Idiom/StandardTargets]. 
     504 
     505The following targets are accepted only by the top-level `Makefile`: 
    471506 
    472507 `install`:: 
     
    474509  the places you specified when running `configure`, principally set 
    475510  by the `--prefix` flag; see [wiki:Building/Installing]. 
    476  
    477  `clean`:: 
    478   Delete all files from the current directory that are normally 
    479   created by `make`.  Don't delete the files that record the 
    480   configuration. 
    481511 
    482512 `distclean`:: 
     
    503533  `Happy`, or `Alex` in order to build it.  Hence `make sdist` only 
    504534  works in a completely built tree. 
    505  
    506 To see how these targets are defined: [wiki:Building/Architecture/Idiom/StandardTargets].