Add user settings documentation
authorAndrey Mokhov <andrey.mokhov@gmail.com>
Sat, 14 May 2016 12:58:21 +0000 (13:58 +0100)
committerAndrey Mokhov <andrey.mokhov@gmail.com>
Sat, 14 May 2016 12:58:21 +0000 (13:58 +0100)
See #56, #245.

doc/user-settings.md [new file with mode: 0644]
src/Settings/User.hs

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