0865c5bf53962bd17bc88950a8d0146d58f21146
[ghc.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 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 :: 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 (`defaultFlavour`, `quickFlavour`, 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. In the
52 following sections we look at specific fields of the `Flavour` record in
53 more detail. Note: `defaultFlavour`, as well as its individual fields such
54 as `defaultArgs`, `defaultPackages`, etc. that we use below, are defined in module
55 `Settings.Default`.
56
57 ## Command line arguments
58
59 One of the key features of Hadrian is that users can easily modify any build command.
60 The build system will detect the change and will rerun all affected build rules during
61 the next build, without requiring a full rebuild.
62
63 For example, here is how to pass an extra argument `-O0` to all invocations of
64 GHC when compiling package `cabal`:
65 ```haskell
66 userFlavour :: Flavour
67 userFlavour = defaultFlavour { name = "user", args = defaultArgs <> userArgs }
68
69 userArgs :: Args
70 userArgs = builder Ghc ? package cabal ? arg "-O0"
71 ```
72 Builders such as `Ghc` are defined in `src/Builder.hs`, and all packages that
73 are currently built as part of the GHC are defined in `src/GHC.hs`.
74
75 You can combine several custom command line settings using `mconcat`:
76 ```haskell
77 userArgs :: Args
78 userArgs = mconcat
79     [ builder Ghc ? package cabal ? arg "-O0"
80     , package rts ? input "//PrimOps.c" ? pure ["-fno-PIC", "-static"] ]
81 ```
82 You can match any combination of the `builder`, `stage`, `package`, `way`, `input`
83 and `output` predicates when specifying custom command line arguments. File
84 patterns such as `"//Prelude.*"` can be used when matching input and output files,
85 where `//` matches an arbitrary number of path components and `*` matches an entire
86 path component, excluding any separators.
87
88 ## Packages
89
90 Users can add and remove packages from particular build stages. As an example,
91 below we add package `base` to Stage0 and remove package `haskeline` from Stage1:
92 ```haskell
93 userFlavour :: Flavour
94 userFlavour = defaultFlavour { name = "user", packages = modifiedPackages }
95
96 modifiedPackages :: Stage -> Action [Package]
97 modifiedPackages stage = do
98     packages <- defaultPackages stage
99     return $ case stage of
100         Stage0 -> packages ++ [base]
101         Stage1 -> packages \\ [haskeline]
102         _      -> packages
103 ```
104 If you are working on a new GHC package you need to let Hadrian know about it
105 by adding it to `userPackages`:
106 ```haskell
107 userPackages :: [Package]
108 userPackages = [userPackage]
109
110 -- An example package that lives in "libraries/user-package" directory.
111 userPackage :: Package
112 userPackage = library "user-package"
113 ```
114 You will also need to add `userPackage` to a specific build stage by modifying
115 the `packages` setting of the user flavour as otherwise it will not be built.
116
117 You can choose which integer library to use when builing GHC using the
118 `integerLibrary` setting of the build flavour. Possible values are: `integerGmp`
119 (default) and `integerSimple`.
120 ```haskell
121 userFlavour :: Flavour
122 userFlavour = defaultFlavour { name = "user", integerLibrary = integerSimple }
123 ```
124 ## Build ways
125
126 Packages can be built in a number of ways, such as `vanilla`, `profiling` (with
127 profiling information enabled), and many others as defined in `src/Way.hs`. You
128 can change the default build ways by modifying `libraryWays` and `rtsWays` fields
129 of the `Flavour` record as required. As an example, below we remove `profiling`
130 from the list of library ways:
131 ```haskell
132 noProfilingFlavour :: Flavour
133 noProfilingFlavour = defaultFlavour
134     { name        = "no-profiling"
135     , libraryWays = remove [profiling] defaultLibraryWays
136     , ghcProfiled = False } -- Can't build profiled GHC without profiled libraries
137 ```
138 Note that `rtsWays` is computed from `libraryWays` by default, therefore the above
139 change will lead to the removal of `threadedProfiling` way from `rtsWays`. To
140 change this behaviour, you can override the default `rtsWays` setting.
141
142 Similarly, if we want to completely turn off dynamic linking,
143 we can define a custom `Flavour` to this effect:
144 ``` haskell
145 noDynamicFlavour :: Flavour
146 noDynamicFlavour = defaultFlavour
147   { name = "no-dynamic"
148   , libraryWays = remove [dynamic] defaultLibraryWays
149   }
150 ```
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 and Stage2
190 utilities such as `haddock`. Note that all Stage0 and Stage1 libraries will
191 still be built.
192
193 To change the default behaviour of Hadrian with respect to building split
194 objects, override the `splitObjects` setting of the `Flavour` record:
195 ```haskell
196 userFlavour :: Flavour
197 userFlavour = defaultFlavour { name = "user", splitObjects = return False }
198 ```
199
200 Hadrian prints various progress info during the build. You can change the colours
201 used by default by overriding `buildProgressColour` and `successColour`:
202 ```haskell
203 -- | Set colour for build progress messages (e.g. executing a build command).
204 buildProgressColour :: BuildProgressColour
205 buildProgressColour = mkBuildProgressColour (Dull Magenta)
206
207 -- | Set colour for success messages (e.g. a package is built successfully).
208 successColour :: SuccessColour
209 successColour = mkSuccessColour (Dull Green)
210 ```
211
212 Your options are `Dull Colour`, `Vivid Colour`, or `Extended Code`. `Dull`
213 colours are the ANSI 8-bit colours, `Vivid` correspond to the 16-bit codes that
214 end with ";1", and `Extended` let's you enter a manual code for the 256 colour
215 set. E.g.
216
217 ```
218 Dull Blue
219 Vivid Cyan
220 Extended "203"
221 ```