Hadrian: introduce userDefaultFlavour, making default flavour overridable
[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 ## Packages
106
107 Users can add and remove packages from particular build stages. As an example,
108 below we add package `base` to Stage0 and remove package `haskeline` from Stage1:
109 ```haskell
110 userFlavour :: Flavour
111 userFlavour = defaultFlavour { name = "user", packages = modifiedPackages }
112
113 modifiedPackages :: Stage -> Action [Package]
114 modifiedPackages stage = do
115     packages <- defaultPackages stage
116     return $ case stage of
117         Stage0 -> packages ++ [base]
118         Stage1 -> packages \\ [haskeline]
119         _      -> packages
120 ```
121 If you are working on a new GHC package you need to let Hadrian know about it
122 by adding it to `userPackages`:
123 ```haskell
124 userPackages :: [Package]
125 userPackages = [userPackage]
126
127 -- An example package that lives in "libraries/user-package" directory.
128 userPackage :: Package
129 userPackage = library "user-package"
130 ```
131 You will also need to add `userPackage` to a specific build stage by modifying
132 the `packages` setting of the user flavour as otherwise it will not be built.
133
134 You can choose which integer library to use when builing GHC using the
135 `integerLibrary` setting of the build flavour. Possible values are: `integerGmp`
136 (default) and `integerSimple`.
137 ```haskell
138 userFlavour :: Flavour
139 userFlavour = defaultFlavour { name = "user", integerLibrary = integerSimple }
140 ```
141 ## Build ways
142
143 Packages can be built in a number of ways, such as `vanilla`, `profiling` (with
144 profiling information enabled), and many others as defined in `src/Way.hs`. You
145 can change the default build ways by modifying `libraryWays` and `rtsWays` fields
146 of the `Flavour` record as required. As an example, below we remove `profiling`
147 from the list of library ways:
148 ```haskell
149 noProfilingFlavour :: Flavour
150 noProfilingFlavour = defaultFlavour
151     { name        = "no-profiling"
152     , libraryWays = remove [profiling] defaultLibraryWays
153     , ghcProfiled = False } -- Can't build profiled GHC without profiled libraries
154 ```
155 Note that `rtsWays` is computed from `libraryWays` by default, therefore the above
156 change will lead to the removal of `threadedProfiling` way from `rtsWays`. To
157 change this behaviour, you can override the default `rtsWays` setting.
158
159 Similarly, if we want to completely turn off dynamic linking, we can define a custom
160 `Flavour` to this effect:
161 ``` haskell
162 noDynamicFlavour :: Flavour
163 noDynamicFlavour = defaultFlavour
164     { name = "no-dynamic"
165     , libraryWays = remove [dynamic] defaultLibraryWays }
166 ```
167
168 ## Verbose command lines
169
170 By default Hadrian does not print full command lines during the build process
171 and instead prints short human readable digests for each executed command. You
172 can suppress this behaviour completely or partially using `verboseCommand` setting:
173 ```haskell
174 -- | Set to 'True' to print full command lines during the build process. Note:
175 -- this is a 'Predicate', hence you can enable verbose output only for certain
176 -- targets, e.g.: @verboseCommand = package ghcPrim@.
177 verboseCommand :: Predicate
178 verboseCommand = do
179     verbosity <- expr getVerbosity
180     return $ verbosity >= Loud
181 ```
182 For example, to print the full command lines used to compile GHC executables,
183 set `verboseCommands` to:
184 ```haskell
185 verboseCommand :: Predicate
186 verboseCommand = input "ghc/Main.hs"
187 ```
188 Below are a few other examples:
189 ```haskell
190 -- Print command lines for all Ghc Link invocations:
191 verboseCommand = builder (Ghc Link)
192
193 -- Print command lines when compiling files in package compiler using Gcc:
194 verboseCommand = builder (Gcc Compile) &&^ package compiler
195
196 -- Use patterns when matching files:
197 verboseCommand = output "//rts/sm/*" &&^ way threaded
198
199 -- Print all commands:
200 verboseCommand = return True
201 ```
202
203 ## Miscellaneous
204
205 By setting `stage1Only = True` you can disable building Stage2 GHC and Stage2
206 utilities such as `haddock`. Note that all Stage0 and Stage1 libraries will
207 still be built.
208
209 To change the default behaviour of Hadrian with respect to building split
210 objects, override the `splitObjects` setting of the `Flavour` record:
211 ```haskell
212 userFlavour :: Flavour
213 userFlavour = defaultFlavour { name = "user", splitObjects = return False }
214 ```
215
216 Hadrian prints various progress info during the build. You can change the colours
217 used by default by overriding `buildProgressColour` and `successColour`:
218 ```haskell
219 -- | Set colour for build progress messages (e.g. executing a build command).
220 buildProgressColour :: BuildProgressColour
221 buildProgressColour = mkBuildProgressColour (Dull Magenta)
222
223 -- | Set colour for success messages (e.g. a package is built successfully).
224 successColour :: SuccessColour
225 successColour = mkSuccessColour (Dull Green)
226 ```
227
228 Your options are `Dull Colour`, `Vivid Colour`, or `Extended Code`. `Dull`
229 colours are the ANSI 8-bit colours, `Vivid` correspond to the 16-bit codes that
230 end with ";1", and `Extended` let's you enter a manual code for the 256 colour
231 set. E.g.
232
233 ```
234 Dull Blue
235 Vivid Cyan
236 Extended "203"
237 ```