README.md 3.07 KB
Newer Older
Ben Gamari's avatar
Ben Gamari committed
1
# ghc-utils
Ben Gamari's avatar
Ben Gamari committed
2
3
4
There are utilities that I find useful while working on GHC. It's quite a mixed
bag; a few are for performance analysis, some for general development, and
others for release management. Some are useful; all are hacky.
Ben Gamari's avatar
Ben Gamari committed
5

6
7
8
9
10
# Usage

You can build the scripts using `nix-build .` and enter into a shell where
the scripts are available using `nix-shell`.

Ben Gamari's avatar
Ben Gamari committed
11
12
13
14
15
## Day-to-day maintenance

 * `push`: A script which I use to look over and push upstream my local branches
 * `review-submodules`: A script for reviewing and optionally reverting
   submodule changes in a commit
Ben Gamari's avatar
Ben Gamari committed
16
17
 * `add-upstream-remotes.py`: A script which adds git remotes (named `upstream`)
   to all submodules pointing to the upstream repository.
Ben Gamari's avatar
Ben Gamari committed
18
19
20

## Development tools

Ben Gamari's avatar
Ben Gamari committed
21
22
 * `run-until-crash`: A tool to run a process until it crashes; useful for
   reproducing and collecting core dumps from hard-to-trigger crashers.
Ben Gamari's avatar
Ben Gamari committed
23
24
25
26
27
 * `make-ghc-tags.sh`: A script for generating emacs `TAGS` files for a GHC tree
   (e.g. `ghc-utils/make-ghc-tags.sh`)
 * `debug-ghc`: A script for running an in-place installation of GHC (e.g.
   `inplace/bin/ghc-stage2`) in `gdb`
 * `validate-all`: A script for validating a range of GHC commits.
Ben Gamari's avatar
Ben Gamari committed
28
29
 * `ghc-docker`: A convenient script for bringing up a Docker image from the
   gitlab.haskell.org Docker registry with configured GHC tree.
Ben Gamari's avatar
Ben Gamari committed
30
31
32

## Understanding performance

Ben Gamari's avatar
Ben Gamari committed
33
34
35
36
37
 * `ghc_perf.py`: A handy utility for collecting runtime and `perf` statistics
   from programs compiled by GHC (with the `-rtsopts` flag).
 * `rts_stats.py`: A handy utility for comparing statistics from the GHC
   runtime's `+RTS -t --machine-readable` output (which requires that the
   program have been built with GHC's `-rtsopts` flag)
Ben Gamari's avatar
Ben Gamari committed
38
39
40
41
42
43
 * `split-core2core.py`: An extremely useful script for splitting up the output
   of GHC's `-dverbose-core2core` dump option, placing the output of each pass
   in a separate file (e.g. `ghc-utils/split-core2core.py
   my-program.verbose-core2core`)
 * `compare-ticks/`: A hack for comparing reports from GHC's ticky-ticky
   profiler.
Ben Gamari's avatar
Ben Gamari committed
44
45
 * `eventlog-sort`: A hack to dump the events from a GHC eventlog with relative
   timestamps (in milliseconds).
Ben Gamari's avatar
Ben Gamari committed
46
 * `ghc_timings.py`: A small hack to turn `-ddump-timings` output into a Markdown table.
Ben Gamari's avatar
Ben Gamari committed
47

Ben Gamari's avatar
Ben Gamari committed
48
49
50
51
52
53
54
55
56
57
58
59
60

## Release engineering

 * `rel-eng`:
   * `source-release.sh`: The script that I use to build source distribution
     tarballs.
   * `bin-release.sh`: The script that I use to build binary distributions.
   * `upload.sh`: The script that I use to collect, hash, sign, and upload
     documentation and distribution tarballs.
   * `mkchroot-debian.sh`: A script for preparing clean Debian container
     environments for GHC building with `systemd-nspawn`.
   * `download`
     * `process.py`: The script that I use to generate GHC download pages
Ben Gamari's avatar
Ben Gamari committed
61
   * `update-autoconf.sh`: Update the autoconf sources in the GHC source tree
Ben Gamari's avatar
Ben Gamari committed
62
63
64
 * `library-versions`: A set of scripts used to generate the
   `Commentary/Libraries/VersionHistory` page on the GHC Wiki. See
   `library-versions/README.mkd`.
Ben Gamari's avatar
Ben Gamari committed
65
66
67
68
69

## Other

 * `new-contribs.hs`: A tool I use to generate new-contributor statistics for
   GHC community status updates.