Fix issue haskell#289: Add command line switches to hptool for Windows

Fixes haskell-platform issue haskell#289 by removing all
positional parameters from the command line for the hptool,
replacing them with all with explicit switches, and adding
new command line parameters via new switches in order to
specify additional inputs needed for the Windows version of
hptool.  Fixing haskell#289 should make it a little easier to get
the Windows HP builds to include the correct documentation
and other ancillary files.

Unit testing is introduced to the hptool package with this
commit, which is immediately useful to the new command line
functionality, but should be useful for future work as well.

* hptool/hptool.cabal
  * To accomodate unit tests, break hptool up into a library
    that both the executable and the unit tests can
    reference.  Also, add the new files introduced, and
    handle building the unit tests.
* hptool/os-extras/win/templates/Nsisfile.nsi.mu
  * Update the doc short cuts which are created during
    installation, to track how GHC docs are currently structured.
* hptool/os-extras/win/templates/index.html.mu
  * New. The template to use for the overall index.html file
    for the installed GHC docs.
* hptool/src/CLArgs.hs
  * New.  Handles the new command line argument processing.
* hptool/src/Config.hs
  * Add to the Oracle, the new parameters that come from the
    command line, keeping them in a UserConfig.
* hptool/src/Internal/CLArgs.hs
  * New. A separation of CLArgs functionality which allows
    the unit tests to access non-exported functions.
* hptool/src/Main.hs
  * Replace the command line processing using the new CLArgs
    module, while updating the usage message, and connecting
    the args with the oracle.
* hptool/src/OS/Win/WinNsis.hs
  * Rather than use a index.html file that has to be updated
    by hand for each release, use a template to generate one.
* hptool/src/OS/Win/WinPaths.hs
  * Add paths for the index.html and its template.  Remove
    the winExternalDocs path, since it is now unused.
* hptool/src/OS/Win/WinRules.hs
  * Rather than copy a hand-crafted directory into the
    release, grab the appropriate pieces as specified by the
    user from the command line args (and pushed into the
    oracle), and untar those into the release instaed.
* hptool/src/Package.hs
  * Compiler warning.
* hptool/src/Types.hs
  * Add two types, BuildFlavor and UserConfig, for storing
    the user command line args.
* hptool/tests/UnitTests.hs
  * New.  The main unit tests file, which will invoke the
    sub-tests (so far only one: CLArgs)
* hptool/tests/UnitTests/CLArgs.hs
  * New. Tests the new command line parsing/handling.
* windows-platform.sh
  * Some updated paths; update the messages to match the new
    params; update the sanity checks; add a time stamp to
    start and end.

hptool/hptool.cabal

@@ -1,4 +1,4 @@
-Name:            hptool
+Name:            HPTool
 Version:         0.1
 Author:          Mark Lentczner
 Maintainer:      [email protected]
@@ -10,9 +10,63 @@ Synopsis:        Haskell Platform Utility
 Data-files:
   templates/*.cabal.mu
 
+Library
+  Exposed-Modules:
+    CLArgs,
+    Internal.CLArgs,
+    Config,
+    Dirs
+    GhcDist,
+    HaddockMaster,
+    LocalCommand,
+    OS,
+    OS.Internal,
+    OS.Mac,
+    OS.Posix,
+    OS.Win
+    OS.Win.WinNsis,
+    OS.Win.WinPaths,
+    OS.Win.WinRules,
+    OS.Win.WinUtils,
+    Package,
+    Paths,
+    PlatformDB,
+    ReleaseFiles,
+    Releases,
+    Releases2012,
+    Releases2013,
+    Releases2014,
+    Releases2015,
+    Releases2016,
+    Releases2017,
+    Releases2018,
+    SourceTarball,
+    Target,
+    Templates,
+    Types,
+    Utils,
+    Website
+  Build-depends:
+    Cabal,
+    base,
+    bytestring,
+    containers,
+    directory,
+    hastache >=0.6.0,
+    shake >= 0.14 && < 0.16,
+    split,
+    text,
+    transformers,
+    unix-compat,
+    filepath
+  hs-source-dirs: src
+
 Executable hptool
   Main-is: Main.hs
+  hs-source-dirs: src
   Other-Modules:
+    CLArgs,
+    Internal.CLArgs,
     Config,
     Dirs
     GhcDist,
@@ -45,21 +99,37 @@ Executable hptool
     Types,
     Utils,
     Website
-
-  hs-source-dirs: src
-
   Build-depends:
     Cabal,
     base,
     bytestring,
     containers,
     directory,
     hastache >=0.6.0,
+    HPTool,
     shake >= 0.14 && < 0.16,
     split,
     text,
     transformers,
     unix-compat,
     filepath
-
   ghc-options: -Wall -fwarn-tabs
+
+
+test-suite unit-tests
+  type: exitcode-stdio-1.0
+  hs-source-dirs: tests
+  other-modules:
+    UnitTests.CLArgs
+  main-is: UnitTests.hs
+  build-depends:
+    base,
+    directory,
+    HPTool,
+    HUnit,
+    QuickCheck,
+    tasty,
+    tasty-hunit,
+    tasty-hspec,
+    transformers
+  ghc-options: -Wall

hptool/os-extras/win/templates/Nsisfile.nsi.mu

@@ -439,10 +439,10 @@ Section "-StartMenu" StartMenu
         "$INSTDIR\doc\html\index.html"
     CreateShortCut \
         "$SMPROGRAMS\$START_MENU_FOLDER\GHC Flag Reference.lnk" \
-        "$INSTDIR\doc\html\users_guide\flag-reference.html"
+        "$INSTDIR\doc\html\users_guide\flags.html"
     CreateShortCut \
         "$SMPROGRAMS\$START_MENU_FOLDER\Library Documentation.lnk" \
-        "$INSTDIR\lib\extralibs\doc\frames.html"
+        "$INSTDIR\lib\extralibs\doc\index.html"
     CreateShortCut "$SMPROGRAMS\$START_MENU_FOLDER\GHCi.lnk" \
         "$INSTDIR\bin\ghci.exe"
     CreateShortCut "$SMPROGRAMS\$START_MENU_FOLDER\WinGHCi.lnk" \

hptool/os-extras/win/templates/index.html.mu

@@ -0,0 +1,56 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
+<html><head>
+<meta http-equiv="content-type" content="text/html; charset=windows-1252">
+    <title>GHC Documentation</title>
+  </head>
+
+  <body>
+
+    <h1>GHC Documentation</h1>
+
+    <p>
+      Welcome to GHC!
+    </p>
+
+    <p>
+      This is the top of the GHC documentation tree, where you will find
+      links to all the supplied documentation about GHC and its libraries.
+    </p>
+
+    <ul>
+      <li>
+        <p>
+          <b><a href="users_guide/index.html">The User's Guide</a></b>
+        </p>
+        <p>
+          The User's Guide has all you need to know about using GHC:
+          command line options, language extensions, GHCi, etc.
+        </p>
+      </li>
+
+      <li>
+        <p>
+          <b><a href="libraries/index.html">Libraries</a></b>
+        </p>
+        <p>
+          Documentation for the libraries that come with GHC.
+        </p>
+      </li>
+
+      <li>
+        <p>
+          <b><a href="libraries/ghc-{{ghcVersion}}/index.html">GHC API</a></b>
+        </p>
+        <p>
+          Documentation for the GHC API.
+        </p>
+      </li>
+    </ul>
+
+    <p>For more information, see the following:</p>
+    <ul>
+      <li><p><a href="http://www.haskell.org/ghc/">GHC Home Page</a></p></li>
+      <li><p><a href="http://ghc.haskell.org/trac/ghc/">
+        GHC Developers Home</a></p></li>
+    </ul>
+</body></html>

hptool/src/CLArgs.hs

@@ -0,0 +1,137 @@
+{-# LANGUAGE RecordWildCards #-}
+{-# LANGUAGE LambdaCase #-}
+
+-- | Command Line Args handling.
+
+module CLArgs
+       ( checkAndValidateArgs
+       , flags
+       , Flags(..)
+       , ValidationErrs
+       )
+  where
+
+import Control.Monad.Trans.Writer.Strict ( execWriterT )
+import System.Console.GetOpt
+
+import Types
+
+import Internal.CLArgs
+
+
+-- | Long Options, provided at top-level so they can be used in the
+-- specific error messages (the OptDescr is not very ammenable to mapping
+-- from a value in Flags to the option).  Note no short options are used
+-- since otherwise they likely would conflict with the Shake command-line
+-- options, so we use a long option, with an "X" before our "short" option.
+--  --Xb: cabal executable file
+--  --Xc: core build only
+--  --Xf: full build
+--  --Xg: ghc-bindist (tar file)
+--  --Xh: haddock docs in HTML (tar file)
+--  --Xi: print info
+--  --Xl: ghc libraries docs in HTML (tar file)
+--  --Xp: ghc user's guide PDF (file)
+--  --Xs: stack installer or executable file
+--  --Xu: ghc user's guide in HTML (tar file)
+--  --Xx: set installation prefix (for Posix builds)
+optCabalExe, optCore, optFull, optGHCBinDist, optHaddockDocs, optInfo,
+  optGHCLibsHTML, optGHCUsersPDF, optStackExe, optGHCUsersHTML, optPrefix,
+  optUsage :: [Char]
+optCabalExe     = "Xb"
+optCore         = "Xc"
+optFull         = "Xf"
+optGHCBinDist   = "Xg"
+optHaddockDocs  = "Xh"
+optInfo         = "Xi"
+optGHCLibsHTML  = "Xl"
+optGHCUsersPDF  = "Xp"
+optStackExe     = "Xs"
+optGHCUsersHTML = "Xu"
+optPrefix       = "Xx"
+optUsage        = "X?"
+
+-- If we use the long option of "help", shake intercepts that from us.
+flags :: [OptDescr (Either a Flags)]
+flags = [ Option "" [optUsage] (NoArg $ Right Usage)
+                     "Show command line flags and options."
+        , Option "" [optCabalExe] (ReqArg (Right . CabalExe) "PATH")
+                     "Path to the cabal executable to use during build."
+        , Option "" [optCore] (NoArg (Right $ FlavorFlag BuildFlavorCore))
+                     "Perform a core-only HP build."
+        , Option "" [optFull] (NoArg $ Right $ FlavorFlag BuildFlavorFull)
+                     "Perform a full HP build."
+        , Option "" [optGHCBinDist] (ReqArg (Right . GHCBinDist) "TAR")
+                     "Path to the GHC distribution tarfile."
+        , Option "" [optHaddockDocs] (ReqArg (Right . HaddockHTML) "TAR")
+                     "WINDOWS: Path to Haddock documentation tarfile."
+        , Option "" [optInfo] (NoArg $ Right Info)
+                     "Show details on packages are in this HP release."
+        , Option "" [optGHCLibsHTML] (ReqArg (Right . GHCLibsHTML) "TAR")
+                     "WINDOWS: Path to GHC library docs tarfile."
+        , Option "" [optGHCUsersPDF] (ReqArg (Right . GHCUsersPDF) "PDF")
+                     "WINDOWS: Path to the GHC User's Guide (PDF file)."
+        , Option "" [optStackExe] (ReqArg (Right . StackExe) "PATH")
+                     "Path to the stack installer or executable."
+        , Option "" [optGHCUsersHTML] (ReqArg (Right . GHCUsersHTML) "TAR")
+                     "WINDOWS: Path to GHC User's Guide (HTML) tarfile."
+        , Option "" [optPrefix] (ReqArg (Right . Prefix) "DIR")
+                     "Set a custom install prefix (only Posix builds)."
+        ]
+
+flagsToConfig :: UserConfig -> Flags -> UserConfig
+flagsToConfig uc                 Info            = uc
+flagsToConfig uc@UserConfig{..} (Prefix a)       = uc{ ucPrefix = Just a }
+flagsToConfig uc@UserConfig{..} (FlavorFlag a)   = uc{ ucBuildFlavor = a }
+flagsToConfig uc@UserConfig{..} (CabalExe a)     = uc{ ucCabalExe = a }
+flagsToConfig uc@UserConfig{..} (GHCBinDist a)   = uc{ ucGHCBinDist = a }
+flagsToConfig uc@UserConfig{..} (StackExe a)     = uc{ ucStackExe = a }
+flagsToConfig uc@UserConfig{..} (GHCUsersPDF a)  = uc{ ucGHCUsersPDF = a }
+flagsToConfig uc@UserConfig{..} (GHCUsersHTML a) = uc{ ucGHCUsersHTML = a }
+flagsToConfig uc@UserConfig{..} (GHCLibsHTML a)  = uc{ ucGHCLibsHTML = a }
+flagsToConfig uc@UserConfig{..} (HaddockHTML a)  = uc{ ucHaddockHTML = a }
+flagsToConfig uc                 Usage           = uc
+
+defUserConfig :: UserConfig
+defUserConfig = UserConfig Nothing BuildFlavorCore "" "" "" "" "" "" ""
+
+checkAndValidateArgs :: (Monad m) => Bool -> (FilePath -> m Bool) -> [Flags]
+                        -> m (UserConfig, ValidationErrs)
+checkAndValidateArgs buildWin doesFileExist flgVals = do
+  let checkRequiredAndExists' = checkRequiredAndExists doesFileExist flgVals
+      uc = defUserConfig
+      -- Some flags are required only for Windows, and are misleading if
+      -- otherwise provided.
+      validator =
+          if buildWin then checkRequiredAndExists' else checkExcess flgVals
+  validationErrors <- execWriterT $ do
+    checkCoreOrFull flgVals
+    checkRequiredAndExists'
+      (\case (CabalExe s) -> Just s
+             _            -> Nothing )
+      "cabal executable" optCabalExe
+    checkRequiredAndExists'
+      (\case (GHCBinDist s) -> Just s
+             _              -> Nothing )
+      "GHC distro tarfile" optGHCBinDist
+    checkRequiredAndExists'
+      (\case (StackExe s) -> Just s
+             _            -> Nothing )
+      "Stack installer/executable" optStackExe
+    validator (\case (GHCUsersPDF s) -> Just s
+                     _               -> Nothing )
+      "GHC User's Guide (PDF file)" optGHCUsersPDF
+    validator (\case (GHCUsersHTML s) -> Just s
+                     _                -> Nothing )
+      "GHC User's Guide (HTML tarfile)" optGHCUsersHTML
+    validator (\case (GHCLibsHTML s) -> Just s
+                     _               -> Nothing )
+      "Required: path to Libraries Doc HTML tarfile" optGHCLibsHTML
+    validator (\case (HaddockHTML s) -> Just s
+                     _               -> Nothing )
+      "Required: path to Haddock HTML tarfile" optHaddockDocs
+  let userConfigValidated =
+          if (not $ null validationErrors )
+            then uc
+            else foldl flagsToConfig uc flgVals
+  return ( userConfigValidated, validationErrors )