... | ... | @@ -4,7 +4,7 @@ |
|
|
This 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.
|
|
|
|
|
|
|
|
|
Note that before making any non-trivial changes to the build system you should acquaint yourself with the overall [architecture](building/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.
|
|
|
Note that before making any non-trivial changes to the build system you should acquaint yourself with the overall [architecture](building/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.
|
|
|
|
|
|
|
|
|
Incedentally, it's a good idea to have a copy of the
|
... | ... | @@ -56,3 +56,112 @@ out the parameters for a particular macro call. |
|
|
<td>
|
|
|
prints the value of variable `VAR`. Useful for quick diagnosis.
|
|
|
</td></tr></table>
|
|
|
|
|
|
## Scenarios
|
|
|
|
|
|
|
|
|
The following are a collection of common changes you might want to make to the build system, with the exact steps required in each case.
|
|
|
|
|
|
### Adding a source file to GHC
|
|
|
|
|
|
|
|
|
GHC is in two parts:
|
|
|
|
|
|
- the `ghc` package, which comprises most of the GHC source code, can be found in the `compiler` directory.
|
|
|
- the `ghc` program itself, consists of a single `Main` module that imports the `ghc` package. It is found in the `ghc` directory.
|
|
|
|
|
|
|
|
|
Like 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: [compiler/ghc.cabal.in](/trac/ghc/browser/ghc/compiler/ghc.cabal.in). Be careful not to modify the preprocessed version, `ghc.cabal`, as it will be overwritten next time you run `configure`.
|
|
|
|
|
|
|
|
|
To add a module to the `ghc` package:
|
|
|
|
|
|
- Add your module to the `exposed-modules` section of [compiler/ghc.cabal.in](/trac/ghc/browser/ghc/compiler/ghc.cabal.in)
|
|
|
- `cd compiler; make stage2`
|
|
|
|
|
|
### Adding a source file to the RTS
|
|
|
|
|
|
|
|
|
The 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
|
|
|
|
|
|
```wiki
|
|
|
$ cd rts; make
|
|
|
```
|
|
|
|
|
|
|
|
|
To have the change propagated to the stage 2 compiler, either go and make stage 2 explicitly, or issue a top-level `make`.
|
|
|
|
|
|
### Adding a new package
|
|
|
|
|
|
|
|
|
Adding a new package is quite straightforward:
|
|
|
|
|
|
- To arrange that the package is checked out by `darcs-all`, add an entry to the [packages](/trac/ghc/browser/ghc/packages) file.
|
|
|
- run `sh boot` to generate the `ghc.mk` and `GNUmakefile` files in your package's build.
|
|
|
- Add an entry to the `PACKAGES` variable in [ghc.mk](/trac/ghc/browser/ghc/ghc.mk). The list in `PACKAGES` is kept in dependency order: each package must appear after the packages it depends on.
|
|
|
|
|
|
|
|
|
That's it: doing a top-level `make` should now build your package and bring everything else up to date.
|
|
|
|
|
|
### Adding a program
|
|
|
|
|
|
|
|
|
Utility 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:
|
|
|
|
|
|
```wiki
|
|
|
utils/hpc_dist_MODULES = Main HpcCombine HpcDraft HpcFlags HpcLexer HpcMap \
|
|
|
HpcMarkup HpcOverlay HpcParser HpcReport HpcSet \
|
|
|
HpcShowTix HpcUtils
|
|
|
utils/hpc_dist_HC_OPTS = -cpp -package hpc
|
|
|
utils/hpc_dist_INSTALL = YES
|
|
|
utils/hpc_dist_PROG = hpc$(exeext)
|
|
|
$(eval $(call build-prog,utils/hpc,dist,1))
|
|
|
$(eval $(call bindist,utils/hpc,ghc.mk))
|
|
|
```
|
|
|
|
|
|
|
|
|
This is all that is necessary to build and install a program. Taking each of these lines in turn:
|
|
|
|
|
|
```wiki
|
|
|
utils/hpc_dist_MODULES = Main HpcCombine HpcDraft HpcFlags HpcLexer HpcMap \
|
|
|
HpcMarkup HpcOverlay HpcParser HpcReport HpcSet \
|
|
|
HpcShowTix HpcUtils
|
|
|
```
|
|
|
|
|
|
|
|
|
remember that variable names all begin with *directory*_*distdir* (see [Idiom: variable names](building/architecture#)), 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.
|
|
|
|
|
|
```wiki
|
|
|
utils/hpc_dist_HC_OPTS = -cpp -package hpc
|
|
|
```
|
|
|
|
|
|
|
|
|
This defines any extra options that need to be passed to GHC when compiling `hpc`.
|
|
|
|
|
|
```wiki
|
|
|
utils/hpc_dist_INSTALL = YES
|
|
|
```
|
|
|
|
|
|
|
|
|
This line indicates that we want the `hpc` program to be installed by `make install`. The default is not to install programs.
|
|
|
|
|
|
```wiki
|
|
|
utils/hpc_dist_PROG = hpc$(exeext)
|
|
|
```
|
|
|
|
|
|
|
|
|
This specifies the name of the program. The variable `$(exeext)` contains `.exe` on Windows, and is otherwise empty.
|
|
|
|
|
|
```wiki
|
|
|
$(eval $(call build-prog,utils/hpc,dist,1))
|
|
|
```
|
|
|
|
|
|
|
|
|
This is a call to the `build-prog` macro, whose definition can be found in [rules/build-prog.mk](/trac/ghc/browser/ghc/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`.
|
|
|
|
|
|
|
|
|
Finally, for programs that we want to install, we need to include the `ghc.mk` file in a binary distribution:
|
|
|
|
|
|
```wiki
|
|
|
$(eval $(call bindist,utils/hpc,ghc.mk))
|
|
|
``` |
|
|
\ No newline at end of file |