git.iko.soy/stackage
on 4e30926 help sign in
stackage/README.md
115 lines 5.0 kB history raw
1stackage
2========
4[![Build Status](https://travis-ci.org/fpco/stackage.svg?branch=master)](https://travis-ci.org/fpco/stackage)
6"Stable Hackage," tools for creating a vetted set of packages from Hackage.
8__NOTE__ This repository is for package authors to get their code into
9Stackage. If you simply want to use Stackage as an end user, please follow the
10instructions on [http://www.stackage.org/](http://www.stackage.org).
12The Stackage project consists of multiple repositories. This repository
13contains the metadata on packages to be included in future builds and some
14project information. In addition, we have the following repositories:
16* [stackage-server](https://github.com/fpco/stackage-server) [![Build Status](https://travis-ci.org/fpco/stackage-server.svg?branch=master)](https://travis-ci.org/fpco/stackage-server)
17* [stackage-curator](https://github.com/fpco/stackage-curator) [![Build Status](https://travis-ci.org/fpco/stackage-curator.svg?branch=master)](https://travis-ci.org/fpco/stackage-curator)
18* [stackage-types](https://github.com/fpco/stackage-types) [![Build Status](https://travis-ci.org/fpco/stackage-types.svg?branch=master)](https://travis-ci.org/fpco/stackage-types)
19* [lts-haskell](https://github.com/fpco/lts-haskell)
21Get your package included
22-------------------------
24In order to get your package included in the set of stable packages, you should
25send a pull request against this repository. In the [`build-constraints.yaml`](https://github.com/fpco/stackage/blob/master/build-constraints.yaml) file,
26there's a section called `packages`. In general, to add a set of
27packages, you would add:
29 "My Name myemail@example.com @mygithubuser":
30 - package1
31 - package2
32 - package3
34You can follow the examples of the other sets of packages in that function.
35Once you've done this, you can send a pull request to get your package
36included.
38__NOTE__: In order to ease the process of adding new packages, we no longer
39require new submissions to be tested on your own system before sending a pull
40request. If you believe your package works with the newest versions of all
41dependencies, you may send a pull request without testing first.
43You should also read the [maintainers
44agreement](https://github.com/fpco/stackage/wiki/Maintainers-Agreement).
46Package Author Guidelines
47-------------------------
49There are some basic rules to get your package to play nice with Stackage. Here
50are some quick guidelines to hopefully make this easier:
52* Make sure that your code is buildability and testable from Hackage. Often
53 times, authors test their builds locally, but the tarball that gets uploaded
54 to Hackage is missing some necessary files. The best way to do this is to
55 set up a Travis job to do it for you. We recommend the
56 [multi-ghc-travis](https://github.com/hvr/multi-ghc-travis) approach.
57* Make your code compatible with the newest versions of all dependencies.
58* Make your code compatible with the versions of libraries that ship with GHC ([more information on lenient lower bounds](https://www.fpcomplete.com/blog/2014/05/lenient-lower-bounds)).
60There are certainly many other tips that could be added here. If you think of
61any, please send a pull request!
63Build the package set
64---------------------
66Generally, building the package set should be done only by the Jenkins machine
67or by the official maintainers, as the process does require quite a bit of
68setup on the local machine. That said, you'll likely be able to get a stable
69build by running:
71 cabal update
72 cabal install stackage
73 stackage nightly
75### Docker
77Note: This method has been disabled for now, but may be enabled again in the future.
79If you'd like to check a build plan, or perform an entire build, without
80specially configuring your system, Docker may be a good approach. To check if
81some modifications to `build-constraints.yaml` are valid, try the following:
831. Create a local clone of the `stackage` repo
842. Make modifications to your local `build-constraints.yaml`
853. Inside the `stackage` working directory, run the following:
87 ```
88 $ docker run -it --rm -v $(pwd):/stackage -w /stackage snoyberg/stackage /bin/bash -c 'cabal update && stackage check'
89 ```
91Similarly, if you'd like to perform an entire build, you can replace the last step with:
93```
94$ docker run -it --rm -v $(pwd):/stackage -w /stackage snoyberg/stackage /bin/bash -c 'cabal update && stackage nightly --skip-upload'
95```
97## Processing
99The following describes at a high level the series of steps for processing
101### Nightlies
1031. Get list of core packages
1042. Get build constraints from list of maintained packages
1053. Load up package index
1064. Calculate build plan using newest versions of packages
1075. Write out a YAML file with complete build plan
1086. Verify that the build plan can be compiled
1097. Perform the build
111### LTS
1131. Load up most recent build plan
1142. Convert build plan into constraints for next build
1153. Continue from step (3) above