6b1849f47975ba3db57ee0278e47b33cc03dee08
[ghc.git] / hadrian / doc / user-settings.md
1 # User settings
2
3 You can customise Hadrian by copying the file `hadrian/src/UserSettings.hs` to
4 `hadrian/UserSettings.hs` and overriding the default build settings (if you don't
5 copy the file your changes will be tracked by `git` and you can accidentally commit
6 them). Here we document currently supported settings.
7
8 ## Build flavour
9
10 Build _flavour_ is a collection of build settings that fully define a GHC build
11 (see `src/Flavour.hs`):
12 ```haskell
13 data Flavour = Flavour {
14     -- | Flavour name, to select this flavour from command line.
15     name :: String,
16     -- | Use these command line arguments.
17     args :: Args,
18     -- | Build these packages.
19     packages :: Stage -> Action [Package],
20     -- | Either 'integerGmp' or 'integerSimple'.
21     integerLibrary :: Action Package,
22     -- | Build libraries these ways.
23     libraryWays :: Ways,
24     -- | Build RTS these ways.
25     rtsWays :: Ways,
26     -- | Build dynamic GHC programs.
27     dynamicGhcPrograms :: Action Bool,
28     -- | Enable GHCi debugger.
29     ghciWithDebugger :: Bool,
30     -- | Build profiled GHC.
31     ghcProfiled :: Bool,
32     -- | Build GHC with debug information.
33     ghcDebugged :: Bool
34     -- | Whether to build docs and which ones
35     --   (haddocks, user manual, haddock manual)
36     ghcDocs :: Action DocTargets }
37 ```
38 Hadrian provides several built-in flavours (`default`, `quick`, and a few
39 others; see `hadrian/doc/flavours.md`), which can be activated from the command line,
40 e.g. by passing `--flavour=quick`. Users can define new build flavours by adding them
41 to `userFlavours` list:
42 ```haskell
43 -- | User-defined build flavours. See 'userFlavour' as an example.
44 userFlavours :: [Flavour]
45 userFlavours = [userFlavour] -- Add more build flavours if need be.
46
47 -- | This is an example user-defined build flavour. Feel free to modify it and
48 -- use by passing @--flavour=user@ from the command line.
49 userFlavour :: Flavour
50 userFlavour = defaultFlavour { name = "user" } -- Modify other settings here.
51 ```
52 Now `--flavour=user` will run Hadrian with `userFlavour` settings.
53
54 When no `--flavour` argument is passed to hadrian, it will use the
55 `default` one. You can however change this, and for example make
56 the "fallback" flavour be `user`, by changing `userDefaultFlavour`:
57
58 ``` haskell
59 userDefaultFlavour :: String
60 -- before:
61 -- userDefaultFlavour = "default"
62 -- now:
63 userDefaultFlavour = "user"
64 ```
65
66 This saves you from having to type `build --flavour=user [...]`
67 every time, allowing you to _persist_ the choice of flavour.
68
69 In the
70 following sections we look at specific fields of the `Flavour` record in
71 more detail. Note: `defaultFlavour`, as well as its individual fields such
72 as `defaultArgs`, `defaultPackages`, etc. that we use below, are defined in module
73 `Settings.Default`.
74
75 ## Command line arguments
76
77 One of the key features of Hadrian is that users can easily modify any build command.
78 The build system will detect the change and will rerun all affected build rules during
79 the next build, without requiring a full rebuild.
80
81 For example, here is how to pass an extra argument `-O0` to all invocations of
82 GHC when compiling package `cabal`:
83 ```haskell
84 userFlavour :: Flavour
85 userFlavour = defaultFlavour { name = "user", args = defaultArgs <> userArgs }
86
87 userArgs :: Args
88 userArgs = builder Ghc ? package cabal ? arg "-O0"
89 ```
90 Builders such as `Ghc` are defined in `src/Builder.hs`, and all packages that
91 are currently built as part of the GHC are defined in `src/GHC.hs`.
92
93 You can combine several custom command line settings using `mconcat`:
94 ```haskell
95 userArgs :: Args
96 userArgs = mconcat
97     [ builder Ghc ? package cabal ? arg "-O0"
98     , package rts ? input "//PrimOps.c" ? pure ["-fno-PIC", "-static"] ]
99 ```
100 You can match any combination of the `builder`, `stage`, `package`, `way`, `input`
101 and `output` predicates when specifying custom command line arguments. File
102 patterns such as `"//Prelude.*"` can be used when matching input and output files,
103 where `//` matches an arbitrary number of path components and `*` matches an entire
104 path component, excluding any separators.
105
106 ### Enabling -Werror
107
108 It is useful to enable `-Werror` when building GHC as this setting is
109 used in the CI to ensure a warning free build. The `werror` function can be
110 used to easily modify a flavour to turn this setting on.
111
112 ```
113 devel2WerrorFlavour :: Flavour
114 devel2WerrorFlavour = werror (developmentFlavour Stage2)
115 ```
116
117 ### Linking GHC against the debugged RTS
118
119 What was previously achieved by having `GhcDebugged=YES` in `mk/build.mk` can
120 be done by defining a custom flavour in the user settings file, one that
121 sets the `ghcDebugged` field of `Flavour` to `True`, e.g:
122
123 ``` haskell
124 quickDebug :: Flavour
125 quickDebug = quickFlavour { name = "dbg", ghcDebugged = True }
126 ```
127
128 Running `build --flavour=dbg` will build a `quick`-flavoured GHC and link
129 GHC, iserv, iserv-proxy and remote-iserv against the debugged RTS, by passing
130 `-debug` to the commands that link those executables.
131
132 ## Packages
133
134 Users can add and remove packages from particular build stages. As an example,
135 below we add package `base` to Stage0 and remove package `haskeline` from Stage1:
136 ```haskell
137 ...
138 import Packages
139 ...
140
141 userFlavour :: Flavour
142 userFlavour = defaultFlavour { name = "user", packages = modifiedPackages }
143
144 modifiedPackages :: Stage -> Action [Package]
145 modifiedPackages stage = do
146     packages <- defaultPackages stage
147     return $ case stage of
148         Stage0 -> packages ++ [base]
149         Stage1 -> packages \\ [haskeline]
150         _      -> packages
151 ```
152 If you are working on a new GHC package you need to let Hadrian know about it
153 by adding it to `userPackages`:
154 ```haskell
155 userPackages :: [Package]
156 userPackages = [userPackage]
157
158 -- An example package that lives in "libraries/user-package" directory.
159 userPackage :: Package
160 userPackage = library "user-package"
161 ```
162 You will also need to add `userPackage` to a specific build stage by modifying
163 the `packages` setting of the user flavour as otherwise it will not be built.
164
165 You can choose which integer library to use when builing GHC using the
166 `integerLibrary` setting of the build flavour. Possible values are: `integerGmp`
167 (default) and `integerSimple`.
168 ```haskell
169 userFlavour :: Flavour
170 userFlavour = defaultFlavour { name = "user", integerLibrary = pure integerSimple }
171 ```
172
173 ### Specifying the final stage to build
174
175 The `finalStage` variable can be set to indicate after which stage we should
176 stop the compilation pipeline. By default it is set to `Stage2` which indicates
177 that we will build everything which uses the `Stage1` `ghc` and then stop.
178
179 ```
180 finalStage :: Stage
181 finalStage = Stage2
182 ```
183
184 Using this mechanism we can also build a `Stage3` compiler by setting
185 `finalStage = Stage3` or just a `Stage1` compiler by setting
186 `finalStage = Stage1`.
187
188 ## Build ways
189
190 Packages can be built in a number of ways, such as `vanilla`, `profiling` (with
191 profiling information enabled), and many others as defined in `src/Way.hs`. You
192 can change the default build ways by modifying `libraryWays` and `rtsWays` fields
193 of the `Flavour` record as required. As an example, below we remove `profiling`
194 from the list of library ways:
195 ```haskell
196 noProfilingFlavour :: Flavour
197 noProfilingFlavour = defaultFlavour
198     { name        = "no-profiling"
199     , libraryWays = remove [profiling] defaultLibraryWays
200     , ghcProfiled = False } -- Can't build profiled GHC without profiled libraries
201 ```
202 Note that `rtsWays` is computed from `libraryWays` by default, therefore the above
203 change will lead to the removal of `threadedProfiling` way from `rtsWays`. To
204 change this behaviour, you can override the default `rtsWays` setting.
205
206 Similarly, if we want to completely turn off dynamic linking, we can define a custom
207 `Flavour` to this effect:
208 ``` haskell
209 noDynamicFlavour :: Flavour
210 noDynamicFlavour = defaultFlavour
211     { name = "no-dynamic"
212     , libraryWays = remove [dynamic] defaultLibraryWays }
213 ```
214
215 ## Verbose command lines
216
217 By default Hadrian does not print full command lines during the build process
218 and instead prints short human readable digests for each executed command. You
219 can suppress this behaviour completely or partially using `verboseCommand` setting:
220 ```haskell
221 -- | Set to 'True' to print full command lines during the build process. Note:
222 -- this is a 'Predicate', hence you can enable verbose output only for certain
223 -- targets, e.g.: @verboseCommand = package ghcPrim@.
224 verboseCommand :: Predicate
225 verboseCommand = do
226     verbosity <- expr getVerbosity
227     return $ verbosity >= Loud
228 ```
229 For example, to print the full command lines used to compile GHC executables,
230 set `verboseCommands` to:
231 ```haskell
232 verboseCommand :: Predicate
233 verboseCommand = input "ghc/Main.hs"
234 ```
235 Below are a few other examples:
236 ```haskell
237 -- Print command lines for all Ghc Link invocations:
238 verboseCommand = builder (Ghc Link)
239
240 -- Print command lines when compiling files in package compiler using Gcc:
241 verboseCommand = builder (Gcc Compile) &&^ package compiler
242
243 -- Use patterns when matching files:
244 verboseCommand = output "//rts/sm/*" &&^ way threaded
245
246 -- Print all commands:
247 verboseCommand = return True
248 ```
249
250 ## Documentation
251
252 `Flavour`'s `ghcDocs :: Action DocTargets` field lets you
253 customize the "groups" of documentation targets that should
254 run when running `build docs` (or, transitively,
255 `build binary-dist`).
256
257 ```haskell
258 type DocTargets = Set DocTarget
259 data DocTarget = Haddocks | SphinxHTML | SphinxPDFs | SphinxMan
260 ```
261
262 By default, `ghcDocs` contains all of them and `build docs` would
263 therefore attempt to build all the haddocks, manuals and manpages.
264 If, for some reason (e.g no easy way to install `sphinx-build` or
265 `xelatex` on your system), you're just interested in building the
266 haddocks, you could define a custom flavour as follows:
267
268 ```haskell
269 justHaddocksFlavour :: Flavour
270 justHaddocksFlavour = defaultFlavour
271     { name = "default-haddocks"
272         , ghcDocs = Set.singleton Haddocks }
273 ```
274
275 and then run `build --flavour=default-haddocks`. Alternatively,
276 you can use the `--docs` CLI flag to selectively disable some or
277 all of the documentation targets:
278
279 - `--docs=none`: don't build any docs
280 - `--docs=no-haddocks`: don't build haddocks
281 - `--docs=no-sphinx`: don't build any user manual or manpage
282 - `--docs=no-sphinx-html`: don't build HTML versions of manuals
283 - `--docs=no-sphinx-pdfs`: don't build PDF versions of manuals
284 - `--docs=no-sphinx-man`: don't build the manpage
285
286 You can pass several `--docs=...` flags, Hadrian will combine
287 their effects.
288
289 ## Split sections
290
291 You can build all or just a few packages with
292 [`-split-sections`][split-sections] by tweaking an existing
293 flavour (whichever matches your needs) using
294 `splitSections` or `splitSectionsIf`:
295
296 ``` haskell
297 splitSections :: Flavour -> Flavour
298 splitSectionsIf :: (Package -> Bool) -> Flavour -> Flavour
299 ```
300
301 For example, you can easily start with the `quick` flavour and
302 additionally build all Haskell packages with `-split-sections` by defining a new
303 flavour as
304 `(splitSectionsIf (const True) quickFlavour) { name = "quick-split" }`.
305 You can then start a build with this flavour with `build --flavour=quick-split`.
306
307 Changing `(const True)` to `(== base)` would only build `base` with
308 `-split-sections`, not all Haskell packages as with `quick-split` above.
309
310 `splitSections` is simply `splitSectionsIf` applied to the predicate
311 `(/=ghc)`, i.e it builds all Haskell packages but the `ghc`
312 library with `-split-sections` (it is usually not worth using that
313 option with the `ghc` library).
314
315 ## Miscellaneous
316
317 Hadrian prints various progress info during the build. You can change the colours
318 used by default by overriding `buildProgressColour` and `successColour`:
319 ```haskell
320 -- | Set colour for build progress messages (e.g. executing a build command).
321 buildProgressColour :: BuildProgressColour
322 buildProgressColour = mkBuildProgressColour (Dull Magenta)
323
324 -- | Set colour for success messages (e.g. a package is built successfully).
325 successColour :: SuccessColour
326 successColour = mkSuccessColour (Dull Green)
327 ```
328
329 Your options are `Dull Colour`, `Vivid Colour`, or `Extended Code`. `Dull`
330 colours are the ANSI 8-bit colours, `Vivid` correspond to the 16-bit codes that
331 end with ";1", and `Extended` let's you enter a manual code for the 256 colour
332 set. E.g.
333
334 ```
335 Dull Blue
336 Vivid Cyan
337 Extended "203"
338 ```
339
340 [split-sections]: https://downloads.haskell.org/~ghc/latest/docs/html/users_guide/phases.html#ghc-flag--split-sections