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