Minor revision
authorAndrey Mokhov <andrey.mokhov@gmail.com>
Sat, 14 May 2016 17:10:51 +0000 (18:10 +0100)
committerAndrey Mokhov <andrey.mokhov@gmail.com>
Sat, 14 May 2016 17:10:51 +0000 (18:10 +0100)
[skip ci]

doc/user-settings.md

index a7f1469..e9bea77 100644 (file)
@@ -1,12 +1,12 @@
 # User settings\r
 \r
-Users can customise Hadrian by specifying user build settings in file\r
+You can customise Hadrian by specifying user build settings in file\r
 `src/Settings/User.hs`. Here we document currently supported settings.\r
 \r
 ## Build directory\r
 \r
 Hadrian puts build results into `_build` directory by default, which is\r
-controlled by `buildRootPath`:\r
+specified by `buildRootPath`:\r
 ```haskell\r
 -- | All build artefacts are stored in 'buildRootPath' directory.\r
 buildRootPath :: FilePath\r
@@ -19,7 +19,7 @@ One of the key features of Hadrian is that users can modify any build command by
 changing `userArgs`. The build system will detect the change and will rerun all\r
 affected build rules during the next build, without requiring a full rebuild.\r
 \r
-As an example, here is how to pass an extra argument `-O0` to all invocations of\r
+For example, here is how to pass an extra argument `-O0` to all invocations of\r
 GHC when compiling package `cabal`:\r
 ```haskell\r
 -- | Control user-specific command line arguments.\r
@@ -27,24 +27,24 @@ userArgs :: Args
 userArgs = builder Ghc ? package cabal ? arg "-O0"\r
 ```\r
 Builders such as `Ghc` are defined in `src/Builder.hs`, and all packages that\r
-are currently built as part of the GHC are defined in `src/GHC.hs` (also see\r
-`src/Package.hs`).\r
+are currently built as part of the GHC are defined in `src/GHC.hs`. See also\r
+`src/Package.hs`.\r
 \r
-It is possible to specify several custom command line arguments combining the\r
-list with `mconcat`:\r
+You can combine several custom command line settings using `mconcat`:\r
 ```haskell\r
 userArgs :: Args\r
 userArgs = mconcat \r
     [ builder Ghc ? package cabal ? arg "-O0"\r
-    , package rts ? input "//Evac\_thr.c" ? append [ "-DPARALLEL\_GC", "-Irts/sm" ]\r
-    , builder Ghc ? output "//Prelude.\*" ? remove ["-Wall", "-fwarn-tabs"] ]\r
+    , package rts ? input "//Evac_thr.c" ? append [ "-DPARALLEL_GC", "-Irts/sm" ]\r
+    , builder Ghc ? output "//Prelude.*" ? remove ["-Wall", "-fwarn-tabs"] ]\r
 ```\r
 The above example also demostrates the use of `append` for adding more than one\r
-argument and `remove` for removing arguments that Hadrian uses by default. It is\r
-possible to match any combination of the current `builder`, `stage`, `package`,\r
-`way`, `input` and `output` using predicates. File patterns such as\r
-`"//Prelude.\*"` can be used when matching input and output files where `//`\r
-matches an arbitrary number of path components and `\*` matches an entire path component, excluding any separators.\r
+argument and `remove` for removing arguments that Hadrian uses by default. You\r
+can match any combination of the `builder`, `stage`, `package`, `way`, `input`\r
+and `output` when specifying custom command line arguments. File patterns such as\r
+`"//Prelude.*"` can be used when matching input and output files where `//`\r
+matches an arbitrary number of path components and `*` matches an entire path\r
+component, excluding any separators.\r
 \r
 ## Packages\r
 \r
@@ -63,20 +63,27 @@ by setting `userKnownPackages`:
 ```haskell\r
 -- | Add new user-defined packages.\r
 userKnownPackages :: [Package]\r
-userKnownPackages = []\r
+userKnownPackages = [myPackage]\r
+\r
+-- An example package that lives in "libraries/my-package" directory.\r
+myPackage :: Package\r
+myPackage = library "my-package"\r
 ```\r
-To control which integer library to use when builing GHC, set `integerLibrary`:\r
+Note, you will also need to add it to a specific build stage by modifying\r
+`userPackages` as otherwise it will not be built.\r
+\r
+You can choose which integer library to use when builing GHC by setting\r
+`integerLibrary`:\r
 ```haskell\r
 -- | Choose the integer library: integerGmp or integerSimple.\r
 integerLibrary :: Package\r
 integerLibrary = integerGmp\r
 ```\r
-\r
 ## Build ways\r
 \r
 Libraries can be built in a number of ways, such as `vanilla`, `profiling` (with \r
 profiling information enabled), and many others as defined in `src/Way.hs`. To\r
-control which ways particular packages are built, set `userLibraryWays` and\r
+control which ways particular ways are built, set `userLibraryWays` and\r
 `userRtsWays`. As an example, below we remove `dynamic` from the list of library\r
 ways and keep `rts` package ways unchanged:\r
 ```haskell\r
@@ -119,6 +126,6 @@ verboseCommands = builder (Gcc Compile) &&^ package compiler
 -- Use patterns when matching files:\r
 verboseCommands = file "//rts/sm/*" &&^ way threaded\r
 \r
--- Show all commands:\r
+-- Print all commands:\r
 verboseCommands = return True\r
-```
\ No newline at end of file
+```\r