Fix broken colours with `-j` (#484)
[hadrian.git] / 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 directory
9
10 Hadrian puts build results into `_build` directory by default, which is
11 specified by `userBuildRoot`:
12 ```haskell
13 -- | All build results are put into the 'buildRoot' directory.
14 userBuildRoot :: BuildRoot
15 userBuildRoot = BuildRoot "_build"
16 ```
17
18 ## Build flavour
19
20 Build _flavour_ is a collection of build settings that fully define a GHC build
21 (see `src/Flavour.hs`):
22 ```haskell
23 data Flavour = Flavour {
24     -- | Flavour name, to select this flavour from command line.
25     name :: String,
26     -- | Use these command line arguments.
27     args :: Args,
28     -- | Build these packages.
29     packages :: Stage -> Action [Package],
30     -- | Either 'integerGmp' or 'integerSimple'.
31     integerLibrary :: Action Package,
32     -- | Build libraries these ways.
33     libraryWays :: Ways,
34     -- | Build RTS these ways.
35     rtsWays :: Ways,
36     -- | Build split objects.
37     splitObjects :: Predicate,
38     -- | Build dynamic GHC programs.
39     dynamicGhcPrograms :: Bool,
40     -- | Enable GHCi debugger.
41     ghciWithDebugger :: Bool,
42     -- | Build profiled GHC.
43     ghcProfiled :: Bool,
44     -- | Build GHC with debug information.
45     ghcDebugged :: Bool }
46 ```
47 Hadrian provides several built-in flavours (`defaultFlavour`, `quickFlavour`, and a few
48 others; see `hadrian/doc/flavours.md`), which can be activated from the command line,
49 e.g. by passing `--flavour=quick`. Users can define new build flavours by adding them
50 to `userFlavours` list:
51 ```haskell
52 -- | User-defined build flavours. See 'userFlavour' as an example.
53 userFlavours :: [Flavour]
54 userFlavours = [userFlavour] -- Add more build flavours if need be.
55
56 -- | This is an example user-defined build flavour. Feel free to modify it and
57 -- use by passing @--flavour=user@ from the command line.
58 userFlavour :: Flavour
59 userFlavour = defaultFlavour { name = "user" } -- Modify other settings here.
60 ```
61 Now `--flavour=user` will run Hadrian with `userFlavour` settings. In the
62 following sections we look at specific fields of the `Flavour` record in
63 more detail. Note: `defaultFlavour`, as well as its individual fields such
64 as `defaultArgs`, `defaultPackages`, etc. that we use below, are defined in module
65 `Settings.Default`.
66
67 ## Command line arguments
68
69 One of the key features of Hadrian is that users can easily modify any build command.
70 The build system will detect the change and will rerun all affected build rules during
71 the next build, without requiring a full rebuild.
72
73 For example, here is how to pass an extra argument `-O0` to all invocations of
74 GHC when compiling package `cabal`:
75 ```haskell
76 userFlavour :: Flavour
77 userFlavour = defaultFlavour { name = "user", args = defaultArgs <> userArgs }
78
79 userArgs :: Args
80 userArgs = builder Ghc ? package cabal ? arg "-O0"
81 ```
82 Builders such as `Ghc` are defined in `src/Builder.hs`, and all packages that
83 are currently built as part of the GHC are defined in `src/GHC.hs`.
84
85 You can combine several custom command line settings using `mconcat`:
86 ```haskell
87 userArgs :: Args
88 userArgs = mconcat
89     [ builder Ghc ? package cabal ? arg "-O0"
90     , package rts ? input "//Evac_thr.c" ? pure [ "-DPARALLEL_GC", "-Irts/sm" ] ]
91 ```
92 You can match any combination of the `builder`, `stage`, `package`, `way`, `input`
93 and `output` predicates when specifying custom command line arguments. File
94 patterns such as `"//Prelude.*"` can be used when matching input and output files,
95 where `//` matches an arbitrary number of path components and `*` matches an entire
96 path component, excluding any separators.
97
98 ## Packages
99
100 Users can add and remove packages from particular build stages. As an example,
101 below we add package `base` to Stage0 and remove package `haskeline` from Stage1:
102 ```haskell
103 userFlavour :: Flavour
104 userFlavour = defaultFlavour { name = "user", packages = modifiedPackages }
105
106 modifiedPackages :: Stage -> Action [Package]
107 modifiedPackages stage = do
108     packages <- defaultPackages stage
109     return $ case stage of
110         Stage0 -> packages ++ [base]
111         Stage1 -> packages \\ [haskeline]
112         _      -> packages
113 ```
114 If you are working on a new GHC package you need to let Hadrian know about it
115 by adding it to `userPackages`:
116 ```haskell
117 userPackages :: [Package]
118 userPackages = [userPackage]
119
120 -- An example package that lives in "libraries/user-package" directory.
121 userPackage :: Package
122 userPackage = library "user-package"
123 ```
124 You will also need to add `userPackage` to a specific build stage by modifying
125 the `packages` setting of the user flavour as otherwise it will not be built.
126
127 You can choose which integer library to use when builing GHC using the
128 `integerLibrary` setting of the build flavour. Possible values are: `integerGmp`
129 (default) and `integerSimple`.
130 ```haskell
131 userFlavour :: Flavour
132 userFlavour = defaultFlavour { name = "user", integerLibrary = integerSimple }
133 ```
134 ## Build ways
135
136 Packages can be built in a number of ways, such as `vanilla`, `profiling` (with
137 profiling information enabled), and many others as defined in `src/Way.hs`. You
138 can change the default build ways by modifying `libraryWays` and `rtsWays` fields
139 of the `Flavour` record as required. As an example, below we remove `profiling`
140 from the list of library ways:
141 ```haskell
142 noProfilingFlavour :: Flavour
143 noProfilingFlavour = defaultFlavour
144     { name        = "no-profiling"
145     , libraryWays = remove [profiling] defaultLibraryWays
146     , ghcProfiled = False } -- Can't build profiled GHC without profiled libraries
147 ```
148 Note that `rtsWays` is computed from `libraryWays` by default, therefore the above
149 change will lead to the removal of `threadedProfiling` way from `rtsWays`. To
150 change this behaviour, you can override the default `rtsWays` setting.
151
152 ## Verbose command lines
153
154 By default Hadrian does not print full command lines during the build process
155 and instead prints short human readable digests for each executed command. You
156 can suppress this behaviour completely or partially using `verboseCommands` setting:
157 ```haskell
158 -- | Set to 'True' to print full command lines during the build process. Note:
159 -- this is a 'Predicate', hence you can enable verbose output only for certain
160 -- targets, e.g.: @verboseCommand = package ghcPrim@.
161 verboseCommand :: Predicate
162 verboseCommand = do
163     verbosity <- expr getVerbosity
164     return $ verbosity >= Loud
165 ```
166 For example, to print the full command lines used to compile GHC executables,
167 set `verboseCommands` to:
168 ```haskell
169 verboseCommands :: Predicate
170 verboseCommands = input "ghc/Main.hs"
171 ```
172 Below are a few other examples:
173 ```haskell
174 -- Print command lines for all Ghc Link invocations:
175 verboseCommands = builder (Ghc Link)
176
177 -- Print command lines when compiling files in package compiler using Gcc:
178 verboseCommands = builder (Gcc Compile) &&^ package compiler
179
180 -- Use patterns when matching files:
181 verboseCommands = output "//rts/sm/*" &&^ way threaded
182
183 -- Print all commands:
184 verboseCommands = return True
185 ```
186
187 ## Miscellaneous
188
189 By setting `stage1Only = True` you can disable building Stage2 GHC (i.e. the
190 `ghc-stage2` executable) and Stage2 utilities, such as `haddock`. Note that all
191 Stage0 and Stage1 libraries (including `compiler`) will still be built. Enabling
192 this flag during installation leads to installing `ghc-stage1` instead of
193 `ghc-stage2`, and `ghc-pkg` that was build with the Stage0 compiler.
194
195 To change the default behaviour of Hadrian with respect to building split
196 objects, override the `splitObjects` setting of the `Flavour` record:
197 ```haskell
198 userFlavour :: Flavour
199 userFlavour = defaultFlavour { name = "user", splitObjects = return False }
200 ```
201
202 Hadrian prints various progress info during the build. You can change the colours
203 used by default by overriding `buildProgressColour` and `successColour`:
204 ```haskell
205 -- | Set colour for build progress messages (e.g. executing a build command).
206 buildProgressColour :: BuildProgressColour
207 buildProgressColour = mkBuildProgressColour (Dull Magenta)
208
209 -- | Set colour for success messages (e.g. a package is built successfully).
210 successColour :: SuccessColour
211 successColour = mkSuccessColour (Dull Green)
212 ```
213
214 Your options are `Dull Colour`, `Vivid Colour`, or `Extended Code`. `Dull`
215 colours are the ANSI 8-bit colours, `Vivid` correspond to the 16-bit codes that
216 end with ";1", and `Extended` let's you enter a manual code for the 256 colour
217 set. E.g.
218
219 ```
220 Dull Blue
221 Vivid Cyan
222 Extended "203"
223 ```