Preparing the DCSS Debian Package
---------------------------------

This guide covers making the packages from a debian system like Debian or
Ubuntu and installing these into the CDO repo. We currently produce packages
for both i386 and amd64 architectures, and the guide has steps for building
these using cowbuilder and pbuilder, based on the debian directory in
crawl-ref/source/debian of the repo.

The Debian maintainer's guide is a good resource for working with debian
packages:

https://www.debian.org/doc/manuals/maint-guide/index.en.html


0.1. Software Prerequisites

   Install the cowbuilder and pbuilder packages:

   sudo apt-get install cowbuilder

   See the following websites if you have trouble with cowbuilder or pbuilder
   during any of these steps:

   https://wiki.debian.org/cowbuilder
   https://wiki.debian.org/PbuilderTricks

   Set up your DEBFULLNAME and DEBEMAIL shell variables using the name and
   email you use in the git mailmap. This can be done in the shell or in your
   pbuilderrc file (see below). To set them in the shell:

   export DEBFULLNAME="yourname"
   export DEBEMAIL="your@email"


0.2 Release Prerequisites

   Before building the packages, you should have the release version tagged
   with all commits included, including final changelog.txt entry for the
   version. Additionally this tag should include a commit updating
   crawl-ref/source/debian/changelog text file.

   To make this commit, you need to add an entry to this file in the following
   format:

   crawl (2:VER-1) unstable; urgency=low

     * Major bugfix release

    -- devname <devemail>  TIMESTAMP

   You can copy the previous entry, update the version, and use output from the
   `date' command to update the timestamp. The format must match the previous
   entries. A command like the following will give you a valid timestamp:

   date +'%a, %d %b %Y %R:%S %z'

   Before you make the commit with the changelog entry, it's a good idea to
   make a version tag for testing purposes and try the steps 1 through 6 below
   to make sure that the changelog entry you made is right and that the package
   will build with pbuilder. You can make a test tag (using version 0.17.0 as
   an example) with a command like:

   git tag -a 0.17.0

   Any error in the format will happen early in the test package build, so you
   don't have to wait for it to finish. If the entry seems fine, you can make
   the commit updating the debian changelog and tag the final release. You can
   delete your testing tag with:

   git tag -d 0.17.0

   See guide.txt in this directory for details on making the release.


1. Make a copy of the of the source packages and extract

   The source packages should be made using the package-source target. Run the
   following from the source directory if you haven't yet:

   make package-source

   This will make several files in the toplevel repo dir, but you specifically
   need the stone_soup-VER-tar.xz file. Copy this to a location where you'd
   like to prepare the packages, then exactract the source directory and rename
   the original file. Using version 0.17 as an example and with ~/crawl-deb as
   my staging directory:

   mkdir -p ~/crawl-deb
   cp stone_soup-0.17.0.tar.xz ~/crawl-deb
   cd ~/crawl-deb
   tar Jxf stone_soup-0.17.0.tar.xz
   mv stone_soup-0.17.0 crawl-0.17.0
   mv stone_soup-0.17.0.tar.xz crawl-0.17.0.orig.tar.xz

   The name formats of crawl-VER and crawl-VER.orig.EXT for the source
   directory and archive are specifically looked for by pbuilder, so these
   renaming steps are required.


2. Copy and update the debian directory in the source directory

   We need the crawl-ref/source/debian directory to be at the top level to
   build the package. Using 0.17.0 as an example, and assuming we're already in
   our staging directory with the unpacked source:

   cd crawl-0.17.0
   cp -r source/debian .


3. Set up your pbuilderrc

   We use the cowbuilder program to create the copy-on-write chroot
   directories, and use pbuilder to build the packages in the chroot. A
   pbuilderrc file is needed to tell pbuilder to use the cowbuilder system and
   to set downstream shell variables. To use the example pbuilderrc file in
   this directory, copy it to ~/.pbuilderrc or (as root) to /etc/pbuilderrc
   after making any modifications.

   You can edit this file to set DEBFULLNAME and DEBEMAIL to your name and
   email if you didn't do that in your shell already. In the example
   pbuilderrc, all pbuilder-related data go in /var/cache/pbuilder. To change
   this, you'll need to modify at least BASEPATH, BUILDPLACE, BUILDRESULT, and
   APTCACHE.


4. Create a .cow chroot directory for each architecture.

   You'll need a cowbuilder chroot directory for each architecture you want to
   build. If you're using the example pbuilderrc, we use the scheme
   `DIST-ARCH.cow'. For example, when building based on debian stable, we'll
   use:

       /var/cache/pbuilder/stable-amd64.cow
       /var/cache/pbuilder/stable-i386.cow

   To create these, run the following:

   sudo cowbuilder --create --architecture amd64 \
     --basepath /var/cache/pbuilder/stable-amd64.cow
   sudo cowbuilder --create --architecture i386 \
     --basepath /var/cache/pbuilder/stable-i386.cow

   This chroot directory needs to be created only once for each OS/ARCH/DIST
   combination on which you what to build the package. It doesn't need to be
   recreated if you're only building a different DCSS version, but if you're
   using a different value for any of OS, ARCH, or DIST, you'll need to create
   a corresponding .cow chroot.


5. Build the packages

   Asuming your pbuilderrc is based on the example one in this directory, you
   need to set some of the shell variables ARCH, DIST, and OS to set up
   downstream variables to build the packages for the architectures (e.g. i386
   or amd64) you want and against the distribution you want (e.g. stable or
   testing for Debian), and possibly based on the OS you want (debian or
   ubuntu) if you want to e.g. build against debian on an ubunutu host system.

   Run pdebuild from the `crawl-VER' source directory you made above. The
   simplest build situation is making packages for the same architecture and
   against the same distribution as your host system. Using our 0.17.0 example
   building against debian stable on a debian stable system for amd64, simply:

   sudo pdebuild

   To build the i386 package:

   sudo ARCH=i386 pdebuild

   If you're on ubuntu, building against debian stable, you might need:

   sudo OS=debian DIST=stable pdebuild
   sudo OS=debian DIST=stable ARCH=i386 pdebuild

   Once the package building is finished, the results well be in
   /var/cache/pbuilder/result, if you're using the example pbuilderrc.


6. Test install the packages

   Test the built packages in /var/cache/pbuilder/result by installing them;
   you'll need to install the crawl_VER_ARCH.deb, crawl-tiles_VER_ARCH.deb, and
   crawl-common_VER.deb packages. For example:

   dpkg -i /var/cache/pbuilder/results/crawl_0.17.0-1_amd64.deb  \
           /var/cache/pbuilder/results/crawl-tiles_0.17.0-1_amd64.deb \
           /var/cache/pbuilder/results/crawl-common_0.17.0-1_amd64.deb \
           /var/cache/pbuilder/results/crawl-tiles-data_0.17.0-1_amd64.deb

   Run the console version with `crawl' and the tiles version with
   `crawl-tiles' to see if they work.


7. Upload files to CDO, install into the repo, and test

   You'll need to upload the deb files above in addition to the
   `crawl_VER-1.dsc' file to the crawl account on CDO. The staging directory
   ~/upload/deb-files can be used for this, but you'll need to clear out the
   previous release files.

   We install each release into a component named after the major version of
   the release. If you're logged into CDO, go to the repository root directory
   `deb' and install the .deb files and the .dsc file using reprepro. An
   example using 0.17 and ~/upload/deb-files as a staging directory):

   cd ~/deb
   for i in ../upload/deb-files/*.deb
       do reprepro -C 0.17 includedeb crawl "$i"; done
   for i in ../upload/deb-files/*.dsc
       do reprepro -C 0.17 includedsc crawl "$i"; done

   Make sure to use the right major version number in those -C arguments.

   Note: If you messed something up and need to upload a new build of packages
   for a version already installed in the repo, you can remove the installed
   debs with a command like the following (run from ~/deb):

   reprepro -C 0.17 remove crawl crawl crawl-common crawl-tiles crawl-tiles-data

   To test that the repository is working, follow the apt instructions on the
   download page to add the DCSS repo and signing key, being sure to use the
   correct crawl major version in sources.list. Then update your apt-cache, and
   install the crawl and crawl-tiles packages on your system.


8. Update the download page

   The major version in the example command to add the repository URL should be
   updated. See release.txt for details on keeping the CDO website in sync with
   the website repository.


At this point, the repository should be working and the packages ready for
users to install with apt.
