git.iko.soy/stackage
on 031ab4e help sign in
stackage/README.md
134 lines 5.6 kB history raw
1stackage
2========
4"Stable Hackage," tools for creating a vetted set of packages from Hackage.
6__NOTE__ This repository is for package authors to get their code into
7Stackage. If you simply want to use Stackage as an end user, please follow the
8instructions on [http://www.stackage.org/](http://www.stackage.org).
10A note about the codebase: the goal is to minimize dependencies and have
11the maximum range of supported compiler versions. Therefore, we avoid
12anything "complicated." For example, instead of using the text package,
13we use Strings everywhere.
15Get your package included
16-------------------------
18In order to get your package included in the set of stable packages, you should
19send a pull request against this repository. In the [`build-constraints.yaml`](https://github.com/fpco/stackage/blob/master/build-constraints.yaml) file,
20there's a section called `packages`. In general, to add a set of
21packages, you would add:
23 "My Name myemail@example.com @mygithubuser":
24 - package1
25 - package2
26 - package3
28You can follow the examples of the other sets of packages in that function.
29Once you've done this, you can send a pull request to get your package
30included.
32__NOTE__: In order to ease the process of adding new packages, we no longer
33require new submissions to be tested on your own system before sending a pull
34request. If you believe your package works with the newest versions of all
35dependencies, you may send a pull request without testing first.
37You should also read the [maintainers
38agreement](https://github.com/fpco/stackage/wiki/Maintainers-Agreement).
40Build the package set
41---------------------
43Generally, building the package set should be done only by the Jenkins machine
44or by the official maintainers, as the process does require quite a bit of
45setup on the local machine. That said, you'll likely be able to get a stable
46build by running:
48 cabal update
49 cabal install stackage
50 stackage nightly
52### Docker
54Note: This method is currently considered experimental.
56If you'd like to check a build plan, or perform an entire build, without
57specially configuring your system, Docker may be a good approach. To check if
58some modifications to `build-constraints.yaml` are valid, try the following:
601. Create a local clone of the `stackage` repo
612. Make modifications to your local `build-constraints.yaml`
623. Inside the `stackage` working directory, run the following:
64 ```
65 $ docker run -it --rm -v $(pwd):/stackage -w /stackage snoyberg/stackage /bin/bash -c 'cabal update && stackage check'
66 ```
68Similarly, if you'd like to perform an entire build, you can replace the last step with:
70```
71$ docker run -it --rm -v $(pwd):/stackage -w /stackage snoyberg/stackage /bin/bash -c 'cabal update && stackage nightly --skip-upload'
72```
74## Processing
76The following describes at a high level the series of steps for processing
78### Nightlies
801. Get list of core packages
812. Get build constraints from list of maintained packages
823. Load up package index
834. Calculate build plan using newest versions of packages
845. Write out a YAML file with complete build plan
856. Verify that the build plan can be compiled
867. Perform the build
88### LTS
901. Load up most recent build plan
912. Convert build plan into constraints for next build
923. Continue from step (3) above
94## Code explanation
96We start off with *constraints*. Constraints state things like "package X has a
97given version range," who the maintainer is for a package, the description of
98the system/compiler being used, etc. `BuildConstraints` describes the build as
99a whole, whereas `PackageConstraints` describes the constraints on an
100individual package.
102There are two primary ways of getting a `BuildConstraints`.
103`defaultBuildConstraints` inspects the first GHC in the PATH environment variable to
104determine GHC version, core packages, core tools, etc. It then uses the
105`Stackage.Config` module to extract information on additional packages to be
106installed. The secondary approach is in `Stackage2.UpdateBuildPlan`, which will be
107discussed later.
109`BuildConstraints` does not specify a build completely. That is given by a
110`BuildPlan`, which is similarly broken down into `BuildPlan` and `PackagePlan`.
111In order to get a `BuildPlan`, we need two pieces of information: the
112`BuildConstraints`, and a package index. The package index (usually downloaded
113from Hackage) is a collection of all of the cabal files available.
115By applying a `BuildConstraints` to a package index (via `newBuildPlan`), we
116get a proposed `BuildPlan`. There is no guarantee that this `BuildPlan` is
117valid. To validate it, we use `checkBuildPlan`. A `BuildPlan` is an instance of
118both `ToJSON` and `FromJSON`, and therefore can be serialized to a file for
119later use.
121When dealing with LTS Haskell, we want to be able to take a `BuildPlan`, and
122update to a newer `BuildPlan` that keeps all packages at the same major
123version. `updateBuildConstraints` turns a `BuildPlan` into a new
124`BuildConstraints` with that restriction, and `updateBuildPlan` applies
125`newBuildPlan` to that result. As mentioned previously: this is *not* a
126validated result, and therefore `checkBuildPlan` must be used.
128A `BuildPlan` can be acted on. This is done to check that all packages compile
129together, run relevant test suites, test Haddock documentation is correct, and
130produce as artifacts both a self-contained GHC binary package database and a
131set of Haddock documentation. (Not yet implemented.)
133A `BuildPlan` may be converted into a bundle to be uploaded to Stackage Server.
134(Not yet implemented.)