This page describes how you can get started with developing new Haskell packages for inclusion in Debian GNU/Linux in general, and how to use the infrastructure developed by the DHG in particular.
Contents
Setting Up
In this section we will create an environment where you can build new Haskell packages for integration into the DHG package collection.
Note: The DHG infrastructure is not currently available in DebianStable.
Run unstable
First, make sure that you are running DebianUnstable. (You can do this on your development system itself or using debootstrap or a similar mechanism.)
Get Haskell platform
Now install and initialize the Haskell platform on your system:
sudo apt-get install haskell-platform cabal update
Get Package Consistency Checker
Next get our package consistency checker, and test that it runs:
git clone git@salsa.debian.org:haskell-team/package-plan.git
cd package-plan
sudo apt-get install libfile-slurp-perl libipc-run-perl \
liblist-moreutils-perl libtext-patch-perl libdpkg-perl \
cabal-install dctrl-tools patchutils
./test-packages.plThe result should be a message like the following:
705 packages successfully tested for co-installability. 198 packages have newer versions on hackage
with no mention of any errors. We do this to verify that our packages have no conflicts in their dependencies (to proactively avoid cabal dependency hell).
This allows you to check whether particular combinations of packages can be combined, an important aspect of the process as described below.
Download Experimental DHG Version of cabal-debian
Until we get our local changes pushed to upstream, you need to locally build an experimental cabal-debian tool.
git clone git@github.com:ddssff/cabal-debian.git cd cabal-debian cabal install cd ..
You also have to make sure that you have the local cabal binary in your PATH, for example with
export PATH="${PATH}:${HOME}/.cabal/bin"
Get Other Development Support Packages
If you also want to develop and upgrade packages, you should additionally
sudo apt-get install cabal-debian devscripts haskell-devscripts \
ghc-doc ghc-prof pkg-haskell-tools
git clone git@salsa.debian.org:haskell-team/DHG_packages.gitTo make signing work below, please make sure that you have a ~/.devscripts setup file with content like
# ~/.devscripts (see /etc/devscripts.conf for explanations). DEBSIGN_MAINT=krisrose@debian.org DEBSIGN_KEYID=0xC4D012FFE0163787
Below, we'll assume that you end up with a working directory that contains the package-plan and DHG_packages directories as siblings.
How To Check that a Particular Package Version Can Be Integrated
This section explains how to check that a package in Hackage of a particular version can be integrated. You should do this before integrating and building the package! (This is where cabal dependency hell is prevented.)
TL;DR
Assume we are adding or updating haskell-$pkg to $newversion.
cd package-plan git pull vi packages.txt ./test-packages.pl git commit -m "Checking haskell-$pkg at $newversion" packages.txt git push cd ..
Check that Package Version Is Not In Conflict
This is checked by adding the version information in the master DHG list and test that our addition does not create conflicts.
First make sure your package plan is the latest.
cd package-plan git pull cd ..
Assume that we want to check that version 1.0 of the package hello on Hackage can be integrated. Edit the file package-plan/packages.txt and add a line that contains
hello 1.0
in the alphabetically appropriate spot. If a line already exists for hello, then replace just the version number with the new one you need without touching the options (see the package-plan documentation for the possible annotations).
Save the file and then run
cd package-plan ./test-packages.pl cd ..
The script should finish with no errors. If there are errors then a more profound change is needed (see later).
Commit the new verified package plan (again, only if the test succeeds):
cd package-plan git commit -m 'Added hello 1.0' packages.txt git push cd ..
How To Debianize a New Package from Hackage To Be Under DHG Control
This section explains how a package is integrated into the DHG infrastructure after it has been checked that the version does not create conflicts, as discussed above.
TL;DR
Assume $CabalPkg is the Hackage package name and that the lower case version of that is $pkg.
cd DHG_packages/p git pull git pull --tags cabal unpack --pristine $CabalPkg mv $CabalPkg-* haskell-$pkg cd haskell-$pkg cabal-debian --official vi debian/changelog vi debian/control vi debian/copyright cd ../../..
Decide the DHG Name of the Source Package
DHG source packages are named haskell-* where the * is replaced with the Hackage package name in lower case. So a package named Hello will have the DHG source package name haskell-hello. We call these $CabalPkg and $pkg, respectively.
Update DHG Infrastructure
Update the DHG infrastructure, so you are sure you have the last version.
cd DHG_packages git pull git pull --tags cd ..
Verify that there is not a directory DHG_packages/p/haskell-$pkg.
Retrieve Sources To DHG Infrastructure
We first have to receive the sources for the package from Hackage with cabal. These should be in a directory with the name of the eventual DHG package, under DHG_packages/p. So, for our fictional $CabalPkg package, the proper command sequence is
cd DHG_packages/p cabal unpack --pristine $CabalPkg mv $CabalPkg-* haskell-$pkg cd ../..
Debianize the Sources
We now need to add the debian substructure. Thankfully, this is mostly automated by the cabal-debian tool. Run this first (still assuming the $pkg is set):
cd DHG_packages/p/haskell-$pkg cabal-debian --official cd ../../..
Note: If your package is a simple single program with no libraries or data files, then you may want to give the package name explicitly as cabal-debian --official --default-package haskell-$pkg to avoid that the Debian binary package is named haskell-$pkg-utils.
If the script finishes, this creates the directory package-plan/p/haskell-$pkg/debian with a bunch of files that should appear familiar. As of cabal-debian version 4.30.2, several of these files need to be adjusted:
changelog:
- Only refer to an ITP bug if you made one.
- Change the signer to yourself (not the DHG group).
control:
Add an Uploaders: entry with yourself.
Check that the X-Description: field is appropriate (it comes from the cabal description).
Fix any dependencies to packages named libghc-haskell-* to just libghc-*.
copyright:
- Check that the licenses are correctly attributed.
Make sure the top Copyright: field has the involved people.
Once these edits have been done, the package is debianized, and you can proceed to building it.
How To Update the Debianization of a Package Already Under DHG Control
This section explains how to update the debianization of a package already under DHG control to a new version, after it has been checked that the new version does not create conflicts, as discussed above.
We'll assume that you are updating the package haskell-$pkg to $newversion. We also assume that you have the directory DHG_packages/p/haskell-$pkg available.
TL;DR
cd DHG_packages/p/haskell-$pkg git pull git pull --tags debchange --newversion "$newversion" origtargz --unpack cabal-debian --official --upgrade cd ../../..
Update DHG Infrastructure
Update the DHG infrastructure, so you are sure you have the last version.
cd DHG_packages git pull git pull --tags cd ..
Verify that there is a directory DHG_packages/p/haskell-$pkg.
Create a New Changelog Entry
Update the debian/changelog to indicate the new version you will be building.
cd DHG_packages/p/haskell-$pkg debchange --newversion "$newversion" cd ../../..
Verify that the new entry in debian/changelog is as you wish it, especially that you are the change owner.
Download New Version Sources From Hackage
Get the sources of the new version.
cd DHG_packages/p/haskell-$pkg origtargz --unpack cd ../../..
Update the Debianization
Copy dependency changes from the new Cabal version of the package to the DHG control structure.
cd DHG_packages/p/haskell-$pkg cabal-debian --official --upgrade cd ../../..
Verify in DHG_packages/p/haskell-$pkg/debian that the changelog and control files are as you wish.
You have now debianized the new version of package.
How To Build and Upload a DHG-Debianized Package
TL;DR
cd DHG_packages/p/haskell-$pkg sudo mk-build-deps --install --remove debian/control debuild -us -uc cd .. dht upload haskell-$pkg_*changes cd ../..
Make Sure All Build Dependencies Are Installed
We first make sure that all build dependencies are there.
cd DHG_packages/p/haskell-$pkg sudo mk-build-deps --install --remove debian/control cd ../../..
The mk-build-deps command can be omitted if you already have all build dependencies; in some cases it will not succeed, and you have to manually install the build dependencies.
Build the Debian Package
We can now build the binary packages! We do so without signing them (yet).
cd DHG_packages/p/haskell-$pkg debuild -us -uc cd ../../..
The mk-build-deps command can be omitted if you already have all build dependencies; in some cases it will not succeed, and you have to manually install the build dependencies.
If the build fails then fix the errors; this includes errors from lintian (marked with E: in the output).
Once the package has been built, you should have a file with a name like DHG_packages/p/haskell-$pkg_*.changes.
Commit the Updated Debianization to Git
Once the package builds, you can commit the debianization to Git.
cd DHG_packages/p/haskel-$pkg ./debian/rules clean git add debian/ git commit -m "Debianization updated for haskell-$pkg to $newversion." git push cd ../../..
(You can only do this if you are in the haskell-team group on Salsa – if not then talk to us!)
Upload the Package
For this step you need to be a DebianDeveloper.
Once you have finished the above steps and built a debian package, you are ready to upload it! For the DHG infrastructure, we use a helper script for this to also tag the DHG_packages archive itself.
cd DHG_packages/p dht upload haskell-$pkg_*.changes cd ../..
Please complete the haskell-$pkg_*.changes name to make sure you have the right version (there may be old ones around).
Note: See the manual of dht (installed by pkg-haskell-tools) to see more possibilities, including help on finding out of date or missing packages, and mass building.