Changes between Version 1 and Version 2 of Building/Modifying


Ignore:
Timestamp:
Mar 31, 2009 8:24:15 AM (5 years ago)
Author:
simonmar
Comment:

add scenarios

Legend:

Unmodified
Added
Removed
Modified
  • Building/Modifying

    v1 v2  
    55This section covers making changes to the GHC build system.  We'll give some general advice on how to work with the build system, and then describe a few common scenarios, such as how to add a new source file. 
    66 
    7 Note that before making any non-trivial changes to the build system you should acquaint yourself with the overall [wiki:Building/Architecture architecture].  Even if you're already familiar with GNU make, the GHC build system is probably quite different from most `Makefile`-based build systems you've seen before.   
     7Note that before making any non-trivial changes to the build system you should acquaint yourself with the overall [wiki:Building/Architecture architecture].  Even if you're already familiar with GNU make, the GHC build system is probably quite different from most `Makefile`-based build systems you've encountered before.   
    88 
    99Incedentally, it's a good idea to have a copy of the  
     
    4545 `make show VALUE=VAR`:: 
    4646  prints the value of variable `VAR`.  Useful for quick diagnosis. 
     47 
     48== Scenarios == 
     49 
     50The following are a collection of common changes you might want to make to the build system, with the exact steps required in each case. 
     51 
     52=== Adding a source file to GHC === 
     53 
     54GHC is in two parts:  
     55 
     56  * the `ghc` package, which comprises most of the GHC source code, can be found in the `compiler` directory.   
     57  * the `ghc` program itself, consists of a single `Main` module that imports the `ghc` package.  It is found in the `ghc` directory. 
     58 
     59Like any Cabal package, the `ghc` package has a `ghc.cabal` file, except that in this case the file is preprocessed by `configure` from the original: [[GhcFile(compiler/ghc.cabal.in)]].  Be careful not to modify the preprocessed version, `ghc.cabal`, as it will be overwritten next time you run `configure`. 
     60 
     61To add a module to the `ghc` package: 
     62 
     63 * Add your module to the `exposed-modules` section of [[GhcFile(compiler/ghc.cabal.in)]] 
     64 * {{{cd compiler; make stage2}}} 
     65 
     66=== Adding a source file to the RTS === 
     67 
     68The RTS picks up source files automatically, using '''make''''s `$(wildcard)` function.  So to add files to the RTS, just put your source file in `rts`, and 
     69 
     70{{{ 
     71$ cd rts; make 
     72}}} 
     73 
     74To have the change propagated to the stage 2 compiler, either go and make stage 2 explicitly, or issue a top-level `make`. 
     75 
     76=== Adding a new package === 
     77 
     78Adding a new package is quite straightforward: 
     79 
     80 * To arrange that the package is checked out by `darcs-all`, add an entry to the [[GhcFile(packages)]] file. 
     81 * run `sh boot` to generate the `ghc.mk` and `GNUmakefile` files in your package's build. 
     82 * Add an entry to the `PACKAGES` variable in [[GhcFile(ghc.mk)]].  The list in `PACKAGES` is kept in dependency order: each package must appear after the packages it depends on. 
     83 
     84That's it: doing a top-level `make` should now build your package and bring everything else up to date. 
     85 
     86=== Adding a program === 
     87 
     88Utility programs live in `utils`, for example `utils/hpc`.  Each program has a simple `ghc.mk` file, for example the one for `hpc` looks like this: 
     89 
     90{{{ 
     91utils/hpc_dist_MODULES = Main HpcCombine HpcDraft HpcFlags HpcLexer HpcMap \ 
     92                         HpcMarkup HpcOverlay HpcParser HpcReport HpcSet \ 
     93                         HpcShowTix HpcUtils 
     94utils/hpc_dist_HC_OPTS = -cpp -package hpc 
     95utils/hpc_dist_INSTALL = YES 
     96utils/hpc_dist_PROG    = hpc$(exeext) 
     97$(eval $(call build-prog,utils/hpc,dist,1)) 
     98$(eval $(call bindist,utils/hpc,ghc.mk)) 
     99}}} 
     100 
     101This is all that is necessary to build and install a program.  Taking each of these lines in turn: 
     102 
     103{{{ 
     104utils/hpc_dist_MODULES = Main HpcCombine HpcDraft HpcFlags HpcLexer HpcMap \ 
     105                         HpcMarkup HpcOverlay HpcParser HpcReport HpcSet \ 
     106                         HpcShowTix HpcUtils 
     107}}} 
     108 
     109remember that variable names all begin with ''directory''_''distdir'' (see [wiki:Building/Architecture#Idiom:variablenames Idiom: variable names]), and in this case the directory is `utils/hpc`, and the distdir is just `dist`.  The variable `utils/hpc_dist_MODULES` specifies the list of Haskell modules that make up the `hpc` program. 
     110 
     111{{{ 
     112utils/hpc_dist_HC_OPTS = -cpp -package hpc 
     113}}} 
     114 
     115This defines any extra options that need to be passed to GHC when compiling `hpc`. 
     116 
     117{{{ 
     118utils/hpc_dist_INSTALL = YES 
     119}}} 
     120 
     121This line indicates that we want the `hpc` program to be installed by `make install`.  The default is not to install programs. 
     122 
     123{{{ 
     124utils/hpc_dist_PROG    = hpc$(exeext) 
     125}}} 
     126 
     127This specifies the name of the program.  The variable `$(exeext)` contains `.exe` on Windows, and is otherwise empty. 
     128 
     129{{{ 
     130$(eval $(call build-prog,utils/hpc,dist,1)) 
     131}}} 
     132 
     133This is a call to the `build-prog` macro, whose definition can be found in [[GhcFile(rules/build-prog.mk)]].  This expands to the code for actually building the program, and it takes three arguments: the directory, the distdir, and the GHC stage to use for building (in this case we're using stage 1).  The `build-prog` macro expects to find certain variables defined, namely ''directory''_''distdir''`_PROG`, and ''directory''_''distdir''`_MODULES`. 
     134 
     135Finally, for programs that we want to install, we need to include the `ghc.mk` file in a binary distribution: 
     136 
     137{{{ 
     138$(eval $(call bindist,utils/hpc,ghc.mk)) 
     139}}}