[commit: ghc] wip/nfs-locking: Minor revision (4b0dc2f)

[git at git.haskell.org]

Repository : ssh://git@git.haskell.org/ghc

On branch  : wip/nfs-locking
Link       : http://ghc.haskell.org/trac/ghc/changeset/4b0dc2fe52989ff18dc5e0202a1bd48f00689772/ghc

>---------------------------------------------------------------

commit 4b0dc2fe52989ff18dc5e0202a1bd48f00689772
Author: Andrey Mokhov <andrey.mokhov at gmail.com>
Date:   Sat May 14 18:10:51 2016 +0100

    Minor revision
    
    [skip ci]


>---------------------------------------------------------------

4b0dc2fe52989ff18dc5e0202a1bd48f00689772
 doc/user-settings.md | 45 ++++++++++++++++++++++++++-------------------
 1 file changed, 26 insertions(+), 19 deletions(-)

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