HACKING.md

   1 Contributing to the Glasgow Haskell Compiler
   2 ============================================
   3
   4 So you've decided to hack on GHC, congratulations! We hope you have a
   5 rewarding experience. This file will point you in the direction of
   6 information to help you get started right away.
   7
   8 The GHC Developer's Wiki
   9 ========================
  10
  11 The home for GHC hackers is our Trac instance, located here:
  12
  13 <http://ghc.haskell.org/trac/ghc>
  14
  15 From here, you can file bugs (or look them up,) use the wiki, view the
  16 `git` history, among other things. Of particular note is the building
  17 page, which has the high level overview of the build process and how
  18 to get the source:
  19
  20 <http://ghc.haskell.org/trac/ghc/wiki/Building>
  21
  22 Contributing patches to GHC in a hurry
  23 ======================================
  24
  25 Make sure your system has the necessary tools to compile GHC. You can
  26 find an overview here:
  27
  28 <http://ghc.haskell.org/trac/ghc/wiki/Building/Preparation>
  29
  30 Next, clone the repository and all the associated libraries:
  31
  32 ```
  33 $ git clone --recursive git://git.haskell.org/ghc.git
  34 ```
  35
  36 On Windows, you need an extra repository containing some build tools.
  37 These can be downloaded for you by configure. This only needs to be done once by running:
  38
  39 ```
  40 $ ./configure --enable-tarballs-autodownload
  41 ```
  42
  43 First copy `mk/build.mk.sample` to `mk/build.mk` and ensure it has
  44 your preferred build settings. (You probably want to at least set
  45 `BuildFlavour` to `quick`):
  46
  47 ```
  48 $ cp mk/build.mk.sample mk/build.mk
  49 $ ... double-check mk/build.mk ...
  50 ```
  51
  52 Now build. The convenient `validate` script will build the tree in a way which
  53 is both quick to build and consistent with our testsuite,
  54
  55 ```
  56 $ ./validate --build-only
  57 ```
  58
  59 You can use the `./inplace/bin/ghc-stage2` binary to play with the
  60 newly built compiler.
  61
  62 Now, hack on your copy and rebuild (with `make`) as necessary.
  63
  64 Then start by making your commits however you want. When you're done, you can submit
  65  a pull request on Github for small changes. For larger changes the patch needs to be
  66  submitted to [Phabricator](https://phabricator.haskell.org/) for code review.
  67  The GHC Trac Wiki has a good summary for the [overall process](https://ghc.haskell.org/trac/ghc/wiki/WorkingConventions/FixingBugs)
  68  as well as a guide on
  69  [how to use Phabricator/arcanist](https://ghc.haskell.org/trac/ghc/wiki/Phabricator).
  70
  71
  72 Useful links:
  73 =============
  74
  75 An overview of things like using git, the release process, filing bugs
  76 and more can be located here:
  77
  78 <http://ghc.haskell.org/trac/ghc/wiki/WorkingConventions>
  79
  80 You can find our coding conventions for the compiler and RTS here:
  81
  82 <http://ghc.haskell.org/trac/ghc/wiki/Commentary/CodingStyle>
  83 <http://ghc.haskell.org/trac/ghc/wiki/Commentary/Rts/Conventions>
  84
  85 A high level overview of the bug tracker:
  86
  87 <http://ghc.haskell.org/trac/ghc/wiki/WorkingConventions/BugTracker>
  88
  89 If you're going to contribute regularly, **learning how to use the
  90 build system is important** and will save you lots of time. You should
  91 read over this page carefully:
  92
  93 <http://ghc.haskell.org/trac/ghc/wiki/Building/Using>
  94
  95 How to communicate with us
  96 ==========================
  97
  98 GHC is a big project, so you'll surely need help. Luckily, we can
  99 provide plenty through a variety of means!
 100
 101 ## IRC
 102
 103 If you're an IRC user, be sure to drop by the official `#ghc` channel
 104 on [freenode](http://freenode.org). Many (but not all) of the
 105 developers and committers are actively there during a variety of
 106 hours.
 107
 108 ## Mailing lists
 109
 110 In the event IRC does not work or if you'd like a bigger audience, GHC
 111 has several mailing lists for this purpose. The most important one is
 112 [ghc-devs](http://www.haskell.org/pipermail/ghc-devs/), which is where
 113 the developers actively hang out and discuss incoming changes and
 114 problems.
 115
 116 There is no strict standard about where you post patches - either in
 117 `ghc-devs` or in the bug tracker. Ideally, please put it in the bug
 118 tracker with test cases or relevant information in a ticket, and set
 119 the ticket status to `patch`. By doing this, we'll see the patch
 120 quickly and be able to review. This will also ensure it doesn't get
 121 lost. But if the change is small and self contained, feel free to
 122 attach it to your email, and send it to `ghc-devs`.
 123
 124 Furthermore, if you're a developer (or want to become one!) you're
 125 undoubtedly also interested in the other mailing lists:
 126
 127  * [glasgow-haskell-users](http://www.haskell.org/mailman/listinfo/glasgow-haskell-users)
 128    is where developers/users meet.
 129  * [ghc-tickets](http://www.haskell.org/mailman/listinfo/ghc-tickets)
 130    for email from Trac.
 131  * [ghc-builds](http://www.haskell.org/mailman/listinfo/ghc-builds)
 132    for nightly build emails.
 133  * [ghc-commits](http://www.haskell.org/mailman/listinfo/ghc-commits)
 134    for commit messages when someone pushes to the repository.
 135
 136 El fin
 137 ======
 138
 139 Happy Hacking!  -- The GHC Team