15bd6bd7995b67670aca5b5d3a47d4363563d1d2
[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
96 - Building with `integer-simple` as the integer library
97
98   ``` sh
99   # Make
100   echo "INTEGER_LIBRARY=integer-simple" >> mk/build.mk
101   make
102
103   # Hadrian
104   build --integer-simple
105   ```
106
107 - Freezing the stage 1 GHC compiler
108
109   ``` sh
110   # Make
111   echo "stage=2" >> mk/build.mk
112   make
113
114   # Hadrian
115   build --freeze1
116   ```
117
118 - Running the testsuite
119
120   ``` sh
121   # Make
122   make test                             # (1)
123   make test TEST=plugins01              # (2)
124   make test TEST="plugins01 plugins02"  # (3)
125
126
127   # Hadrian
128   build test # equivalent to (1)
129
130   build test --only=plugins01 # equivalent to (2)
131   TEST=plugins01 build test   # equivalent to (2)
132
133   build test --only="plugins01 plugins02"    # equivalent to (3)
134   TEST="plugins01 plugins02" build test      # equivalent to (3)
135   TEST=plugins01 build test --only=plugins02 # equivalent to (3)
136   ```
137
138   As illustrated in the examples above, you can use the `TEST` environment
139   variable, the `--only=...` flag or even both to restrict your testsuite run
140   to some (usually small) subset of the testsuite.
141
142   See [the docs for the test rules](./testsuite.md) if you want to know about
143   all the options that hadrian supports and what they correspond to in the Make
144   build system.
145
146 - Generate the `platformConstants` file to be used for stage 1/2 GHC
147
148   ``` sh
149   # Make
150   make inplace/lib/platformConstants
151
152   # Hadrian
153   build _build/stage0/lib/platformConstants
154   build _build/stage1/lib/platformConstants
155   ```
156
157 - Build a static library for base with the stage 1 compiler
158
159   ``` sh
160   # Make
161   make libraries/base/dist-install/build/libHSbase-4.12.0.0.a
162
163   # Hadrian
164   build _build/stage1/libraries/base/build/libHSbase-4.12.0.0.a
165   ```
166
167 - Generate haddocks, user guide, etc
168
169   ``` sh
170   # Make
171   make docs
172
173   # Hadrian
174   build docs
175   ```
176
177 - Build documentation, but without haddocks (resp. without HTML or PDF manuals)
178
179   ``` sh
180   # Make
181   echo 'HADDOCKS_DOCS = NO' > mk/build.mk
182   # For HTML manuals: BUILD_SPHINX_HTML = NO
183   # For PDF manuals: BUILD_SPHINX_PDF = NO
184   make
185
186   # Hadrian
187   build docs --docs=no-haddocks
188   # Append --docs=no-sphinx-pdfs, --docs=no-sphinx-html or
189   # --docs=no-sphinx-man (or --docs=no-sphinx to encompass them all)
190   # to further reduce or even completely disable documentation targets.
191   ```
192
193 - Running nofib
194
195   ``` sh
196   # Make
197   cd nofib; make clean; make boot; make 2>&1 | tee nofib-log
198
199   # Hadrian
200   build nofib # builds the compiler and everything we need if necessary, too
201   ```