## page was renamed from Haskell/CollabMaint/GettingStarted 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. <> = 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|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.pl }}} The 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 [[https://wiki.haskell.org/Cabal/Survival|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.git }}} To 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: 1. `changelog`: * Only refer to an ITP bug if you made one. * Change the signer to yourself (not the DHG group). 1. `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-*`. 1. `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.