Packaging

This is a quick guide to creating and maintaining a debian package for internal use within an organization (such as Free Geek Vancouver).

For more detail and discussion of creating official packages, please refer to The Debian new maintainers guide

Setting up the tools

This should have instructions on how to setup the debian tools. Things like which packages need to be installed and how to setup environment variables like DEBFULLNAME/DEBEMAIL. Unfortunately it hasn't yet been written, perhaps you could flesh out this section?

For uploading the package, dput is the currently recommended tool. To configure it for Free Geek edit ~/.dput.cf and put the following into it:

 [freegeek]
 fqdn = alder.shop.lan
 method = scp
 allow_unsigned_uploads = 1
 run_dinstall = 0
 incoming = /srv/apt/freegeekvancouver/incoming

Creating a new package

The following script sets up the bare minimum for a package. To create a more complex package consider looking at the dh_make utility from debhelper. The following is intended to be ran in a Ubuntu/Debian terminal

Set the package name for use in the following script, replace package-name with your package name:

 PNAME=package-name

Now copy and paste the following in a terminal to create the necessary structure. It will open the changelog for you to update, the control file which describes the package and the copyright information:

 # Create the directory for the package
 mkdir "${PNAME}-v1.0.0"
 cd "${PNAME}-v1.0.0"
 mkdir "debian"
 echo "9" > debian/compat
 # Create the control file
 echo "Source: ${PNAME}
 Maintainer: ${DEBFULLNAME:-My Name} <${DEBEMAIL:[email protected]}>
 Section: misc
 Priority: optional
 Standards-Version: 3.9.5
 Build-Depends: debhelper (>= 9)
 
 Package: ${PNAME}
 Architecture: all
 Depends: \${misc:Depends}
 Description: ${PNAME} (could be described better)
  A blurb about ${PNAME} which can span multiple lines" \
 | sed 's/^ //' > debian/control
 
 # Create the copyright file
 echo "Format: http://www.debian.org/doc/packaging-manuals/copyright-format/1.0/
 
 Files: *
 Copyright: 2014 Free Geek Vancouver
 License: GPL-3+
 
 License: GPL-3+
  This program is free software: you can redistribute it and/or modify
  it under the terms of the GNU General Public License as published by
  the Free Software Foundation, either version 3 of the License, or
  (at your option) any later version.
  .
  This program is distributed in the hope that it will be useful,
  but WITHOUT ANY WARRANTY; without even the implied warranty of
  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  GNU General Public License for more details.
  .
  The full text of the GPL is distributed as in
  /usr/share/common-licenses/GPL-3 on Debian systems." \
 | sed 's/^ //' > debian/copyright
 
 echo -e '#!/usr/bin/make -f\n%:\n\tdh [email protected]' > debian/rules
 chmod +x debian/rules
 mkdir debian/source
 echo "3.0 (native)" > debian/source/format
 
 # Create the changelog
 dch --create -v 1.0.0 --package "${PNAME}" --empty
 dch -a 'Initial release.' 2> /dev/null
 editor debian/changelog debian/copyright debian/control
 echo "Your package is now ready to build"

Adding files

To specify which files are to be added to the output package, create a debian/package-name.install and list the directories or individual files from the top level which should be included in the final package.

The debhelper scripts can also make use of more complex build processes refer to man dh_install for further details.

Updating and releasing a package

Releasing a package consists of the usual updating of component files, then updating the debian changelog, building the package and uploading it.

As you develop individual changes should be added to the changelog by running:

 dch -a 'Description of change'

To release the package run (In the top level directory of the project):

 dch -r
 debuild -us -uc
 dput freegeek ../*.changes

At this point you should also commit, tag, and push the project if appropriate.

Finally add a new changelog entry for future development:

 dch -i