Clean up, build stage 1 GHC on AppVeyor.

.appveyor.yml

@@ -39,4 +39,4 @@ install:
 build_script:
     - cd C:\msys64\home\ghc\shake-build
     - echo "" | stack --no-terminal exec -- build.bat selftest
-    - echo "" | stack --no-terminal exec -- build.bat -j --no-progress inplace/bin/ghc-cabal.exe
+    - echo "" | stack --no-terminal exec -- build.bat -j --no-progress inplace/bin/ghc-stage1.exe

src/GHC.hs

@@ -19,7 +19,7 @@ import Stage
 -- all of them. However, not all of these packages will be built. For example,
 -- package /win32/ is built only on Windows.
 -- "Packages" defines default conditions for building each package, which can
--- be overridden in "User".
+-- be overridden in "Settings.User".
 defaultKnownPackages :: [Package]
 defaultKnownPackages =
     [ array, base, binary, bytestring, cabal, compiler, containers, compareSizes
@@ -30,7 +30,7 @@ defaultKnownPackages =
     , primitive, process, rts, runGhc, stm, templateHaskell, terminfo, time
     , touchy, transformers, unlit, unix, win32, xhtml ]
 
--- Package definitions (see "Package")
+-- | Package definitions, see 'Package'.
 array, base, binary, bytestring, cabal, compiler, containers, compareSizes,
     deepseq, deriveConstants, directory, dllSplit, filepath, genapply,
     genprimopcode, ghc, ghcBoot, ghcCabal, ghci, ghcPkg, ghcPrim, ghcTags,

src/Package.hs

@@ -21,6 +21,7 @@ newtype PackageName = PackageName { getPackageName :: String }
 instance Show PackageName where
     show (PackageName name) = name
 
+-- TODO: make PackageType more precise, #12
 -- | We regard packages as either being libraries or programs. This is
 -- bit of a convenient lie as Cabal packages can be both, but it works
 -- for now.
@@ -35,6 +36,7 @@ data Package = Package
      }
      deriving Generic
 
+-- | Prettyprint Package name.
 pkgNameString :: Package -> String
 pkgNameString = getPackageName . pkgName
 
@@ -42,29 +44,37 @@ pkgNameString = getPackageName . pkgName
 pkgCabalFile :: Package -> FilePath
 pkgCabalFile pkg = pkgPath pkg -/- getPackageName (pkgName pkg) <.> "cabal"
 
+-- | Smart constructor for a top-level package, e.g. 'compiler'.
 topLevel :: PackageName -> Package
 topLevel name = Package name (getPackageName name) Library
 
+-- | Smart constructor for a library package, e.g. 'array'.
 library :: PackageName -> Package
 library name = Package name ("libraries" -/- getPackageName name) Library
 
+-- | Smart constructor for a utility package, e.g. 'haddock'.
 utility :: PackageName -> Package
 utility name = Package name ("utils" -/- getPackageName name) Program
 
+-- | Amend package path. Useful when a package name doesn't match its path.
 setPath :: Package -> FilePath -> Package
 setPath pkg path = pkg { pkgPath = path }
 
+-- | Amend package type.
 setType :: Package -> PackageType -> Package
 setType pkg ty = pkg { pkgType = ty }
 
+-- | Check whether a package is a library.
 isLibrary :: Package -> Bool
 isLibrary (Package {pkgType=Library}) = True
 isLibrary _ = False
 
+-- | Check whether a package is a program.
 isProgram :: Package -> Bool
 isProgram (Package {pkgType=Program}) = True
 isProgram _ = False
 
+-- TODO: Get rid of non-derived Show instances.
 instance Show Package where
     show = show . pkgName
 
@@ -74,8 +84,8 @@ instance Eq Package where
 instance Ord Package where
     compare = compare `on` pkgName
 
--- Given a sorted list of packages and a sorted list of package names, returns
--- packages whose names appear in the list of names
+-- | Given a sorted list of packages and a sorted list of package names, returns
+-- packages whose names appear in the list of names.
 matchPackageNames :: [Package] -> [PackageName] -> [Package]
 matchPackageNames = intersectOrd (\pkg name -> compare (pkgName pkg) name)
 

src/Rules.hs

@@ -12,7 +12,6 @@ import Settings
 allStages :: [Stage]
 allStages = [minBound ..]
 
--- TODO: not all program targets should be needed explicitly
 -- | 'need' all top-level build targets
 generateTargets :: Rules ()
 generateTargets = action $ do
@@ -29,7 +28,7 @@ targetsForStage stage = do
         needHaddock <- interpretPartial target buildHaddock
         return [ pkgHaddockFile pkg | needHaddock && stage == Stage1 ]
     let programTargets = [ prog | Just prog <- programPath stage <$> pkgs ]
-    return (libTargets ++ programTargets)
+    return $ libTargets ++ programTargets
 
 packageRules :: Rules ()
 packageRules = do

src/Rules/Config.hs

@@ -17,8 +17,6 @@ configRules = do
                     ++ "Run the configure script either manually or via the "
                     ++ "build system by passing --configure[=ARGS] flag."
 
-    -- When we detect Windows paths in ACLOCAL_PATH we reset it.
-    -- TODO: Handle Windows paths in ACLOCAL_PATH more gracefully.
     "configure" %> \_ -> do
         putBuild "| Running boot..."
         quietly $ cmd (EchoStdout False) "perl boot"

src/Rules/Libffi.hs

@@ -14,7 +14,7 @@ import Settings.User
 rtsBuildPath :: FilePath
 rtsBuildPath = targetPath Stage1 rts -/- "build"
 
--- TODO: Why copy these include files in rts? Move to libffi!
+-- TODO: Why copy these include files into rts? Keep in libffi!
 libffiDependencies :: [FilePath]
 libffiDependencies = (rtsBuildPath -/-) <$> [ "ffi.h", "ffitarget.h" ]
 

src/Stage.hs

@@ -6,21 +6,20 @@ import GHC.Generics (Generic)
 
 -- | A stage refers to a certain compiler in GHC's build process.
 --
--- * Stage 0 is the bootstrapping compiler, i.e. the one already installed on
---   the user's system.
+-- * Stage 0 is built with the bootstrapping compiler, i.e. the one already
+--   installed on the user's system. The compiler that is produced during
+--   stage 0 is called /stage 1 compiler/.
 --
--- * Stage 1 is built using the stage 0 compiler, using GHC's source code.
---   The result is a compiler that was built by the bootstrapping compiler,
---   with all the features of the new compiler.
+-- * Stage 1 is built using the stage 1 compiler and all GHC sources. The result
+--   is called /stage 2 compiler/ and it has all features of the new GHC.
 --
--- * Stage 2 is built using the stage 1 compiler and GHC's source code. The
---   result is a compiler "built by itself", commonly referred to as
---   /bootstrapping/.
+-- * Stage 2 is built using the stage 2 compiler. The result is a compiler
+--   fully "built by itself", commonly referred to as /bootstrapping/.
 --
--- * Stage 3 uses stage 2 to build from source again. The result should have
---   the same object code as stage 2, which is a good test for the compiler.
---   Since it serves no other purpose than that, the stage 3 build is usually
---   omitted in the build process.
+-- * Stage 3 is built as a self test. The resulting compiler should have
+--   the same object code as the one built in stage 2, which is a good test
+--   for the compiler. Since it serves no other purpose than that, the stage 3
+--   build is usually omitted in the build process.
 data Stage = Stage0 | Stage1 | Stage2 | Stage3
            deriving (Show, Eq, Ord, Enum, Generic, Bounded)
 

src/Target.hs

@@ -8,10 +8,10 @@ module Target (
 ) where
 
 import Control.Monad.Trans.Reader
+import GHC.Generics (Generic)
 
 import Base
 import Builder
-import GHC.Generics (Generic)
 import Package
 import Stage
 import Way

src/Test.hs

 {-# LANGUAGE ScopedTypeVariables #-}
 {-# OPTIONS_GHC -fno-warn-orphans #-}
-
 module Test (testRules) where
 
-import Way
 import Development.Shake
+import Settings.Builders.Ar (chunksOfSize)
 import Test.QuickCheck
-import Settings.Builders.Ar(chunksOfSize)
+import Way
 
 instance Arbitrary Way where
     arbitrary = wayFromUnits <$> arbitrary
@@ -16,7 +15,7 @@ instance Arbitrary WayUnit where
 
 testRules :: Rules ()
 testRules =
-    phony "selftest" $ do
+    "selftest" ~> do
         test $ \(x :: Way) -> read (show x) == x
         test $ \n xs ->
             let res = chunksOfSize n xs