Use Cabal directly in place of ghc-cabal + make build root configurable (#531)
[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 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 (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 ```