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