[commit: ghc] wip/nfs-locking: Add user settings documentation (b56f4eb)

[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/b56f4eb4034f51dbb5364ff57752900c8d9f417b/ghc

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

commit b56f4eb4034f51dbb5364ff57752900c8d9f417b
Author: Andrey Mokhov <andrey.mokhov at gmail.com>
Date:   Sat May 14 13:58:21 2016 +0100

    Add user settings documentation
    
    See #56, #245.


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

b56f4eb4034f51dbb5364ff57752900c8d9f417b
 doc/user-settings.md | 124 +++++++++++++++++++++++++++++++++++++++++++++++++++
 src/Settings/User.hs |  20 ++++-----
 2 files changed, 134 insertions(+), 10 deletions(-)

diff --git a/doc/user-settings.md b/doc/user-settings.md
new file mode 100644
index 0000000..a7f1469
--- /dev/null
+++ b/doc/user-settings.md
@@ -0,0 +1,124 @@
+# User settings
+
+Users 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`:
+```haskell
+-- | All build artefacts are stored in 'buildRootPath' directory.
+buildRootPath :: FilePath
+buildRootPath = "_build"
+```
+
+## Command line arguments
+
+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
+GHC when compiling package `cabal`:
+```haskell
+-- | Control user-specific command line arguments.
+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`).
+
+It is possible to specify several custom command line arguments combining the
+list with `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"] ]
+```
+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.
+
+## Packages
+
+To add or remove a package from a particular build stage, use `userPackages`. As
+an example, below we add package `base` to Stage0 and remove package `haskeline`
+from Stage1:
+```haskell
+-- | Control which packages get to be built.
+userPackages :: Packages
+userPackages = mconcat
+    [ stage0 ? append [base]
+    , stage1 ? remove [haskeline] ]
+```
+If you are working on a new GHC package you need to let Hadrian know about it
+by setting `userKnownPackages`:
+```haskell
+-- | Add new user-defined packages.
+userKnownPackages :: [Package]
+userKnownPackages = []
+```
+To control which integer library to use when builing GHC, set `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
+`userRtsWays`. As an example, below we remove `dynamic` from the list of library
+ways and keep `rts` package ways unchanged:
+```haskell
+-- | Control which ways library packages are built.
+userLibraryWays :: Ways
+userLibraryWays = remove [dynamic]
+
+-- | Control which ways the 'rts' package is built.
+userRtsWays :: Ways
+userRtsWays = mempty
+```
+
+## Verbose command lines 
+
+By default Hadrian does not print full command lines during the build process
+and instead prints short human readable digests for each executed command. It is
+possible to suppress this behaviour completely or partially using
+`verboseCommands` setting:
+```haskell
+-- | Set to True to print full command lines during the build process. Note,
+-- this is a Predicate, hence you can enable verbose output for a chosen package
+-- only, e.g.: verboseCommands = package ghcPrim
+verboseCommands :: Predicate
+verboseCommands = return False
+```
+For example, to print the full command lines used to compile GHC executables,
+set `verboseCommands` to:
+```haskell
+verboseCommands :: Predicate
+verboseCommands = input "ghc/Main.hs"
+```
+Below are a few other examples:
+```haskell
+-- Print command lines for all Ghc Link invocations:
+verboseCommands = builder (Ghc Link)
+
+-- Print command lines when compiling files in package compiler using Gcc:
+verboseCommands = builder (Gcc Compile) &&^ package compiler 
+
+-- Use patterns when matching files:
+verboseCommands = file "//rts/sm/*" &&^ way threaded
+
+-- Show all commands:
+verboseCommands = return True
+```
\ No newline at end of file
diff --git a/src/Settings/User.hs b/src/Settings/User.hs
index 0893579..cc48684 100644
--- a/src/Settings/User.hs
+++ b/src/Settings/User.hs
@@ -16,31 +16,31 @@ import Settings.Default
 buildRootPath :: FilePath
 buildRootPath = "_build"
 
--- Control user-specific settings
+-- | Control user-specific command line arguments.
 userArgs :: Args
 userArgs = builder Ghc ? remove ["-Wall", "-fwarn-tabs"]
 
--- Control which packages get to be built
+-- | Control which packages get to be built.
 userPackages :: Packages
 userPackages = mempty
 
--- Add new user-defined packages
+-- | Add new user-defined packages.
 userKnownPackages :: [Package]
 userKnownPackages = []
 
--- | Control which ways library packages are built
+-- | Choose the integer library: integerGmp or integerSimple.
+integerLibrary :: Package
+integerLibrary = integerGmp
+
+-- | Control which ways library packages are built.
 -- FIXME: skip dynamic since it's currently broken #4
 userLibraryWays :: Ways
 userLibraryWays = remove [dynamic]
 
--- | Control which ways the 'rts' package is built
+-- | Control which ways the 'rts' package is built.
 userRtsWays :: Ways
 userRtsWays = mempty
 
--- | Choose the integer library: integerGmp or integerSimple
-integerLibrary :: Package
-integerLibrary = integerGmp
-
 -- | User-defined flags. Note the following type semantics:
 -- * Bool: a plain Boolean flag whose value is known at compile time
 -- * Action Bool: a flag whose value can depend on the build environment
@@ -79,7 +79,7 @@ buildHaddock = return cmdBuildHaddock
 
 -- | Set to True to print full command lines during the build process. Note,
 -- this is a Predicate, hence you can enable verbose output for a chosen package
--- only, e.g.: verboseCommands = package ghcPrim
+-- only, e.g.: verboseCommands = package ghcPrim.
 verboseCommands :: Predicate
 verboseCommands = return False