|
# Contributing to GHC
|
|
# Contributing to GHC
|
|
|
|
|
|
|
|
|
|
GHC is a BSD-licensed open-source project, and we welcome your help in making it better. This page and the side bar on the right have pointers to information you'll need.
|
|
GHC is a BSD-licensed open-source project, and we welcome your help in making it better. This page and the side bar on the right have pointers to information you'll need.
|
|
|
|
|
|
- [Information for newcomers](contributing#newcomers-to-ghc). This the first stop for those people who say, "I want to contribute to GHC, but I don't know quite where to begin." Begin here.
|
|
- [Information for newcomers](contributing#newcomers-to-ghc). This the first stop for those people who say, "I want to contribute to GHC, but I don't know quite where to begin." Begin here.
|
|
|
|
|
|
- [How to file a bug report for GHC](/report-a-bug)
|
|
- [How to file a bug report for GHC](/report-a-bug)
|
|
|
|
|
|
- [How to contribute a patch to GHC](/Contributing-a-Patch). For [adding features](working-conventions/adding-features), there are a few extra steps to follow.
|
|
- [How to contribute a patch to GHC](/Contributing-a-Patch). For [adding features](working-conventions/adding-features), there are a few extra steps to follow.
|
|
|
|
|
|
- To propose a change to the libraries, you should contact the relevant library maintainer or the [Core Libraries Committee](https://github.com/haskell/core-libraries-committee).
|
|
- To propose a change to the libraries, you should contact the relevant library maintainer or the [Core Libraries Committee](https://github.com/haskell/core-libraries-committee).
|
|
|
|
|
|
## Working conventions
|
|
## Working conventions
|
|
|
|
|
|
- **Using Git**: read [how to use git with GHC](working-conventions/git). Information about our submodule setup is in [WorkingConventions/Git/Submodules](working-conventions/git/submodules), and some useful Git tricks are in [WorkingConventions/Git/Tricks](working-conventions/git/tricks).
|
|
- **Using Git**: read [how to use git with GHC](working-conventions/git). Information about our submodule setup is in [WorkingConventions/Git/Submodules](working-conventions/git/submodules), and some useful Git tricks are in [WorkingConventions/Git/Tricks](working-conventions/git/tricks).
|
|
|
|
|
|
- **GitLab conventions**:
|
|
- **GitLab conventions**:
|
|
- [Label usage](gitlab/labels)
|
|
- [Label usage](gitlab/labels)
|
|
- [Issue tracker conventions](gitlab/issues)
|
|
- [Issue tracker conventions](gitlab/issues)
|
|
- [Merge request conventions](gitlab/merge-requests)
|
|
- [Merge request conventions](gitlab/merge-requests)
|
|
|
|
|
|
- **Releases and branches**:
|
|
- **Releases and branches**:
|
|
- Our conventions for making releases and how the branches are managed: [Releases](working-conventions/releases)
|
|
- Our conventions for making releases and how the branches are managed: [Releases](working-conventions/releases)
|
|
- Instructions for [backporting](contributing/Backporting)
|
|
- Instructions for [backporting](contributing/Backporting)
|
|
|
|
|
|
- **Useful tools**: [Various tools](working-conventions/useful-tools) which exist to make working on GHC more pleasant.
|
|
- **Useful tools**: [Various tools](working-conventions/useful-tools) which exist to make working on GHC more pleasant.
|
|
|
|
|
|
- **Coding style**: When you are editing GHC's source code, please follow our coding guidelines:
|
|
- **Coding style**: When you are editing GHC's source code, please follow our coding guidelines:
|
|
- [Coding style in the compiler](commentary/coding-style)
|
|
- [Coding style in the compiler](commentary/coding-style)
|
|
- [Coding style in the runtime system](commentary/rts/conventions)
|
|
- [Coding style in the runtime system](commentary/rts/conventions)
|
|
|
|
|
|
- **Linting in the CI process**: Here are listed the Hadrian rules that run HLint on your patch.
|
|
- **Linting in the CI process**: Here are listed the Hadrian rules that run HLint on your patch.
|
|
- `lint:base`: This runs HLint on the `base` library
|
|
- `lint:base`: This runs HLint on the `base` library
|
|
- `lint:compiler`: This runs HLint on the `./compiler` codebase
|
|
- `lint:compiler`: This runs HLint on the `./compiler` codebase
|
|
|
|
|
|
- **Testing against Hackage**: Patches that change the language GHC accepts may want to test against a subset of Hackage, kept up-to-date with GHC HEAD. See the [head.hackage repo](https://gitlab.haskell.org/ghc/head.hackage) for more information.
|
|
- **Testing against Hackage**: Patches that change the language GHC accepts may want to test against a subset of Hackage, kept up-to-date with GHC HEAD. See the [head.hackage repo](https://gitlab.haskell.org/ghc/head.hackage) for more information.
|
|
|
|
|
|
- **Licensing**: make sure you are familiar with GHC's [Licensing](licensing). Unless you say otherwise, we will assume that if you submit a contribution to GHC, then you intend to supply it to us under the same license as the existing code. However, we do not ask for copyright attribution; you retain copyright on any contributions you make, so feel free to add your copyright to the top of any file in which you make non-trivial changes.
|
|
- **Licensing**: make sure you are familiar with GHC's [Licensing](licensing). Unless you say otherwise, we will assume that if you submit a contribution to GHC, then you intend to supply it to us under the same license as the existing code. However, we do not ask for copyright attribution; you retain copyright on any contributions you make, so feel free to add your copyright to the top of any file in which you make non-trivial changes.
|
|
|
|
|
|
- **For boot libraries**: GHC ships with a number of [boot libraries](commentary/libraries/version-history) maintained outside of GHC itself. Maintainers of such libraries should read [WorkingConventions/BootLibraries](working-conventions/boot-libraries) for guidance on how to maintain their libraries.
|
|
- **For boot libraries**: GHC ships with a number of [boot libraries](commentary/libraries/version-history) maintained outside of GHC itself. Maintainers of such libraries should read [WorkingConventions/BootLibraries](working-conventions/boot-libraries) for guidance on how to maintain their libraries.
|
|
|
|
- **Tracking fixes across branches**:
|
|
|
|
1. Find the issue, which should have a reference to the merge requests which fixed it
|
|
|
|
2. From the merge request, find the final commit SHA from Marge's comment
|
|
|
|
3. Look for references to that commit SHA in the appropriate branch.
|
|
|
|
|
|
## Tips and Tricks
|
|
## Tips and Tricks
|
|
|
|
|
|
- [Loading GHC into GHCi](building/in-ghci) can provide a more iterative development experience.
|
|
- [Loading GHC into GHCi](building/in-ghci) can provide a more iterative development experience.
|
|
|
|
|
|
- To have an easier time looking up tickets and searching GitLab, use [the browser tips page](browser-tips) to make your search and lookups for GitLab tickets substantially easier.
|
|
- To have an easier time looking up tickets and searching GitLab, use [the browser tips page](browser-tips) to make your search and lookups for GitLab tickets substantially easier.
|
|
|
|
|
|
- If you use Emacs, see [Emacs](emacs) for some useful stuff to put in your `.emacs` file.
|
|
- If you use Emacs, see [Emacs](emacs) for some useful stuff to put in your `.emacs` file.
|
|
|
|
|
|
- If you use Spacemacs or VSCode and Nix: The [Spacemacs](spacemacs) and [Visual Studio Code](Visual-Studio-Code) pages explain how to use them as an IDE.
|
|
- If you use Spacemacs or VSCode and Nix: The [Spacemacs](spacemacs) and [Visual Studio Code](Visual-Studio-Code) pages explain how to use them as an IDE.
|
|
|
|
|
|
- If you have lots of Haskell installations, you may find Edsko's blog post [Comprehensive Haskell Sandboxes](http://www.edsko.net/2013/02/10/comprehensive-haskell-sandboxes/) useful.
|
|
- If you have lots of Haskell installations, you may find Edsko's blog post [Comprehensive Haskell Sandboxes](http://www.edsko.net/2013/02/10/comprehensive-haskell-sandboxes/) useful.
|
|
|
|
|
|
- [ghc-artefact-nix](https://github.com/mpickering/ghc-artefact-nix) is a Nix expression, which downloads a recent artifact from gitlab.haskell.org and enters a nix shell with the artefact available. This is a quick way to try some code out on a recent `HEAD` or a merge request.
|
|
- [ghc-artefact-nix](https://github.com/mpickering/ghc-artefact-nix) is a Nix expression, which downloads a recent artifact from gitlab.haskell.org and enters a nix shell with the artefact available. This is a quick way to try some code out on a recent `HEAD` or a merge request.
|
|
|
|
|
|
## Newcomers to GHC
|
|
## Newcomers to GHC
|
... | @@ -65,9 +52,7 @@ If you have any questions along the way don't hesitate to reach out to the commu |
... | @@ -65,9 +52,7 @@ If you have any questions along the way don't hesitate to reach out to the commu |
|
Follow the instructions on https://ghc.dev.
|
|
Follow the instructions on https://ghc.dev.
|
|
|
|
|
|
- See [Building](building/hadrian) to get started building GHC. Expect it all to take roughly between 20-40 minutes, depending on your CPU speed, and the number of jobs you can run in parallel. Note that [building older versions of GHC may require having an older version of GHC on your path](https://gitlab.haskell.org/ghc/ghc/wikis/building/preparation/tools).
|
|
- See [Building](building/hadrian) to get started building GHC. Expect it all to take roughly between 20-40 minutes, depending on your CPU speed, and the number of jobs you can run in parallel. Note that [building older versions of GHC may require having an older version of GHC on your path](https://gitlab.haskell.org/ghc/ghc/wikis/building/preparation/tools).
|
|
|
|
|
|
- While you are waiting for your build to finish, orient yourself to the general architecture of GHC. This [article](http://www.aosabook.org/en/ghc.html) is written by two of the chief architects of GHC, Simon Marlow and Simon Peyton-Jones, is excellent and current (2012).
|
|
- While you are waiting for your build to finish, orient yourself to the general architecture of GHC. This [article](http://www.aosabook.org/en/ghc.html) is written by two of the chief architects of GHC, Simon Marlow and Simon Peyton-Jones, is excellent and current (2012).
|
|
|
|
|
|
- After a successful build, you should have your brand new compiler in `./_build/stage1/bin/ghc`. (GHCi is launched with `./_build/stage1/bin/ghc --interactive`). Try it out.
|
|
- After a successful build, you should have your brand new compiler in `./_build/stage1/bin/ghc`. (GHCi is launched with `./_build/stage1/bin/ghc --interactive`). Try it out.
|
|
|
|
|
|
### Finding a ticket
|
|
### Finding a ticket
|
... | @@ -79,26 +64,19 @@ If you want to get a taste for possible starting tasks, the ~newcomer label coll |
... | @@ -79,26 +64,19 @@ If you want to get a taste for possible starting tasks, the ~newcomer label coll |
|
### Advice
|
|
### Advice
|
|
|
|
|
|
- Read up on the steps you are expected to take for [contributing a patch to GHC](/Contributing-a-Patch).
|
|
- Read up on the steps you are expected to take for [contributing a patch to GHC](/Contributing-a-Patch).
|
|
|
|
|
|
- Need help? You can email the [ghc-devs](http://www.haskell.org/mailman/listinfo/ghc-devs) list, or ask on IRC in `#ghc`.
|
|
- Need help? You can email the [ghc-devs](http://www.haskell.org/mailman/listinfo/ghc-devs) list, or ask on IRC in `#ghc`.
|
|
|
|
|
|
- Don't get scared. GHC is a big codebase, but it makes sense when you stare at it long enough!
|
|
- Don't get scared. GHC is a big codebase, but it makes sense when you stare at it long enough!
|
|
|
|
- You can [change](https://gitlab.haskell.org/help/user/profile/index?target=\_blank#change-the-email-displayed-on-your-commits) in your profile your commit email to private, e.g. `00001-username@users.gitlab.noreply.gitlab.haskell.org`.
|
|
- You can [change](https://gitlab.haskell.org/help/user/profile/index?target=_blank#change-the-email-displayed-on-your-commits) in your profile your commit email to private, e.g. `00001-username@users.gitlab.noreply.gitlab.haskell.org`.
|
|
|
|
|
|
|
|
- Don't hesitate to ask questions. We have all been beginners at some point and understand that diving in to GHC can be a challenge. Asking questions will help you make better use of your hacking time.
|
|
- Don't hesitate to ask questions. We have all been beginners at some point and understand that diving in to GHC can be a challenge. Asking questions will help you make better use of your hacking time.
|
|
|
|
|
|
- Be forewarned that many pages on the GHC Wiki are somewhat out-of-date. Always check the last modification date. Email `ghc-devs` if you're not sure.
|
|
- Be forewarned that many pages on the GHC Wiki are somewhat out-of-date. Always check the last modification date. Email `ghc-devs` if you're not sure.
|
|
|
|
|
|
- You may want to look at these "how it went for me" blog posts.
|
|
- You may want to look at these "how it went for me" blog posts.
|
|
|
|
|
|
- [Hacking on GHC (is not that hard)](http://rawgit.com/gibiansky/4c54f767bf21a6954b23/raw/67c62c5555f40c6fb67b124307725df168201361/exp.html) by Andrew Gibiansky
|
|
- [Hacking on GHC (is not that hard)](http://rawgit.com/gibiansky/4c54f767bf21a6954b23/raw/67c62c5555f40c6fb67b124307725df168201361/exp.html) by Andrew Gibiansky
|
|
- [Contributing to GHC](http://anniecherkaev.com/projects/contributing-to-ghc) by Annie Cherkaev
|
|
- [Contributing to GHC](http://anniecherkaev.com/projects/contributing-to-ghc) by Annie Cherkaev
|
|
- Andreas Herrmann's [“GHC Hacking Newcomer Guide”](https://youtu.be/s9DkByHSdOg) talk is a wealth of information communicated clearly and succinctly. You can also just browse [the slides](https://github.com/meiersi/HaskellerZ/blob/master/meetups/20180531-GHC-Newcomers-Guide/slides.md).
|
|
- Andreas Herrmann's [“GHC Hacking Newcomer Guide”](https://youtu.be/s9DkByHSdOg) talk is a wealth of information communicated clearly and succinctly. You can also just browse [the slides](https://github.com/meiersi/HaskellerZ/blob/master/meetups/20180531-GHC-Newcomers-Guide/slides.md).
|
|
|
|
|
|
- There is a blog post series by Stephen Diehl that provides an overview of many important data structures and contains links to other sources of information: [Dive into GHC](http://www.stephendiehl.com/posts/ghc_01.html)
|
|
- There is a blog post series by Stephen Diehl that provides an overview of many important data structures and contains links to other sources of information: [Dive into GHC](http://www.stephendiehl.com/posts/ghc_01.html)
|
|
|
|
|
|
### Further reading
|
|
### Further reading
|
|
|
|
|
|
There are many places in GHC where acronyms and terms are used to refer to specific optimizations. If you are new to working on the compiler these can be a barrier. See the [Reading list](https://gitlab.haskell.org/ghc/ghc/-/wikis/reading-list) wiki page for answers.
|
|
There are many places in GHC where acronyms and terms are used to refer to specific optimizations. If you are new to working on the compiler these can be a barrier. See the [Reading list](https://gitlab.haskell.org/ghc/ghc/-/wikis/reading-list) wiki page for answers.
|
|
|
|
|
|
Happy hacking! |
|
Happy hacking! |
|
|
|
\ No newline at end of file |