user-settings.md 16.2 KB
Newer Older
1
# Settings
2

3
You can customise Hadrian in two ways:
4

5 6 7 8 9 10 11 12
- by copying the file `hadrian/src/UserSettings.hs` to `hadrian/UserSettings.hs`
  and overriding the default build settings (if you don't
  copy the file your changes will be tracked by `git` and you can accidentally commit
  them). Here we document currently supported settings.

## The `UserSettings` module

### Build flavour
13

Andrey Mokhov's avatar
Andrey Mokhov committed
14 15
Build _flavour_ is a collection of build settings that fully define a GHC build
(see `src/Flavour.hs`):
16
```haskell
Andrey Mokhov's avatar
Andrey Mokhov committed
17 18 19 20 21 22 23 24 25 26 27 28 29 30
data Flavour = Flavour {
    -- | Flavour name, to select this flavour from command line.
    name :: String,
    -- | Use these command line arguments.
    args :: Args,
    -- | Build these packages.
    packages :: Stage -> Action [Package],
    -- | Either 'integerGmp' or 'integerSimple'.
    integerLibrary :: Action Package,
    -- | Build libraries these ways.
    libraryWays :: Ways,
    -- | Build RTS these ways.
    rtsWays :: Ways,
    -- | Build dynamic GHC programs.
31
    dynamicGhcPrograms :: Action Bool,
Andrey Mokhov's avatar
Andrey Mokhov committed
32 33 34 35 36
    -- | Enable GHCi debugger.
    ghciWithDebugger :: Bool,
    -- | Build profiled GHC.
    ghcProfiled :: Bool,
    -- | Build GHC with debug information.
37
    ghcDebugged :: Bool
Ben Gamari's avatar
Ben Gamari committed
38 39
    -- | Build the GHC executable against the threaded runtime system.
    ghcThreaded :: Bool,
40 41 42
    -- | Whether to build docs and which ones
    --   (haddocks, user manual, haddock manual)
    ghcDocs :: Action DocTargets }
43
```
44
Hadrian provides several built-in flavours (`default`, `quick`, and a few
Andrey Mokhov's avatar
Andrey Mokhov committed
45 46 47
others; see `hadrian/doc/flavours.md`), which can be activated from the command line,
e.g. by passing `--flavour=quick`. Users can define new build flavours by adding them
to `userFlavours` list:
48
```haskell
Andrey Mokhov's avatar
Andrey Mokhov committed
49
-- | User-defined build flavours. See 'userFlavour' as an example.
50
userFlavours :: [Flavour]
Andrey Mokhov's avatar
Andrey Mokhov committed
51 52 53 54 55 56
userFlavours = [userFlavour] -- Add more build flavours if need be.

-- | This is an example user-defined build flavour. Feel free to modify it and
-- use by passing @--flavour=user@ from the command line.
userFlavour :: Flavour
userFlavour = defaultFlavour { name = "user" } -- Modify other settings here.
57
```
58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75
Now `--flavour=user` will run Hadrian with `userFlavour` settings.

When no `--flavour` argument is passed to hadrian, it will use the
`default` one. You can however change this, and for example make
the "fallback" flavour be `user`, by changing `userDefaultFlavour`:

``` haskell
userDefaultFlavour :: String
-- before:
-- userDefaultFlavour = "default"
-- now:
userDefaultFlavour = "user"
```

This saves you from having to type `build --flavour=user [...]`
every time, allowing you to _persist_ the choice of flavour.

In the
Andrey Mokhov's avatar
Andrey Mokhov committed
76 77 78
following sections we look at specific fields of the `Flavour` record in
more detail. Note: `defaultFlavour`, as well as its individual fields such
as `defaultArgs`, `defaultPackages`, etc. that we use below, are defined in module
Andrey Mokhov's avatar
Andrey Mokhov committed
79
`Settings.Default`.
80

81 82
## Command line arguments

Andrey Mokhov's avatar
Andrey Mokhov committed
83
One of the key features of Hadrian is that users can easily modify any build command.
Andrey Mokhov's avatar
Andrey Mokhov committed
84 85
The build system will detect the change and will rerun all affected build rules during
the next build, without requiring a full rebuild.
86 87 88 89

For example, here is how to pass an extra argument `-O0` to all invocations of
GHC when compiling package `cabal`:
```haskell
90 91 92
userFlavour :: Flavour
userFlavour = defaultFlavour { name = "user", args = defaultArgs <> userArgs }

93 94 95 96
userArgs :: Args
userArgs = builder Ghc ? package cabal ? arg "-O0"
```
Builders such as `Ghc` are defined in `src/Builder.hs`, and all packages that
97
are currently built as part of the GHC are defined in `src/Packages.hs`.
98 99 100 101 102 103

You can combine several custom command line settings using `mconcat`:
```haskell
userArgs :: Args
userArgs = mconcat
    [ builder Ghc ? package cabal ? arg "-O0"
104
    , package rts ? input "**/PrimOps.c" ? pure ["-fno-PIC", "-static"] ]
105
```
Andrey Mokhov's avatar
Andrey Mokhov committed
106
You can match any combination of the `builder`, `stage`, `package`, `way`, `input`
107
and `output` predicates when specifying custom command line arguments. File
108
patterns such as `"**/Prelude.*"` can be used when matching input and output files,
109
where `**` matches an arbitrary number of path components, but not absolute path
110
prefixes, and `*` matches an entire path component, excluding any separators.
111

112
#### Enabling -Werror
113 114 115 116 117 118 119 120 121 122

It is useful to enable `-Werror` when building GHC as this setting is
used in the CI to ensure a warning free build. The `werror` function can be
used to easily modify a flavour to turn this setting on.

```
devel2WerrorFlavour :: Flavour
devel2WerrorFlavour = werror (developmentFlavour Stage2)
```

123
#### Linking GHC against the debugged RTS
124 125 126 127 128 129 130 131 132 133 134 135 136 137

What was previously achieved by having `GhcDebugged=YES` in `mk/build.mk` can
be done by defining a custom flavour in the user settings file, one that
sets the `ghcDebugged` field of `Flavour` to `True`, e.g:

``` haskell
quickDebug :: Flavour
quickDebug = quickFlavour { name = "dbg", ghcDebugged = True }
```

Running `build --flavour=dbg` will build a `quick`-flavoured GHC and link
GHC, iserv, iserv-proxy and remote-iserv against the debugged RTS, by passing
`-debug` to the commands that link those executables.

138
### Packages
139

140 141
Users can add and remove packages from particular build stages. As an example,
below we add package `base` to Stage0 and remove package `haskeline` from Stage1:
142
```haskell
143 144 145 146
...
import Packages
...

147
userFlavour :: Flavour
Andrey Mokhov's avatar
Andrey Mokhov committed
148 149 150 151 152 153 154 155 156
userFlavour = defaultFlavour { name = "user", packages = modifiedPackages }

modifiedPackages :: Stage -> Action [Package]
modifiedPackages stage = do
    packages <- defaultPackages stage
    return $ case stage of
        Stage0 -> packages ++ [base]
        Stage1 -> packages \\ [haskeline]
        _      -> packages
157 158
```
If you are working on a new GHC package you need to let Hadrian know about it
Andrey Mokhov's avatar
Andrey Mokhov committed
159
by adding it to `userPackages`:
160
```haskell
Andrey Mokhov's avatar
Andrey Mokhov committed
161 162
userPackages :: [Package]
userPackages = [userPackage]
163

164 165 166
-- An example package that lives in "libraries/user-package" directory.
userPackage :: Package
userPackage = library "user-package"
167
```
Andrey Mokhov's avatar
Andrey Mokhov committed
168
You will also need to add `userPackage` to a specific build stage by modifying
Andrey Mokhov's avatar
Andrey Mokhov committed
169
the `packages` setting of the user flavour as otherwise it will not be built.
170

171
You can choose which integer library to use when building GHC using the
172 173
`integerLibrary` setting of the build flavour. Possible values are: `integerGmp`
(default) and `integerSimple`.
174
```haskell
Andrey Mokhov's avatar
Andrey Mokhov committed
175
userFlavour :: Flavour
176
userFlavour = defaultFlavour { name = "user", integerLibrary = pure integerSimple }
177
```
178

179
#### Specifying the final stage to build
180 181 182 183 184 185 186 187 188 189 190 191 192 193

The `finalStage` variable can be set to indicate after which stage we should
stop the compilation pipeline. By default it is set to `Stage2` which indicates
that we will build everything which uses the `Stage1` `ghc` and then stop.

```
finalStage :: Stage
finalStage = Stage2
```

Using this mechanism we can also build a `Stage3` compiler by setting
`finalStage = Stage3` or just a `Stage1` compiler by setting
`finalStage = Stage1`.

194
### Build ways
195 196 197

Packages can be built in a number of ways, such as `vanilla`, `profiling` (with
profiling information enabled), and many others as defined in `src/Way.hs`. You
198
can change the default build ways by modifying `libraryWays` and `rtsWays` fields
199 200
of the `Flavour` record as required. As an example, below we remove `profiling`
from the list of library ways:
201
```haskell
202 203 204
noProfilingFlavour :: Flavour
noProfilingFlavour = defaultFlavour
    { name        = "no-profiling"
Andrey Mokhov's avatar
Andrey Mokhov committed
205
    , libraryWays = remove [profiling] defaultLibraryWays
206
    , ghcProfiled = False } -- Can't build profiled GHC without profiled libraries
207
```
208 209 210
Note that `rtsWays` is computed from `libraryWays` by default, therefore the above
change will lead to the removal of `threadedProfiling` way from `rtsWays`. To
change this behaviour, you can override the default `rtsWays` setting.
211

Andrey Mokhov's avatar
Andrey Mokhov committed
212 213
Similarly, if we want to completely turn off dynamic linking, we can define a custom
`Flavour` to this effect:
214 215 216
``` haskell
noDynamicFlavour :: Flavour
noDynamicFlavour = defaultFlavour
Andrey Mokhov's avatar
Andrey Mokhov committed
217 218
    { name = "no-dynamic"
    , libraryWays = remove [dynamic] defaultLibraryWays }
219 220
```

221
### Verbose command lines
222 223 224

By default Hadrian does not print full command lines during the build process
and instead prints short human readable digests for each executed command. You
Andrey Mokhov's avatar
Andrey Mokhov committed
225
can suppress this behaviour completely or partially using `verboseCommand` setting:
226
```haskell
Andrey Mokhov's avatar
Andrey Mokhov committed
227 228 229 230 231 232 233
-- | Set to 'True' to print full command lines during the build process. Note:
-- this is a 'Predicate', hence you can enable verbose output only for certain
-- targets, e.g.: @verboseCommand = package ghcPrim@.
verboseCommand :: Predicate
verboseCommand = do
    verbosity <- expr getVerbosity
    return $ verbosity >= Loud
234 235 236 237
```
For example, to print the full command lines used to compile GHC executables,
set `verboseCommands` to:
```haskell
Andrey Mokhov's avatar
Andrey Mokhov committed
238 239
verboseCommand :: Predicate
verboseCommand = input "ghc/Main.hs"
240 241 242 243
```
Below are a few other examples:
```haskell
-- Print command lines for all Ghc Link invocations:
Andrey Mokhov's avatar
Andrey Mokhov committed
244
verboseCommand = builder (Ghc Link)
245 246

-- Print command lines when compiling files in package compiler using Gcc:
Andrey Mokhov's avatar
Andrey Mokhov committed
247
verboseCommand = builder (Gcc Compile) &&^ package compiler
248 249

-- Use patterns when matching files:
250
verboseCommand = output "**/rts/sm/*" &&^ way threaded
251 252

-- Print all commands:
Andrey Mokhov's avatar
Andrey Mokhov committed
253
verboseCommand = return True
254 255
```

256
### Documentation
257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294

`Flavour`'s `ghcDocs :: Action DocTargets` field lets you
customize the "groups" of documentation targets that should
run when running `build docs` (or, transitively,
`build binary-dist`).

```haskell
type DocTargets = Set DocTarget
data DocTarget = Haddocks | SphinxHTML | SphinxPDFs | SphinxMan
```

By default, `ghcDocs` contains all of them and `build docs` would
therefore attempt to build all the haddocks, manuals and manpages.
If, for some reason (e.g no easy way to install `sphinx-build` or
`xelatex` on your system), you're just interested in building the
haddocks, you could define a custom flavour as follows:

```haskell
justHaddocksFlavour :: Flavour
justHaddocksFlavour = defaultFlavour
    { name = "default-haddocks"
	, ghcDocs = Set.singleton Haddocks }
```

and then run `build --flavour=default-haddocks`. Alternatively,
you can use the `--docs` CLI flag to selectively disable some or
all of the documentation targets:

- `--docs=none`: don't build any docs
- `--docs=no-haddocks`: don't build haddocks
- `--docs=no-sphinx`: don't build any user manual or manpage
- `--docs=no-sphinx-html`: don't build HTML versions of manuals
- `--docs=no-sphinx-pdfs`: don't build PDF versions of manuals
- `--docs=no-sphinx-man`: don't build the manpage

You can pass several `--docs=...` flags, Hadrian will combine
their effects.

295
### Split sections
296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320

You can build all or just a few packages with
[`-split-sections`][split-sections] by tweaking an existing
flavour (whichever matches your needs) using
`splitSections` or `splitSectionsIf`:

``` haskell
splitSections :: Flavour -> Flavour
splitSectionsIf :: (Package -> Bool) -> Flavour -> Flavour
```

For example, you can easily start with the `quick` flavour and
additionally build all Haskell packages with `-split-sections` by defining a new
flavour as
`(splitSectionsIf (const True) quickFlavour) { name = "quick-split" }`.
You can then start a build with this flavour with `build --flavour=quick-split`.

Changing `(const True)` to `(== base)` would only build `base` with
`-split-sections`, not all Haskell packages as with `quick-split` above.

`splitSections` is simply `splitSectionsIf` applied to the predicate
`(/=ghc)`, i.e it builds all Haskell packages but the `ghc`
library with `-split-sections` (it is usually not worth using that
option with the `ghc` library).

321
### Miscellaneous
322

Andrey Mokhov's avatar
Andrey Mokhov committed
323 324
Hadrian prints various progress info during the build. You can change the colours
used by default by overriding `buildProgressColour` and `successColour`:
325
```haskell
Andrey Mokhov's avatar
Andrey Mokhov committed
326 327
-- | Set colour for build progress messages (e.g. executing a build command).
buildProgressColour :: BuildProgressColour
328
buildProgressColour = mkBuildProgressColour (Dull Magenta)
329

Andrey Mokhov's avatar
Andrey Mokhov committed
330 331
-- | Set colour for success messages (e.g. a package is built successfully).
successColour :: SuccessColour
332 333 334 335 336 337 338 339 340 341 342 343
successColour = mkSuccessColour (Dull Green)
```

Your options are `Dull Colour`, `Vivid Colour`, or `Extended Code`. `Dull`
colours are the ANSI 8-bit colours, `Vivid` correspond to the 16-bit codes that
end with ";1", and `Extended` let's you enter a manual code for the 256 colour
set. E.g.

```
Dull Blue
Vivid Cyan
Extended "203"
344
```
345

346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370
## `key = value` and `key += value` style settings

One can alternatively supply settings from the command line or a
`<build root>/hadrian.settings` file. Hadrian currently supports two
"families" of settings:

- `{stage0, ..., stage3, *}.(<package name> or *).ghc.{c, hs, link, deps, toolargs, *}.opts`
- `{stage0, ..., stage3, *}.(<package name> or *).cc.{c, deps, *}.opts`

For example, putting the following in a file at `_build/hadrian.settings`:

``` make
stage1.ghc-bin.ghc.link.opts += -eventlog
*.base.ghc.*.opts += -v3
```

and running hadrian with the default build root (`_build`), would respectively
link the stage 2 GHC executable (using the stage 1 GHC) with the `-eventlog`
flag, so that stage 2 GHC supports producing eventlogs with `+RTS -l`, and use
`-v3` on all GHC commands used to build anything related to `base`, whatever
the stage.

We could equivalently specify those settings on the command-line:

``` sh
371
$ hadrian/build "stage1.ghc-bin.ghc.link.opts += -eventlog" \
372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389
                   "*.base.ghc.*.opts += -v3"
```

or specify some in `hadrian.settings` and some on the command-line.

Here is an overview of the supported settings and how you can figure out
the right names for them:

- the stage slot, which comes first, can be filled with any of `stage0`,
  `stage1`, `stage2`, `stage3` or `*`; any value but `*` will restrict the
  setting update to targets built during the given stage, while `*` is taken
  to mean "for any stage".
- the package slot, which comes second, can be filled with any package name
  that Hadrian knows about (all packages that are part of a GHC checkout),
  or `*`, to respectively mean that the builder options are going to be updated
  only when building the given package, or that the said options should be used
  when building all known packages, if the Hadrian command ever gets them to be
  built;
390
- the remaining slots specify the builder and how it was invoked,
391

392
  * `ghc` refers to GHC commands; the final slot refers to how GHC is invoked:
393

394 395 396 397 398 399
    * `c.opts` for commands that build C files with GHC
	  * `hs.opts` for commands that compile Haskell modules with GHC
	  * `link.opts` for GHC linking command
	  * `deps.opts` for commands that figure out dependencies between Haskell modules
	    (with `ghc -M`)
	  * `toolargs.opts` for GHC commands that are used to generate the right ghci
400
	    argument for `hadrian/ghci` to work
401

402
  * `cc` refers to C compiler commands
403

404 405 406 407 408 409
    * `c.opts` for commands that call the C compiler on some C files
	  * `deps.opts` for commands that call the C compiler for figuring out
	    dependencies between C files

  * `cabal.configure.opts` refers to Cabal configure command line. Note that
    package flags can be given by adding `--flags=...` arguments.
410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428

- using a wildcard (`*`) ranges over all possible values for a given "slot";
- `=` entirely overrides the arguments for a given builder in a given context,
  with the value specified on the right hand side of `=`, while `+=` merely
  extends the arguments that are to be emitted in the said context, with
  the values supplied on the right hand side of `+=`.

See `Note [Hadrian settings]` in `hadrian/src/Settings.hs` for explanations
about the implementation and how the set of supported settings can be
extended.

### Tab completion

Hadrian supports tab-completion for the key-value settings. This is implemented
in `Rules.SimpleTargets.completionRule`, by exporting an `autocomplete` target
that takes an (optional) argument, `--complete-setting=<some string>`, and
prints on stdout all the setting keys that have the given string as a prefix.

There is a `hadrian/completion.sh` script that makes use of this rule to
429
install Bash completions for `hadrian/build` and `hadrian/build-cabal`.
430 431 432 433
You can try it out by doing:

``` sh
$ source hadrian/completion.sh
434 435 436 437
$ hadrian/build <TAB>
$ hadrian/build stage1.ba<TAB>
$ hadrian/build "stage1.base.ghc.<TAB>
$ hadrian/build "*.*.ghc.*.opts += -v3" "stage0.ghc-bin.ghc.lin<TAB>
438 439
```

440
[split-sections]: https://downloads.haskell.org/~ghc/latest/docs/html/users_guide/phases.html#ghc-flag--split-sections