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