1898dcd3aaf3f382ae6d7ea5b3e045f0bfe21142
[ghc.git] / doc / user-settings.md
1 **Note:** This document is currently out-of-date and will be fixed after
2 [a major refactoring](https://github.com/snowleopard/hadrian/issues/347).
3
4 # User settings
5
6 You can customise Hadrian by copying the file `hadrian/src/UserSettings.hs` to
7 `hadrian/UserSettings.hs` and overriding the default build settings (if you don't
8 copy the file your changes will be tracked by `git` and you can accidentally commit
9 them). Here we document currently supported settings.
10
11 ## Build directory
12
13 Hadrian puts build results into `_build` directory by default, which is
14 specified by `buildRootPath`:
15 ```haskell
16 -- | All build results are put into 'buildRootPath' directory.
17 buildRootPath :: FilePath
18 buildRootPath = "_build"
19 ```
20
21 ## Build flavour
22
23 Build _flavour_ is a collection of build settings that fully define a GHC build
24 (see `src/Flavour.hs`):
25 ```haskell
26 data Flavour = Flavour
27     { name               :: String    -- ^ Flavour name, to set from command line.
28     , args               :: Args      -- ^ Use these command line arguments.
29     , packages           :: Packages  -- ^ Build these packages.
30     , integerLibrary     :: Package   -- ^ Either 'integerGmp' or 'integerSimple'.
31     , libraryWays        :: Ways      -- ^ Build libraries these ways.
32     , rtsWays            :: Ways      -- ^ Build RTS these ways.
33     , splitObjects       :: Predicate -- ^ Build split objects.
34     , buildHaddock       :: Predicate -- ^ Build Haddock and documentation.
35     , dynamicGhcPrograms :: Bool      -- ^ Build dynamic GHC programs.
36     , ghciWithDebugger   :: Bool      -- ^ Enable GHCi debugger.
37     , ghcProfiled        :: Bool      -- ^ Build profiled GHC.
38     , ghcDebugged        :: Bool }    -- ^ Build GHC with debug information.
39 ```
40 Hadrian provides several
41 [built-in flavours](https://github.com/snowleopard/hadrian/blob/master/doc/flavours.md)
42 (`defaultFlavour`, `quickFlavour`, and
43 a few others), which can be activated from the command line, e.g. `--flavour=quick`.
44 Users can define new build flavours by adding them to `userFlavours` list:
45 ```haskell
46 userFlavour :: Flavour
47 userFlavour = defaultFlavour { name = "user", ... } -- modify the default build flavour
48
49 userFlavours :: [Flavour]
50 userFlavours = [userFlavour]
51 ```
52 Now `--flavour=user` will run Hadrian with `userFlavour` settings. In the
53 following sections we look at specific fields of the `Flavour` record in
54 more detail. Note: `defaultFlavour`, as well as its individual fields such
55 as `defaultArgs`, `defaultPackages`, etc. that we use below, are defined in module
56 `Settings.Default`. Import it as
57 `import {-# SOURCE #-} Settings.Default` to handle cyclic module dependencies. 
58
59 ## Command line arguments
60
61 One of the key features of Hadrian is that users can easily modify any build command.
62 The build system will detect the change and will rerun all
63 affected build rules during the next build, without requiring a full rebuild.
64
65 For example, here is how to pass an extra argument `-O0` to all invocations of
66 GHC when compiling package `cabal`:
67 ```haskell
68 userFlavour :: Flavour
69 userFlavour = defaultFlavour { name = "user", args = defaultArgs <> userArgs }
70
71 userArgs :: Args
72 userArgs = builder Ghc ? package cabal ? arg "-O0"
73 ```
74 Builders such as `Ghc` are defined in `src/Builder.hs`, and all packages that
75 are currently built as part of the GHC are defined in `src/GHC.hs`. See also
76 `src/Package.hs`.
77
78 You can combine several custom command line settings using `mconcat`:
79 ```haskell
80 userArgs :: Args
81 userArgs = mconcat
82     [ builder Ghc ? package cabal ? arg "-O0"
83     , package rts ? input "//Evac_thr.c" ? append [ "-DPARALLEL_GC", "-Irts/sm" ]
84     , builder Ghc ? output "//Prelude.*" ? remove ["-Wall", "-fwarn-tabs"] ]
85 ```
86 The above example also demostrates the use of `append` for adding more than one
87 argument and `remove` for removing arguments that Hadrian uses by default. You
88 can match any combination of the `builder`, `stage`, `package`, `way`, `input`
89 and `output` predicates when specifying custom command line arguments. File
90 patterns such as `"//Prelude.*"` can be used when matching input and output files,
91 where `//` matches an arbitrary number of path components and `*` matches an entire
92 path component, excluding any separators.
93
94 ## Packages
95
96 Users can add and remove packages from particular build stages. As an example,
97 below we add package `base` to Stage0 and remove package `haskeline` from Stage1:
98 ```haskell
99 userFlavour :: Flavour
100 userFlavour = defaultFlavour { name = "user", packages = defaultPackages <> userPackages }
101
102 userPackages :: Packages
103 userPackages = mconcat
104     [ stage0 ? append [base]
105     , stage1 ? remove [haskeline] ]
106 ```
107 If you are working on a new GHC package you need to let Hadrian know about it
108 by adding it to `userKnownPackages`:
109 ```haskell
110 userKnownPackages :: [Package]
111 userKnownPackages = [userPackage]
112
113 -- An example package that lives in "libraries/user-package" directory.
114 userPackage :: Package
115 userPackage = library "user-package"
116 ```
117 You will also need to add `userPackage` to a specific build stage by modifying
118 `userPackages` as otherwise it will not be built.
119
120 You can choose which integer library to use when builing GHC using the
121 `integerLibrary` setting of the build flavour. Possible values are: `integerGmp`
122 (default) and `integerSimple`.
123 ```haskell
124 simpleFlavour :: Flavour
125 simpleFlavour = defaultFlavour { name = "simple", integerLibrary = integerSimple }
126 ```
127 ## Build ways
128
129 Packages can be built in a number of ways, such as `vanilla`, `profiling` (with
130 profiling information enabled), and many others as defined in `src/Way.hs`. You
131 can change the default build ways by modifying `libraryWays` and `rtsWays` fields
132 of the `Flavour` record as required. As an example, below we remove `profiling`
133 from the list of library ways:
134 ```haskell
135 noProfilingFlavour :: Flavour
136 noProfilingFlavour = defaultFlavour
137     { name        = "no-profiling"
138     , libraryWays = defaultLibraryWays <> remove [profiling]
139     , ghcProfiled = False } -- Can't build profiled GHC without profiled libraries
140 ```
141 Note that `rtsWays` is computed from `libraryWays` by default, therefore the above
142 change will lead to the removal of `threadedProfiling` way from `rtsWays`. To
143 change this behaviour, you can override the default `rtsWays` setting.
144
145 ## Verbose command lines
146
147 By default Hadrian does not print full command lines during the build process
148 and instead prints short human readable digests for each executed command. You
149 can suppress this behaviour completely or partially using `verboseCommands` setting:
150 ```haskell
151 -- | Set to True to print full command lines during the build process. Note,
152 -- this is a Predicate, hence you can enable verbose output only for certain
153 -- targets, e.g.: @verboseCommands = package ghcPrim@.
154 verboseCommands :: Predicate
155 verboseCommands = return False
156 ```
157 For example, to print the full command lines used to compile GHC executables,
158 set `verboseCommands` to:
159 ```haskell
160 verboseCommands :: Predicate
161 verboseCommands = input "ghc/Main.hs"
162 ```
163 Below are a few other examples:
164 ```haskell
165 -- Print command lines for all Ghc Link invocations:
166 verboseCommands = builder (Ghc Link)
167
168 -- Print command lines when compiling files in package compiler using Gcc:
169 verboseCommands = builder (Gcc Compile) &&^ package compiler
170
171 -- Use patterns when matching files:
172 verboseCommands = output "//rts/sm/*" &&^ way threaded
173
174 -- Print all commands:
175 verboseCommands = return True
176 ```
177
178 ## Miscellaneous
179
180 To change the default behaviour of Hadrian with respect to building split
181 objects and Haddock documentation, override `splitObjects` and `buildHaddock`
182 fields of the `Flavour` record, for example:
183 ```haskell
184 userFlavour :: Flavour
185 userFlavour = defaultFlavour { name = "user", splitObjects = return False, buildHaddock = return True }
186 ```
187
188 Hadrian prints various progress info during the build. You can customise how this
189 info is printed by overriding `putBuild` and `putSuccess` commands:
190
191 ```haskell
192 -- | Customise build progress messages (e.g. executing a build command).
193 putBuild :: String -> Action ()
194 putBuild = putColoured Vivid White
195
196 -- | Customise build success messages (e.g. a package is built successfully).
197 putSuccess :: String -> Action ()
198 putSuccess = putColoured Vivid Green
199 ```
200
201 You can tune colours for your favourite terminal and also change the verbosity
202 level, e.g. by setting `putSuccess = putLoud`, which will hide success messages
203 unless Hadrian is called with `--verbose` flag.