@@ -22,39 +22,40 @@ High level series of steps for processing
2222
2323We start off with *constraints*. Constraints state things like "package X has a
2424given version range," who the maintainer is for a package, the description of
25−the system/compiler being used, etc. BuildConstraints discuss the build as a
26−whole, whereas PackageConstraints discuss the constraints on an individual
27−package.
25+the system/compiler being used, etc. `BuildConstraints` describes the build as
26+a whole, whereas `PackageConstraints` describes the constraints on an
27+individual package.
2828
29−There are two primary ways of getting a BuildConstraints.
30−defaultBuildConstraints inspects the GHC in the PATH environment variable to
29+There are two primary ways of getting a `BuildConstraints`.
30+`defaultBuildConstraints` inspects the first GHC in the PATH environment variable to
3131determine GHC version, core packages, core tools, etc. It then uses the
32−Stackage.Config module to extract information on additional packages to be
33−installed. The secondary approach is in UpdateBuildPlan, which will be
32+`Stackage.Config` module to extract information on additional packages to be
33+installed. The secondary approach is in `Stackage2.UpdateBuildPlan`, which will be
3434discussed later.
3535
36−BuildConstraints do not specify a build completely. That is given by a
37−BuildPlan, which is similarly broken down into BuildPlan and PackagePlan. In
38−order to get a BuildPlan, we need two pieces of information: the
39−BuildConstraints, and a package index. The package index (usually downloaded
36+`BuildConstraints` does not specify a build completely. That is given by a
37+`BuildPlan`, which is similarly broken down into `BuildPlan` and `PackagePlan`.
38+In order to get a `BuildPlan`, we need two pieces of information: the
39+`BuildConstraints`, and a package index. The package index (usually downloaded
4040from Hackage) is a collection of all of the cabal files available.
4141
42−By applying a BuildConstraints to a package index (via newBuildPlan), we get a
43−proposed BuildPlan. There is no guarantee that this BuildPlan is valid. To
44−validate it, we use checkBuildPlan. A BuildPlan is an instance of both ToJSON
45−and FromJSON, and therefore can be serialized to a file for later use.
46−
47−When dealing with LTS Haskell, we want to be able to take a BuildPlan, and
48−update to a newer BuildPlan that keeps all packages in the same major version.
49−updateBuildConstraints turns a BuildPlan into a new BuildConstraints with that
50−restriction, and updateBuildPlan applies newBuildPlan to that result. As
51−mentioned previously: this is *not* a validated result, and therefore
52−checkBuildPlan must be used.
53−
54−A BuildPlan can actually be acted on. This is done to check that all packages
55−compile together, run relevant test suites, test Haddock documentation is
56−correct, and produce as artifacts both a self-contained GHC binary package
57−database and a set of Haddock documentation. (Not yet implemented.)
58−
59−A BuildPlan may be converted into a bundle to be uploaded to Stackage Server.
42+By applying a `BuildConstraints` to a package index (via `newBuildPlan`), we
43+get a proposed `BuildPlan`. There is no guarantee that this `BuildPlan` is
44+valid. To validate it, we use `checkBuildPlan`. A `BuildPlan` is an instance of
45+both `ToJSON` and `FromJSON`, and therefore can be serialized to a file for
46+later use.
47+
48+When dealing with LTS Haskell, we want to be able to take a `BuildPlan`, and
49+update to a newer `BuildPlan` that keeps all packages at the same major
50+version. `updateBuildConstraints` turns a `BuildPlan` into a new
51+`BuildConstraints` with that restriction, and `updateBuildPlan` applies
52+`newBuildPlan` to that result. As mentioned previously: this is *not* a
53+validated result, and therefore `checkBuildPlan` must be used.
54+
55+A `BuildPlan` can be acted on. This is done to check that all packages compile
56+together, run relevant test suites, test Haddock documentation is correct, and
57+produce as artifacts both a self-contained GHC binary package database and a
58+set of Haddock documentation. (Not yet implemented.)
59+
60+A `BuildPlan` may be converted into a bundle to be uploaded to Stackage Server.
6061(Not yet implemented.)