refactor: reorganize cabal.project files

cabal.project.stage1

@@ -1,3 +1,7 @@
+allow-boot-library-installs: True
+benchmarks: False
+tests: False
+
 packages:
   -- NOTE: we need rts-headers, because the _newly_ built compiler depends
   --       on these potentially _new_ headers, we must not rely on those from
@@ -8,37 +12,49 @@ packages:
   rts-headers
   rts-fs
 
-  -- other packages.
+  -- Compiler
   ghc
   compiler
-  libraries/directory
-  libraries/file-io
-  libraries/filepath
-  libraries/ghc-platform
+
+  -- Internal libraries
   libraries/ghc-boot
   libraries/ghc-boot-th-next
   libraries/ghc-heap
+  libraries/ghc-platform
   libraries/ghci
+
+  -- Internal tools
+  utils/deriveConstants
+  utils/genapply
+  utils/genprimopcode
+  utils/ghc-pkg
+  utils/ghc-toolchain
+  utils/ghc-toolchain/exe
+  utils/unlit
+
+  -- The following are packages available on Hackage but included as submodules
+  libraries/Cabal/Cabal
+  libraries/Cabal/Cabal-syntax
+  libraries/directory
+  libraries/file-io
+  libraries/filepath
   libraries/os-string
   libraries/process
   libraries/semaphore-compat
---  libraries/time
   libraries/unix
   libraries/Win32
-  libraries/Cabal/Cabal-syntax
-  libraries/Cabal/Cabal
-  utils/ghc-pkg
   utils/hsc2hs
-  utils/unlit
-  utils/genprimopcode
-  utils/genapply
-  utils/deriveConstants
-  utils/ghc-toolchain
-  utils/ghc-toolchain/exe
 
-benchmarks: False
-tests: False
-allow-boot-library-installs: True
+--
+-- Constraints
+--
+
+constraints:
+  template-haskell <= 2.22
+
+--
+-- Package level configuration
+--
 
 package *
   library-vanilla: True
@@ -63,8 +79,9 @@ package ghc-boot-th-next
 package hsc2hs
   flags: +in-ghc-tree
 
-constraints:
-  template-haskell <= 2.22
+--
+-- Program options
+--
 
 program-options
   ghc-options: -fhide-source-paths -j

cabal.project.stage2

@@ -1,88 +1,106 @@
-package-dbs: clear, global
+allow-boot-library-installs: True
+benchmarks: False
+tests: False
+
+-- Disable Hackage, we explicitly include the packages we need.
+active-repositories: :none
 
 -- Import configure/generated feature toggles (dynamic, etc.) if present.
 -- A default file is kept in-tree; configure will overwrite with substituted values.
 import: cabal.project.stage2.settings
 
 packages:
+  -- RTS
   rts-headers
   rts-fs
   rts
 
-  libraries/ghc-prim
-  libraries/ghc-internal
-  libraries/ghc-experimental
-  libraries/base
+  -- Compiler
   compiler
   ghc
-  libraries/ghc-platform
-  libraries/ghc-compact
+
+  -- Internal libraries
+  libraries/base
   libraries/ghc-bignum
-  libraries/integer-gmp
   libraries/ghc-boot
   libraries/ghc-boot-th
+  libraries/ghc-compact
+  libraries/ghc-experimental
   libraries/ghc-heap
+  libraries/ghc-internal
+  libraries/ghc-platform
+  libraries/ghc-prim
   libraries/ghci
-  libraries/stm
-  libraries/template-haskell
-  libraries/hpc
+  libraries/integer-gmp
   libraries/system-cxx-std-lib
+  libraries/template-haskell
+
+  -- Internal tools
+  utils/deriveConstants
+  utils/genapply
+  utils/genprimopcode
+  utils/ghc-iserv
+  utils/ghc-pkg
+  utils/ghc-toolchain
+  utils/hp2ps
+  utils/runghc
+  utils/unlit
+
+  -- The following are packages available on Hackage but included as submodules
   libraries/array
   libraries/binary
   libraries/bytestring
+  libraries/Cabal/Cabal
+  libraries/Cabal/Cabal-syntax
   libraries/containers/containers
   libraries/deepseq
   libraries/directory
   libraries/exceptions
   libraries/file-io
   libraries/filepath
+  libraries/haskeline
+  libraries/hpc
   libraries/mtl
   libraries/os-string
   libraries/parsec
   libraries/pretty
   libraries/process
   libraries/semaphore-compat
+  libraries/stm
+  libraries/terminfo
   libraries/text
   libraries/time
   libraries/transformers
   libraries/unix
-  libraries/xhtml
   libraries/Win32
+  libraries/xhtml
+  utils/hpc
+  utils/hsc2hs
 
-  libraries/Cabal/Cabal-syntax
-  libraries/Cabal/Cabal
+  -- These would be on Hackage but we include them as direct URLs
+  -- (Hackage is disabled by `active-repositories: :none`)
   https://hackage.haskell.org/package/alex-3.5.2.0/alex-3.5.2.0.tar.gz
   https://hackage.haskell.org/package/happy-2.1.5/happy-2.1.5.tar.gz
   https://hackage.haskell.org/package/happy-lib-2.1.5/happy-lib-2.1.5.tar.gz
 
-  utils/genprimopcode
-  utils/deriveConstants
-  utils/ghc-pkg
-  utils/hsc2hs
-  utils/unlit
-  utils/ghc-toolchain
-
-  libraries/haskeline
-  libraries/terminfo
-  utils/hp2ps
-  utils/hpc
-  utils/ghc-iserv
-  utils/genapply
-  utils/runghc
-
--- project-rts
--- project-ghc
-benchmarks: False
-tests: False
-allow-boot-library-installs: True
-active-repositories: :none
+--
+-- Constraints
+--
 
 constraints:
   -- we do not want to use the rts-headers from stage1
-  rts-headers source, rts-fs source
-  -- All build dependencies should be installed, i.e. from stage1.
+  -- FIXME: these as listed in `packages:` so they are always used in source form
+  rts-headers source,
+  rts-fs source,
+
   -- I cannot write build:* but ghc-internal is enough to do the job.
-  , build:any.ghc-internal installed
+  -- FIXME: it should be possible to write build:*
+  -- All build dependencies should be installed, i.e. from stage1.
+  build:any.ghc-internal installed
+
+--
+-- Package level configuration
+--
 
 package *
   library-vanilla: True
@@ -128,18 +146,6 @@ if os(darwin)
     flags: +tables-next-to-code +leading-underscore
 	ld-options: -undefined warning
 
-
-program-options
-  ghc-options: -fhide-source-paths -j
-
--- project-boot-libs
-benchmarks: False
-tests: False
-allow-boot-library-installs: True
-active-repositories: :none
-
--- (removed duplicate global package * stanza; first one applies already)
-
 package rts-headers
   ghc-options: -no-rts
 
@@ -180,32 +186,33 @@ package rts
 --        throughout the session. See
 --          GHC.Unit.State:mkUnitState
 --
-package ghc-internal
-  ghc-options: -no-rts
 
 package ghc
   flags: +build-tool-depends +internal-interpreter
 
+package ghc-bin
+  flags: +internal-interpreter -threaded
+
 package ghci
   flags: +internal-interpreter
 
 package ghc-internal
   flags: +bignum-native
+  ghc-options: -no-rts
 
 package text
   flags: -simdutf
 
-program-options
-  ghc-options: -fhide-source-paths -j
-
-package ghc-bin
-  flags: +internal-interpreter -threaded
-
+-- TODO: What is this? Why do we need _in-ghc-tree_ here?
 package hsc2hs
   flags: +in-ghc-tree
 
 package haskeline
   flags: -terminfo
 
+--
+-- Program options
+--
+
 program-options
   ghc-options: -fhide-source-paths -j