b997cd977fa4a07b82bcdbd93ada82f1483dd7b1
[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 split objects.
27     splitObjects :: Predicate,
28     -- | Build dynamic GHC programs.
29     dynamicGhcPrograms :: Action Bool,
30     -- | Enable GHCi debugger.
31     ghciWithDebugger :: Bool,
32     -- | Build profiled GHC.
33     ghcProfiled :: Bool,
34     -- | Build GHC with debug information.
35     ghcDebugged :: Bool }
36 ```
37 Hadrian provides several built-in flavours (`default`, `quick`, and a few
38 others; see `hadrian/doc/flavours.md`), which can be activated from the command line,
39 e.g. by passing `--flavour=quick`. Users can define new build flavours by adding them
40 to `userFlavours` list:
41 ```haskell
42 -- | User-defined build flavours. See 'userFlavour' as an example.
43 userFlavours :: [Flavour]
44 userFlavours = [userFlavour] -- Add more build flavours if need be.
45
46 -- | This is an example user-defined build flavour. Feel free to modify it and
47 -- use by passing @--flavour=user@ from the command line.
48 userFlavour :: Flavour
49 userFlavour = defaultFlavour { name = "user" } -- Modify other settings here.
50 ```
51 Now `--flavour=user` will run Hadrian with `userFlavour` settings.
52
53 When no `--flavour` argument is passed to hadrian, it will use the
54 `default` one. You can however change this, and for example make
55 the "fallback" flavour be `user`, by changing `userDefaultFlavour`:
56
57 ``` haskell
58 userDefaultFlavour :: String
59 -- before:
60 -- userDefaultFlavour = "default"
61 -- now:
62 userDefaultFlavour = "user"
63 ```
64
65 This saves you from having to type `build --flavour=user [...]`
66 every time, allowing you to _persist_ the choice of flavour.
67
68 In the
69 following sections we look at specific fields of the `Flavour` record in
70 more detail. Note: `defaultFlavour`, as well as its individual fields such
71 as `defaultArgs`, `defaultPackages`, etc. that we use below, are defined in module
72 `Settings.Default`.
73
74 ## Command line arguments
75
76 One of the key features of Hadrian is that users can easily modify any build command.
77 The build system will detect the change and will rerun all affected build rules during
78 the next build, without requiring a full rebuild.
79
80 For example, here is how to pass an extra argument `-O0` to all invocations of
81 GHC when compiling package `cabal`:
82 ```haskell
83 userFlavour :: Flavour
84 userFlavour = defaultFlavour { name = "user", args = defaultArgs <> userArgs }
85
86 userArgs :: Args
87 userArgs = builder Ghc ? package cabal ? arg "-O0"
88 ```
89 Builders such as `Ghc` are defined in `src/Builder.hs`, and all packages that
90 are currently built as part of the GHC are defined in `src/GHC.hs`.
91
92 You can combine several custom command line settings using `mconcat`:
93 ```haskell
94 userArgs :: Args
95 userArgs = mconcat
96     [ builder Ghc ? package cabal ? arg "-O0"
97     , package rts ? input "//PrimOps.c" ? pure ["-fno-PIC", "-static"] ]
98 ```
99 You can match any combination of the `builder`, `stage`, `package`, `way`, `input`
100 and `output` predicates when specifying custom command line arguments. File
101 patterns such as `"//Prelude.*"` can be used when matching input and output files,
102 where `//` matches an arbitrary number of path components and `*` matches an entire
103 path component, excluding any separators.
104
105 ### Enabling -Werror
106
107 It is useful to enable `-Werror` when building GHC as this setting is
108 used in the CI to ensure a warning free build. The `werror` function can be
109 used to easily modify a flavour to turn this setting on.
110
111 ```
112 devel2WerrorFlavour :: Flavour
113 devel2WerrorFlavour = werror (developmentFlavour Stage2)
114 ```
115
116 ## Packages
117
118 Users can add and remove packages from particular build stages. As an example,
119 below we add package `base` to Stage0 and remove package `haskeline` from Stage1:
120 ```haskell
121 ...
122 import Packages
123 ...
124
125 userFlavour :: Flavour
126 userFlavour = defaultFlavour { name = "user", packages = modifiedPackages }
127
128 modifiedPackages :: Stage -> Action [Package]
129 modifiedPackages stage = do
130     packages <- defaultPackages stage
131     return $ case stage of
132         Stage0 -> packages ++ [base]
133         Stage1 -> packages \\ [haskeline]
134         _      -> packages
135 ```
136 If you are working on a new GHC package you need to let Hadrian know about it
137 by adding it to `userPackages`:
138 ```haskell
139 userPackages :: [Package]
140 userPackages = [userPackage]
141
142 -- An example package that lives in "libraries/user-package" directory.
143 userPackage :: Package
144 userPackage = library "user-package"
145 ```
146 You will also need to add `userPackage` to a specific build stage by modifying
147 the `packages` setting of the user flavour as otherwise it will not be built.
148
149 You can choose which integer library to use when builing GHC using the
150 `integerLibrary` setting of the build flavour. Possible values are: `integerGmp`
151 (default) and `integerSimple`.
152 ```haskell
153 userFlavour :: Flavour
154 userFlavour = defaultFlavour { name = "user", integerLibrary = pure integerSimple }
155 ```
156
157 ### Specifying the final stage to build
158
159 The `finalStage` variable can be set to indicate after which stage we should
160 stop the compilation pipeline. By default it is set to `Stage2` which indicates
161 that we will build everything which uses the `Stage1` `ghc` and then stop.
162
163 ```
164 finalStage :: Stage
165 finalStage = Stage2
166 ```
167
168 Using this mechanism we can also build a `Stage3` compiler by setting
169 `finalStage = Stage3` or just a `Stage1` compiler by setting
170 `finalStage = Stage1`.
171
172 ## Build ways
173
174 Packages can be built in a number of ways, such as `vanilla`, `profiling` (with
175 profiling information enabled), and many others as defined in `src/Way.hs`. You
176 can change the default build ways by modifying `libraryWays` and `rtsWays` fields
177 of the `Flavour` record as required. As an example, below we remove `profiling`
178 from the list of library ways:
179 ```haskell
180 noProfilingFlavour :: Flavour
181 noProfilingFlavour = defaultFlavour
182     { name        = "no-profiling"
183     , libraryWays = remove [profiling] defaultLibraryWays
184     , ghcProfiled = False } -- Can't build profiled GHC without profiled libraries
185 ```
186 Note that `rtsWays` is computed from `libraryWays` by default, therefore the above
187 change will lead to the removal of `threadedProfiling` way from `rtsWays`. To
188 change this behaviour, you can override the default `rtsWays` setting.
189
190 Similarly, if we want to completely turn off dynamic linking, we can define a custom
191 `Flavour` to this effect:
192 ``` haskell
193 noDynamicFlavour :: Flavour
194 noDynamicFlavour = defaultFlavour
195     { name = "no-dynamic"
196     , libraryWays = remove [dynamic] defaultLibraryWays }
197 ```
198
199 ## Verbose command lines
200
201 By default Hadrian does not print full command lines during the build process
202 and instead prints short human readable digests for each executed command. You
203 can suppress this behaviour completely or partially using `verboseCommand` setting:
204 ```haskell
205 -- | Set to 'True' to print full command lines during the build process. Note:
206 -- this is a 'Predicate', hence you can enable verbose output only for certain
207 -- targets, e.g.: @verboseCommand = package ghcPrim@.
208 verboseCommand :: Predicate
209 verboseCommand = do
210     verbosity <- expr getVerbosity
211     return $ verbosity >= Loud
212 ```
213 For example, to print the full command lines used to compile GHC executables,
214 set `verboseCommands` to:
215 ```haskell
216 verboseCommand :: Predicate
217 verboseCommand = input "ghc/Main.hs"
218 ```
219 Below are a few other examples:
220 ```haskell
221 -- Print command lines for all Ghc Link invocations:
222 verboseCommand = builder (Ghc Link)
223
224 -- Print command lines when compiling files in package compiler using Gcc:
225 verboseCommand = builder (Gcc Compile) &&^ package compiler
226
227 -- Use patterns when matching files:
228 verboseCommand = output "//rts/sm/*" &&^ way threaded
229
230 -- Print all commands:
231 verboseCommand = return True
232 ```
233
234 ## Miscellaneous
235
236 To change the default behaviour of Hadrian with respect to building split
237 objects, override the `splitObjects` setting of the `Flavour` record:
238 ```haskell
239 userFlavour :: Flavour
240 userFlavour = defaultFlavour { name = "user", splitObjects = return False }
241 ```
242
243 Hadrian prints various progress info during the build. You can change the colours
244 used by default by overriding `buildProgressColour` and `successColour`:
245 ```haskell
246 -- | Set colour for build progress messages (e.g. executing a build command).
247 buildProgressColour :: BuildProgressColour
248 buildProgressColour = mkBuildProgressColour (Dull Magenta)
249
250 -- | Set colour for success messages (e.g. a package is built successfully).
251 successColour :: SuccessColour
252 successColour = mkSuccessColour (Dull Green)
253 ```
254
255 Your options are `Dull Colour`, `Vivid Colour`, or `Extended Code`. `Dull`
256 colours are the ANSI 8-bit colours, `Vivid` correspond to the 16-bit codes that
257 end with ";1", and `Extended` let's you enter a manual code for the 256 colour
258 set. E.g.
259
260 ```
261 Dull Blue
262 Vivid Cyan
263 Extended "203"
264 ```