diff options
| -rw-r--r-- | HACKING | 63 | ||||
| -rw-r--r-- | HACKING.md | 149 |
2 files changed, 149 insertions, 63 deletions
diff --git a/HACKING b/HACKING deleted file mode 100644 index 8ceff18881..0000000000 --- a/HACKING +++ /dev/null @@ -1,63 +0,0 @@ -Getting started with hacking on GHC ------------------------------------ - -So you've decided to hack on GHC, congratulations! We hope you have a -rewarding experience. This file will point you in the direction of -information to help you get started right away. - - -The GHC Developer's Wiki ------------------------- - - The home for GHC Developers, with information on accessing the - latest sources, the bug tracker, and documentation on the - code: - - http://hackage.haskell.org/trac/ghc - - In particular, the wiki contains the following pages of interest to - new hackers: - - Quick Start for developers - - http://hackage.haskell.org/trac/ghc/wiki/Building/Hacking - - This section on the wiki will get you up and running with a - serviceable build tree in no time. - - Don't skip this! By default, GHC builds with all optimizations - and profiling; most hackers will want a quicker build, so creating - a mk/build.mk file and knowing how to rebuild only parts of GHC is - very important. - - This is part of the "Building GHC" section of the wiki, which - has more detailed information on GHC's build system should you - need it. - - - Coding conventions - - http://hackage.haskell.org/trac/ghc/wiki/WorkingConventions - - This wiki page explains the ground rules for code that is intended - to go into the mainline compiler source. - - - The GHC Commentary - - http://hackage.haskell.org/trac/ghc/wiki/Commentary - - Notes on the internals and architecture of GHC. - - -Mailing lists -------------- - - Ask on glasgow-haskell-users@haskell.org if you have difficulties. - If you're working with the current darcs sources of GHC, then - cvs-ghc@haskell.org might be a more appropriate (developers hang - out here). See http://www.haskell.org/mailman/listinfo for - subscription. - - -Happy Hacking! --The GHC Team diff --git a/HACKING.md b/HACKING.md new file mode 100644 index 0000000000..c88669761a --- /dev/null +++ b/HACKING.md @@ -0,0 +1,149 @@ +Contributing to the Glasgow Haskell Compiler +============================================ + +So you've decided to hack on GHC, congratulations! We hope you have a +rewarding experience. This file will point you in the direction of +information to help you get started right away. + +The GHC Developer's Wiki +======================== + +The home for GHC hackers is our Trac instance, located here: + +<http://hackage.haskell.org/trac/ghc> + +From here, you can file bugs (or look them up,) use the wiki, view the +`git` history, among other things. Of particular note is the building +page, which has the high level overview of the build process and how +to get the source: + +<http://hackage.haskell.org/trac/ghc/wiki/Building> + +Contributing patches to GHC in a hurry +====================================== + +Make sure your system has the necessary tools to compile GHC. You can +find an overview here: + +<http://hackage.haskell.org/trac/ghc/wiki/Building/Preparation> + +Next, clone the repository and all the associated libraries: + +``` +$ git clone http://darcs.haskell.org/ghc.git/ +$ cd ghc +$ ./sync-all --testsuite get +``` + +First copy `mk/build.mk.sample` to `mk/build.mk` and ensure it has +your preferred build settings. (You probably want to at least set +`BuildFlavour` to `quick`): + +``` +$ cp mk/build.mk.sample mk/build.mk +$ ... double-check mk/build.mk ... +``` + +Now build. If you have multiple cores, **you should always use them to +speed up compilation**: + +``` +$ ./boot +$ ./configure +$ make -jN # <N> is the number of cores you have. +``` + +You can use the `./inplace/bin/ghc-stage2` binary to play with the +newly built compiler. + +Now, hack on your copy and rebuild (with `make`) as necessary. + +Then start by making your commits however you want. When you're done, you +can use `git format-patch` to create a series of `.patch` files you +can give to us. In this example, we'll assume I'm on a `bugfix` branch +and want to submit my patches: + +``` +$ git branch +* bugfix + master +$ git format-patch master -o patches +... +$ +``` + +Now create a trac ticket: + +<http://hackage.haskell.org/trac/ghc/newticket?type=bug> + +And attach the files in your `patches/` directory. Set the status from +*new* to *patch* and we'll review it as soon as we can! + +Useful links: +============= + +An overview of things like using git, the release process, filing bugs +and more can be located here: + +<http://hackage.haskell.org/trac/ghc/wiki/WorkingConventions> + +You can find our coding conventions for the compiler and RTS here: + +<http://hackage.haskell.org/trac/ghc/wiki/Commentary/CodingStyle> +<http://hackage.haskell.org/trac/ghc/wiki/Commentary/Rts/Conventions> + +A high level overview of the bug tracker: + +<http://hackage.haskell.org/trac/ghc/wiki/WorkingConventions/BugTracker> + +If you're going to contribute regularly, **learning how to use the +build system is important** and will save you lots of time. You should +read over this page carefully: + +<http://hackage.haskell.org/trac/ghc/wiki/Building/Using> + +How to communicate with us +========================== + +GHC is a big project, so you'll surely need help. Luckily, we can +provide plenty through a variety of means! + +## IRC + +If you're an IRC user, be sure to drop by the official `#ghc` channel +on [freenode](http://freenode.org). Many (but not all) of the +developers and committers are actively there during a variety of +hours. + +## Mailing lists + +In the event IRC does not work or if you'd like a bigger audience, GHC +has several mailing lists for this purpose. The most important one is +[ghc-devs](http://www.haskell.org/pipermail/ghc-devs/), which is where +the developers actively hang out and discuss incoming changes and +problems. + +There is no strict standard about where you post patches - either in +`ghc-devs` or in the bug tracker. Ideally, please put it in the bug +tracker with test cases or relevant information in a ticket, and set +the ticket status to `patch`. By doing this, we'll see the patch +quickly and be able to review. This will also ensure it doesn't get +lost. But if the change is small and self contained, feel free to +attach it to your email, and send it to `ghc-devs`. + +Furthermore, if you're a developer (or want to become one!) you're +undoubtly also interested in the other mailing lists: + + * [glasgow-haskell-users](http://www.haskell.org/mailman/listinfo/glasgow-haskell-users) + is where developers/users meet. + * [ghc-tickets](http://www.haskell.org/mailman/listinfo/ghc-tickets) + for email from Trac. + * [ghc-builds](http://www.haskell.org/mailman/listinfo/ghc-builds) + for nightly build emails. + * [ghc-commits](http://www.haskell.org/mailman/listinfo/ghc-commits) + for commit messages when someone pushes to the repository. + +El fin +====== + +Happy Hacking! -- The GHC Team |