Add a paragraph on customising progress messages
[ghc.git] / doc / user-settings.md
1 # User settings
2
3 You can customise Hadrian by specifying user build settings in file
4 `src/Settings/User.hs`. Here we document currently supported settings.
5
6 ## Build directory
7
8 Hadrian puts build results into `_build` directory by default, which is
9 specified by `buildRootPath`:
10 ```haskell
11 -- | All build results are put into 'buildRootPath' directory.
12 buildRootPath :: FilePath
13 buildRootPath = "_build"
14 ```
15
16 ## Command line arguments
17
18 One of the key features of Hadrian is that users can modify any build command by
19 changing `userArgs`. The build system will detect the change and will rerun all
20 affected build rules during the next build, without requiring a full rebuild.
21
22 For example, here is how to pass an extra argument `-O0` to all invocations of
23 GHC when compiling package `cabal`:
24 ```haskell
25 -- | Modify default build command line arguments.
26 userArgs :: Args
27 userArgs = builder Ghc ? package cabal ? arg "-O0"
28 ```
29 Builders such as `Ghc` are defined in `src/Builder.hs`, and all packages that
30 are currently built as part of the GHC are defined in `src/GHC.hs`. See also
31 `src/Package.hs`.
32
33 You can combine several custom command line settings using `mconcat`:
34 ```haskell
35 userArgs :: Args
36 userArgs = mconcat
37     [ builder Ghc ? package cabal ? arg "-O0"
38     , package rts ? input "//Evac_thr.c" ? append [ "-DPARALLEL_GC", "-Irts/sm" ]
39     , builder Ghc ? output "//Prelude.*" ? remove ["-Wall", "-fwarn-tabs"] ]
40 ```
41 The above example also demostrates the use of `append` for adding more than one
42 argument and `remove` for removing arguments that Hadrian uses by default. You
43 can match any combination of the `builder`, `stage`, `package`, `way`, `input`
44 and `output` predicates when specifying custom command line arguments. File
45 patterns such as `"//Prelude.*"` can be used when matching input and output files,
46 where `//` matches an arbitrary number of path components and `*` matches an entire
47 path component, excluding any separators.
48
49 ## Packages
50
51 To add or remove a package from a particular build stage, use `userPackages`. As
52 an example, below we add package `base` to Stage0 and remove package `haskeline`
53 from Stage1:
54 ```haskell
55 -- | Modify the set of packages that are built by default in each stage.
56 userPackages :: Packages
57 userPackages = mconcat
58     [ stage0 ? append [base]
59     , stage1 ? remove [haskeline] ]
60 ```
61 If you are working on a new GHC package you need to let Hadrian know about it
62 by setting `userKnownPackages`:
63 ```haskell
64 -- | Add user defined packages. Don't forget to add them to 'userPackages' too.
65 userKnownPackages :: [Package]
66 userKnownPackages = [myPackage]
67
68 -- An example package that lives in "libraries/my-package" directory.
69 myPackage :: Package
70 myPackage = library "my-package"
71 ```
72 Note, you will also need to add `myPackage` to a specific build stage by modifying
73 `userPackages` as otherwise it will not be built.
74
75 You can choose which integer library to use when builing GHC by setting
76 `integerLibrary`. Possible values are: `integerGmp` (default) and `integerSimple`.
77 ```haskell
78 -- | Choose the integer library: 'integerGmp' or 'integerSimple'.
79 integerLibrary :: Package
80 integerLibrary = integerGmp
81 ```
82 ## Build ways
83
84 Packages can be built in a number of ways, such as `vanilla`, `profiling` (with
85 profiling information enabled), and many others as defined in `src/Way.hs`. You
86 can change the default build ways using `userLibraryWays` and `userRtsWays` settings.
87 As an example, below we remove `dynamic` from the list of library ways but keep
88 `rts` package ways unchanged:
89 ```haskell
90 -- | Modify the set of ways in which library packages are built.
91 userLibraryWays :: Ways
92 userLibraryWays = remove [dynamic]
93
94 -- | Modify the set of ways in which the 'rts' package is built.
95 userRtsWays :: Ways
96 userRtsWays = mempty
97 ```
98
99 ## Verbose command lines
100
101 By default Hadrian does not print full command lines during the build process
102 and instead prints short human readable digests for each executed command. You
103 can suppress this behaviour completely or partially using `verboseCommands` setting:
104 ```haskell
105 -- | Set to True to print full command lines during the build process. Note,
106 -- this is a Predicate, hence you can enable verbose output only for certain
107 -- targets, e.g.: @verboseCommands = package ghcPrim@.
108 verboseCommands :: Predicate
109 verboseCommands = return False
110 ```
111 For example, to print the full command lines used to compile GHC executables,
112 set `verboseCommands` to:
113 ```haskell
114 verboseCommands :: Predicate
115 verboseCommands = input "ghc/Main.hs"
116 ```
117 Below are a few other examples:
118 ```haskell
119 -- Print command lines for all Ghc Link invocations:
120 verboseCommands = builder (Ghc Link)
121
122 -- Print command lines when compiling files in package compiler using Gcc:
123 verboseCommands = builder (Gcc Compile) &&^ package compiler
124
125 -- Use patterns when matching files:
126 verboseCommands = output "//rts/sm/*" &&^ way threaded
127
128 -- Print all commands:
129 verboseCommands = return True
130 ```
131
132 ## Miscellaneous
133
134 Use the following settings to change the default behaviour of Hadrian with respect
135 to building split objects and Haddock documentation.
136
137 ```haskell
138 -- | Control when split objects are generated. Note, due to the GHC bug #11315
139 -- it is necessary to do a full clean rebuild when changing this option.
140 splitObjects :: Predicate
141 splitObjects = (return cmdSplitObjects) &&^ defaultSplitObjects
142
143 -- | Control when to build Haddock documentation.
144 buildHaddock :: Predicate
145 buildHaddock = return cmdBuildHaddock
146 ```
147
148 Hadrian prints various progress info during the build. You can customise how this
149 info is printed by overriding `putBuild` and `putSuccess` commands:
150
151 ```haskell
152 -- | Customise build progress messages (e.g. executing a build command).
153 putBuild :: String -> Action ()
154 putBuild = putColoured Vivid White
155
156 -- | Customise build success messages (e.g. a package is built successfully).
157 putSuccess :: String -> Action ()
158 putSuccess = putColoured Vivid Green
159 ```
160
161 You can tune colours for your favourite terminal and also change the verbosity
162 level, e.g. by setting `putSuccess = putLoud`, which will hide success messages
163 unless Hadrian is called with `--verbose` flag.