Submit PRs with patch(es) relative to the source tarball(s) of existing Hackage package(s).
-
The patches MUST apply cleanly by
patch -p1
when inside the original unpacked source-tarball. (Travis CI will verify this when you submit a PR). -
The patches SHOULD work with at least GHC HEAD and the most recent stable released GHC version (currently this means with GHC 8.2.2, GHC 8.4.1-alpha, and GHC 8.5).
-
The patches SHOULD ideally result in the same code being compiled, as one of the main purposes of these patches is to make regression testing possible. I.e. try to avoid conditional compilation.
-
If only the
.cabal
file needs to be modified, a.cabal
file SHOULD be used instead of a.patch
file. If the changes to the.cabal
file are too invasive (e.g. removing modules, changing the structure of the package etc), a.patch
file must be used.
This repo contains <pkg-id>.patch
and <pkg-id>.cabal
files in the
patches/
folder (where <pkg-id>
refers to a specific
release of a package, e.g. lens-4.15.3
).
Once merged to master
, all package releases whose <pkg-id>
is
mentioned will enter the HEAD.hackage package index; if there is a
.patch
file, the respective releases tarballs are patched
(i.e. mutated!). If there is a .cabal
file, it is included as a
revision in the package index. Consequently, if there is only a
.cabal
file and no .patch
file, the original source .tar.gz
is
included verbatimely (i.e. not mutated).
If this operation succeeds, the HEAD.hackage
package index at
http://HEAD.hackage.haskell.org/ is updated to contain the new index
state.
HEAD.hackage
contains only a small subset of package releases,
and needs to be combined with the main Hackage repository.
Cabal's new nix-style local build facility makes sure that the modified packages don't contaminate your package databases, while allowing to maximise sharing via the nix-style package-db cache store.
It is not recommended to add the HEAD.hackage
repository index to
your global cabal configuration.
Instead, you should mix in the HEAD.hackage
repository on a
per-project level. Then the packages in the HEAD.hackage
will
overlay those from the main package index, by adding the repository stanza (as shown on http://head.hackage.haskell.org) to the cabal.project(.local)
file or use head.hackage.sh init
(see below).
To workaround some current issues in cabal
and make it more
convenient, the script
scripts/head.hackage.sh
is provided,
which facilitates common tasks.
It's been tested on Linux so far. Other operating systems may require tweaks (patches welcome!).
The main operations provided are
-
head.hackage.sh update
: Resets & syncs the local package download cache for theHEAD.hackage
repo. -
head.hackage.sh init
: generates a newcabal.project
file with arepository
stanza enabling theHEAD.hackage
repo locally. This command also takes an optional list of arguments which are included asoptional-packages:
declarations in the resultingcabal.project
file. -
head.hackage.sh init-local
: generate acabal.project.local
file instead. -
head.hackage.sh dump-repo
: printrepository
stanza to stdout
The HEAD.hackage
package repo can also be generated as a file-based
local repository. The handling is similiar to using HEAD.hackage
via
a remote repo.
TODO: provide scripting
The process of applying patches can be used in a cabal project with local packages.
You can add something like optional-packages: */*.cabal
to your
cabal.project
file, and then for each package-id with a .patch
or
.cabal
file you want to provide as a locally patched package do
$ cabal unpack --pristine $PKGID
$ cd $PKGID/
$ patch -p1 -i ${WhereThisGitHubRepoIsCloned}/patches/$PKGID.patch
$ cp ${WhereThisGitHubRepoIsCloned}/patches/$PKGID.cabal ./*.cabal
$ cd ..
TODO: implement script
The Travis CI script generator has recently added support for enabling the HEAD.hackage
repository automatically for jobs using unreleased GHC versions.
The patches maintained for the head.hackage
project can also be used with Nix (not to be confused with Cabal's Nix-style local builds). See the README in the script/
folder and/or the
Using a development version of GHC with nix blogpost for more information.