Add flavours link
[ghc.git] / hadrian / doc / make.md
1 # Hadrian for Make users
2
3 This is a cheatsheet-style document meant to succinctly show how to use
4 Hadrian for any GHC developer familiar with the Make build system, by showing
5 the Make command(s) to achieve some goal and then the Hadrian equivalent. If you
6 are looking for a more verbose and comprehensive document, you should head to
7 [Hadrian's README](../README.md).
8
9 ## tl;dr
10
11 For GHC hackers already used to the Make build system, here is what you need to
12 know:
13
14 - You can still boot and configure yourself.
15 - Use `hadrian/build.{sh, bat}` instead of `make`. It supports `-j`. This build
16   script will from now on be referred to as simply `build`.
17 - Add the `-c` flag if you want hadrian to boot and configure the source tree
18   for you.
19 - Build products are not in `inplace` anymore, but `_build` by default. Your
20   stage 2 GHC would then be at `_build/stage1/bin/ghc` (because it's built by
21   the stage 1 compiler).
22 - The build root is configurable with `--build-root` or `-o`.
23 - You can pick the build flavour with `--flavour=X` where X is `perf`, `prof`,
24   etc.
25 - You can run tests with `build test`, and specific ones by adding
26   `--only="T12345 T11223"` for example.
27 - GHCs built by Hadrian are relocatable on Windows, Linux, OS X and FreeBSD.
28   This means you can move the `<build root>/stage1/{lib, bin}` directories
29   around and GHC will still happily work, as long as both directories stay next
30   to each other.
31
32 Of particular interest is the `--build-root/-o` option, which is often useful to
33 work on different things or build GHC in different ways, from the same
34 directory/GHC checkout, without having to sacrifice the build artifacts every
35 time you fire up a build. This is not possible with the Make build system.
36
37 ## Equivalent commands
38
39 - Building a complete stage 2 compiler with its libraries, default flavour
40
41   ``` sh
42   # Make
43   make
44
45   # Hadrian
46   build
47   ```
48
49 - Building with many cores
50
51   ``` sh
52   # Make
53   make -j8
54
55   # Hadrian
56   build -j8
57   ```
58
59 - Bulding a stage 1 or 2 GHC executable
60
61   ``` sh
62   # Make
63   make inplace/bin/ghc-stage1
64   make inplace/bin/ghc-stage2
65
66   # Hadrian
67   build stage1:exe:ghc-bin    # using the simple target name
68   build _build/stage0/bin/ghc # OR using the actual path
69
70   build stage2:exe:ghc-bin    # simple target
71   build _build/stage1/bin/ghc # OR actual path
72   ```
73
74 - Building and registering a library with the stage 2 compiler
75
76   ``` sh
77   # Make
78   make inplace/lib/package.conf.d/text-1.2.3.0.conf
79
80   # Hadrian
81   build stage2:lib:text                                    # simple target
82   build _build/stage1/lib/package.conf.d/text-1.2.3.0.conf # OR actual path
83   ```
84
85 - Building with a particular flavour (e.g `quickest`)
86
87   ``` sh
88   # Make
89   echo "BuildFlavour=quickest" >> mk/build.mk
90   make
91
92   # Hadrian
93   build --flavour=quickest
94   ```
95   See [flavours documentation](https://gitlab.haskell.org/ghc/ghc/blob/master/hadrian/doc/flavours.md) for info on flavours.
96
97 - Building with `integer-simple` as the integer library
98
99   ``` sh
100   # Make
101   echo "INTEGER_LIBRARY=integer-simple" >> mk/build.mk
102   make
103
104   # Hadrian
105   build --integer-simple
106   ```
107
108 - Freezing the stage 1 GHC compiler
109
110   ``` sh
111   # Make
112   echo "stage=2" >> mk/build.mk
113   make
114
115   # Hadrian
116   build --freeze1
117   ```
118
119 - Running the testsuite
120
121   ``` sh
122   # Make
123   make test                             # (1)
124   make test TEST=plugins01              # (2)
125   make test TEST="plugins01 plugins02"  # (3)
126
127
128   # Hadrian
129   build test # equivalent to (1)
130
131   build test --only=plugins01 # equivalent to (2)
132   TEST=plugins01 build test   # equivalent to (2)
133
134   build test --only="plugins01 plugins02"    # equivalent to (3)
135   TEST="plugins01 plugins02" build test      # equivalent to (3)
136   TEST=plugins01 build test --only=plugins02 # equivalent to (3)
137   ```
138
139   As illustrated in the examples above, you can use the `TEST` environment
140   variable, the `--only=...` flag or even both to restrict your testsuite run
141   to some (usually small) subset of the testsuite.
142
143   See [the docs for the test rules](./testsuite.md) if you want to know about
144   all the options that hadrian supports and what they correspond to in the Make
145   build system.
146
147 - Generate the `platformConstants` file to be used for stage 1/2 GHC
148
149   ``` sh
150   # Make
151   make inplace/lib/platformConstants
152
153   # Hadrian
154   build _build/stage0/lib/platformConstants
155   build _build/stage1/lib/platformConstants
156   ```
157
158 - Build a static library for base with the stage 1 compiler
159
160   ``` sh
161   # Make
162   make libraries/base/dist-install/build/libHSbase-4.12.0.0.a
163
164   # Hadrian
165   build _build/stage1/libraries/base/build/libHSbase-4.12.0.0.a
166   ```
167
168 - Generate haddocks, user guide, etc
169
170   ``` sh
171   # Make
172   make docs
173
174   # Hadrian
175   build docs
176   ```
177
178 - Build documentation, but without haddocks (resp. without HTML or PDF manuals)
179
180   ``` sh
181   # Make
182   echo 'HADDOCKS_DOCS = NO' > mk/build.mk
183   # For HTML manuals: BUILD_SPHINX_HTML = NO
184   # For PDF manuals: BUILD_SPHINX_PDF = NO
185   make
186
187   # Hadrian
188   build docs --docs=no-haddocks
189   # Append --docs=no-sphinx-pdfs, --docs=no-sphinx-html or
190   # --docs=no-sphinx-man (or --docs=no-sphinx to encompass them all)
191   # to further reduce or even completely disable documentation targets.
192   ```
193
194 - Running nofib
195
196   ``` sh
197   # Make
198   cd nofib; make clean; make boot; make 2>&1 | tee nofib-log
199
200   # Hadrian
201   build nofib # builds the compiler and everything we need if necessary, too
202   ```