@@ -0,0 +1,51 @@
3+* Get list of core packages
4+* Add core packages as strict dependencies
5+* Load up package index
6+* Calculate matches using newest versions of packages
7+* Write out a YAML file with all that information
8+* Verify that the build plan can be compiled
9+ * Optional: check with cabal-install as well
14+We start off with *constraints*. Constraints state things like "package X has a
15+given version range," who the maintainer is for a package, the description of
16+the system/compiler being used, etc. BuildConstraints discuss the build as a
17+whole, whereas PackageConstraints discuss the constraints on an individual
20+There are two primary ways of getting a BuildConstraints.
21+defaultBuildConstraints inspects the GHC in the PATH environment variable to
22+determine GHC version, core packages, core tools, etc. It then uses the
23+Stackage.Config module to extract information on additional packages to be
24+installed. The secondary approach is in UpdateBuildPlan, which will be
27+BuildConstraints do not specify a build completely. That is given by a
28+BuildPlan, which is similarly broken down into BuildPlan and PackagePlan. In
29+order to get a BuildPlan, we need two pieces of information: the
30+BuildConstraints, and a package index. The package index (usually downloaded
31+from Hackage) is a collection of all of the cabal files available.
33+By applying a BuildConstraints to a package index (via newBuildPlan), we get a
34+proposed BuildPlan. There is no guarantee that this BuildPlan is valid. To
35+validate it, we use checkBuildPlan. A BuildPlan is an instance of both ToJSON
36+and FromJSON, and therefore can be serialized to a file for later use.
38+When dealing with LTS Haskell, we want to be able to take a BuildPlan, and
39+update to a newer BuildPlan that keeps all packages in the same major version.
40+updateBuildConstraints turns a BuildPlan into a new BuildConstraints with that
41+restriction, and updateBuildPlan applies newBuildPlan to that result. As
42+mentioned previously: this is *not* a validated result, and therefore
43+checkBuildPlan must be used.
45+A BuildPlan can actually be acted on. This is done to check that all packages
46+compile together, run relevant test suites, test Haddock documentation is
47+correct, and produce as artifacts both a self-contained GHC binary package
48+database and a set of Haddock documentation. (Not yet implemented.)
50+A BuildPlan may be converted into a bundle to be uploaded to Stackage Server.
51+(Not yet implemented.)