Fix --enable-unregistered by declaring missing RTS functions (#8748)
[ghc.git] / 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 http://git.haskell.org/ghc.git
34 $ cd ghc
35 $ ./sync-all get
36 ```
37
38 First copy `mk/build.mk.sample` to `mk/build.mk` and ensure it has
39 your preferred build settings. (You probably want to at least set
40 `BuildFlavour` to `quick`):
41
42 ```
43 $ cp mk/build.mk.sample mk/build.mk
44 $ ... double-check mk/build.mk ...
45 ```
46
47 Now build. If you have multiple cores, **you should always use them to
48 speed up compilation**:
49
50 ```
51 $ ./boot
52 $ ./configure
53 $ make -jN # <N> is the number of cores you have.
54 ```
55
56 You can use the `./inplace/bin/ghc-stage2` binary to play with the
57 newly built compiler.
58
59 Now, hack on your copy and rebuild (with `make`) as necessary.
60
61 Then start by making your commits however you want. When you're done, you
62 can use `git format-patch` to create a series of `.patch` files you
63 can give to us. In this example, we'll assume I'm on a `bugfix` branch
64 and want to submit my patches:
65
66 ```
67 $ git branch
68 * bugfix
69   master
70 $ git format-patch master -o patches
71 ...
72 $
73 ```
74
75 Now create a trac ticket:
76
77 <http://ghc.haskell.org/trac/ghc/newticket?type=bug>
78
79 And attach the files in your `patches/` directory. Set the status from
80 *new* to *patch* and we'll review it as soon as we can!
81
82 Useful links:
83 =============
84
85 An overview of things like using git, the release process, filing bugs
86 and more can be located here:
87
88 <http://ghc.haskell.org/trac/ghc/wiki/WorkingConventions>
89
90 You can find our coding conventions for the compiler and RTS here:
91
92 <http://ghc.haskell.org/trac/ghc/wiki/Commentary/CodingStyle>
93 <http://ghc.haskell.org/trac/ghc/wiki/Commentary/Rts/Conventions>
94
95 A high level overview of the bug tracker:
96
97 <http://ghc.haskell.org/trac/ghc/wiki/WorkingConventions/BugTracker>
98
99 If you're going to contribute regularly, **learning how to use the
100 build system is important** and will save you lots of time. You should
101 read over this page carefully:
102
103 <http://ghc.haskell.org/trac/ghc/wiki/Building/Using>
104
105 How to communicate with us
106 ==========================
107
108 GHC is a big project, so you'll surely need help. Luckily, we can
109 provide plenty through a variety of means!
110
111 ## IRC
112
113 If you're an IRC user, be sure to drop by the official `#ghc` channel
114 on [freenode](http://freenode.org). Many (but not all) of the
115 developers and committers are actively there during a variety of
116 hours.
117
118 ## Mailing lists
119
120 In the event IRC does not work or if you'd like a bigger audience, GHC
121 has several mailing lists for this purpose. The most important one is
122 [ghc-devs](http://www.haskell.org/pipermail/ghc-devs/), which is where
123 the developers actively hang out and discuss incoming changes and
124 problems.
125
126 There is no strict standard about where you post patches - either in
127 `ghc-devs` or in the bug tracker. Ideally, please put it in the bug
128 tracker with test cases or relevant information in a ticket, and set
129 the ticket status to `patch`. By doing this, we'll see the patch
130 quickly and be able to review. This will also ensure it doesn't get
131 lost. But if the change is small and self contained, feel free to
132 attach it to your email, and send it to `ghc-devs`.
133
134 Furthermore, if you're a developer (or want to become one!) you're
135 undoubtedly also interested in the other mailing lists:
136
137  * [glasgow-haskell-users](http://www.haskell.org/mailman/listinfo/glasgow-haskell-users)
138    is where developers/users meet.
139  * [ghc-tickets](http://www.haskell.org/mailman/listinfo/ghc-tickets)
140    for email from Trac.
141  * [ghc-builds](http://www.haskell.org/mailman/listinfo/ghc-builds)
142    for nightly build emails.
143  * [ghc-commits](http://www.haskell.org/mailman/listinfo/ghc-commits)
144    for commit messages when someone pushes to the repository.
145
146 El fin
147 ======
148
149 Happy Hacking!  -- The GHC Team