Put one-Shot info in the interface
[ghc.git] / README.md
1 The Glasgow Haskell Compiler
2 ============================
3
4 [![Build Status](https://api.travis-ci.org/ghc/ghc.svg?branch=master)](http://travis-ci.org/ghc/ghc)
5
6 This is the source tree for [GHC][1], a compiler and interactive
7 environment for the Haskell functional programming language.
8
9 For more information, visit [GHC's web site][1].
10
11 Information for developers of GHC can be found on the [GHC Trac][2].
12
13
14 Getting the Source
15 ==================
16
17 There are two ways to get a source tree:
18
19  1. *Download source tarballs*
20
21   Download the GHC source distribution:
22
23         ghc-<version>-src.tar.bz2
24
25   which contains GHC itself and the "boot" libraries.
26
27  2. *Check out the source code from git*
28
29   The official mirror for GHC on GitHub is located at https://github.com/ghc/ghc.
30
31         $ git clone git://github.com/ghc/ghc.git
32         $ cd ghc
33         $ ./sync-all get
34
35   If you want to clone your own fork instead, add an argument to `sync-all` to
36   tell it where it can find the other repositories it needs.
37
38         $ git clone <your preferred github.com GHC fork URL> ghc
39         $ cd ghc
40         $ ./sync-all -r git://github.com/ghc get
41
42   **DO NOT submit pull request directly to the github repo.**
43   *See the GHC developer team's working conventions re [contributing patches](http://ghc.haskell.org/trac/ghc/wiki/WorkingConventions/Git#Contributingpatches "ghc.haskell.org/trac/ghc/wiki/WorkingConventions/Git#Contributingpatches").*
44
45
46 Building & Installing
47 =====================
48
49 For full information on building GHC, see the [GHC Building Guide] [3].
50 Here follows a summary - if you get into trouble, the Building Guide
51 has all the answers.
52
53 Before building GHC you may need to install some other tools and
54 libraries.  See, [Setting up your system for building GHC] [8].
55
56 *NB.* In particular, you need [GHC] [1] installed in order to build GHC,
57 because the compiler is itself written in Haskell.  You also need
58 [Happy] [4], [Alex] [5], and [Cabal] [9].  For instructions on how
59 to port GHC to a new platform, see the [GHC Building Guide] [3].
60
61 For building library documentation, you'll need [Haddock] [6].  To build
62 the compiler documentation, you need a good DocBook XML toolchain and
63 dblatex.
64
65 **Quick start**: the following gives you a default build:
66
67     $ perl boot
68     $ ./configure
69     $ make         # can also say 'make -jX' for X number of jobs
70     $ make install
71
72 (NB: **Do you have multiple cores? Be sure to tell that to `make`!** This can
73 save you hours of build time depending on your system configuration, and is
74 almost always a win regardless of how many cores you have. As a simple rule,
75 you should have about N+1 jobs, where `N` is the amount of cores you have.)
76
77 The `perl boot` step is only necessary if this is a tree checked out
78 from git.  For source distributions downloaded from [GHC's web site] [1],
79 this step has already been performed.
80
81 These steps give you the default build, which includes everything
82 optimised and built in various ways (eg. profiling libs are built).
83 It can take a long time.  To customise the build, see the file `HACKING`.
84
85 Once you have a build you need to keep it going.  You need to keep all
86 repos in sync with the [sync-all script] [7].  To get the latest changes:
87
88     $ ./sync-all pull
89     $ ./sync-all get
90
91 Filing bugs and feature requests
92 ================================
93
94 If you've encountered what you believe is a bug in GHC, or you'd like
95 to propose a feature request, please let us know! Submit a ticket in
96 our [bug tracker] [10] and we'll be sure to look into it. Remember:
97 **Filing a bug is the best way to make sure your issue isn't lost over
98 time**, so please feel free.
99
100 If you're an active user of GHC, you may also be interested in joining
101 the [glasgow-haskell-users] [11] mailing list, where developers and
102 GHC users discuss various topics and hang out.
103
104 Hacking & Developing GHC
105 ========================
106
107 Once you've filed a bug, maybe you'd like to fix it yourself? That
108 would be great, and we'd surely love your company! If you're looking
109 to hack on GHC, check out the guidelines in the `HACKING.md` file in
110 this directory - they'll get you up to speed quickly.
111
112 Contributors & Acknowledgements
113 ===============================
114
115 GHC in its current form wouldn't exist without the hard work of
116 [its many contributors] [12]. Over time, it has grown to include the
117 efforts and research of many institutions, highly talented people, and
118 groups from around the world. We'd like to thank them all, and invite
119 you to join!
120
121   [1]:  http://www.haskell.org/ghc/            "www.haskell.org/ghc/"
122   [2]:  http://ghc.haskell.org/trac/ghc    "ghc.haskell.org/trac/ghc"
123   [3]:  http://ghc.haskell.org/trac/ghc/wiki/Building
124           "ghc.haskell.org/trac/ghc/wiki/Building"
125   [4]:  http://www.haskell.org/happy/          "www.haskell.org/happy/"
126   [5]:  http://www.haskell.org/alex/           "www.haskell.org/alex/"
127   [6]:  http://www.haskell.org/haddock/        "www.haskell.org/haddock/"
128   [7]:  http://ghc.haskell.org/trac/ghc/wiki/Building/SyncAll
129           "http://ghc.haskell.org/trac/ghc/wiki/Building/SyncAll"
130   [8]:  http://ghc.haskell.org/trac/ghc/wiki/Building/Preparation
131           "http://ghc.haskell.org/trac/ghc/wiki/Building/Preparation"
132   [9]:  http://www.haskell.org/cabal/          "http://www.haskell.org/cabal/"
133   [10]: http://ghc.haskell.org/trac/ghc/
134           "http://ghc.haskell.org/trac/ghc/"
135   [11]: http://www.haskell.org/pipermail/glasgow-haskell-users/
136           "http://www.haskell.org/pipermail/glasgow-haskell-users/"
137   [12]: http://ghc.haskell.org/trac/ghc/wiki/TeamGHC
138           "http://ghc.haskell.org/trac/ghc/wiki/TeamGHC"