From 04f71e69e70ab0d3c249f8f382d27d40bdc22129 Mon Sep 17 00:00:00 2001 From: Michael Snoyman Date: Mon, 8 Dec 2014 14:06:46 +0200 Subject: [PATCH] Updated roadmap --- ROADMAP | 10 ---------- ROADMAP.md | 51 +++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 51 insertions(+), 10 deletions(-) delete mode 100644 ROADMAP create mode 100644 ROADMAP.md diff --git a/ROADMAP b/ROADMAP deleted file mode 100644 index 70a17559..00000000 --- a/ROADMAP +++ /dev/null @@ -1,10 +0,0 @@ -Processing: - -* Get list of core packages -* Add core packages as strict dependencies -* Load up package index -* Calculate matches using newest versions of packages -* Write out a YAML file with all that information -* Verify that the build plan can be compiled - * Optional: check with cabal-install as well -* Perform the build diff --git a/ROADMAP.md b/ROADMAP.md new file mode 100644 index 00000000..05551293 --- /dev/null +++ b/ROADMAP.md @@ -0,0 +1,51 @@ +Processing: + +* Get list of core packages +* Add core packages as strict dependencies +* Load up package index +* Calculate matches using newest versions of packages +* Write out a YAML file with all that information +* Verify that the build plan can be compiled + * Optional: check with cabal-install as well +* Perform the build + +Code explanation: + +We start off with *constraints*. Constraints state things like "package X has a +given version range," who the maintainer is for a package, the description of +the system/compiler being used, etc. BuildConstraints discuss the build as a +whole, whereas PackageConstraints discuss the constraints on an individual +package. + +There are two primary ways of getting a BuildConstraints. +defaultBuildConstraints inspects the GHC in the PATH environment variable to +determine GHC version, core packages, core tools, etc. It then uses the +Stackage.Config module to extract information on additional packages to be +installed. The secondary approach is in UpdateBuildPlan, which will be +discussed later. + +BuildConstraints do not specify a build completely. That is given by a +BuildPlan, which is similarly broken down into BuildPlan and PackagePlan. In +order to get a BuildPlan, we need two pieces of information: the +BuildConstraints, and a package index. The package index (usually downloaded +from Hackage) is a collection of all of the cabal files available. + +By applying a BuildConstraints to a package index (via newBuildPlan), we get a +proposed BuildPlan. There is no guarantee that this BuildPlan is valid. To +validate it, we use checkBuildPlan. A BuildPlan is an instance of both ToJSON +and FromJSON, and therefore can be serialized to a file for later use. + +When dealing with LTS Haskell, we want to be able to take a BuildPlan, and +update to a newer BuildPlan that keeps all packages in the same major version. +updateBuildConstraints turns a BuildPlan into a new BuildConstraints with that +restriction, and updateBuildPlan applies newBuildPlan to that result. As +mentioned previously: this is *not* a validated result, and therefore +checkBuildPlan must be used. + +A BuildPlan can actually be acted on. This is done to check that all packages +compile together, run relevant test suites, test Haddock documentation is +correct, and produce as artifacts both a self-contained GHC binary package +database and a set of Haddock documentation. (Not yet implemented.) + +A BuildPlan may be converted into a bundle to be uploaded to Stackage Server. +(Not yet implemented.)