Debian/Ubuntu installer developing

 

Tools required for the development

The following packages come with the standard Debian installation, so you probably have them already. Still, you should check with `dpkg -s <package>`.

• dpkg-dev
  this package contains the tools needed to unpack, build and upload Debian source packages.

• file
  this handy program can determine what type a file is.

• gcc
  the GNU C compiler, necessary if your program like most others is written in the C programming language. This package will also "pull in" several other packages such as binutils which includes programs used to assemble and link object files

• g++
  the GNU C++ compiler, necessary if your program is written in C++. 

• libc6-dev
  the C libraries and header files gcc needs to link with to create object files. (see `info libc` in the glibc-doc package)

• make
  usually creation of a program takes several steps, so rather than having to type out the same commands over and over again, you can use this program to automate the process, creating `Makefile's.

  You'll probably want to install the following packages, too:

• dh-make and debhelper
  dh-make is necessary to create the skeleton of our example package, and it will use some of the debhelper tools for creating packages. 

• devscripts
  this package contains some nice and useful scripts that can be helpful to the maintainers.

• fakeroot
  this utility lets you emulate being root which is necessary for some parts of the build process. (see fakeroot(1))

• gnupg
  a tool that enables you to digitally sign packages. This is especially important if you want to distribute it to other people, and you will certainly be doing that when your work gets included in the Debian distribution. 

• lintian
  this is the Debian package checker that can let you know of any common mistakes after you build the package, and explain the errors found.

Initial debianization

Please note that you should run dh_make only once, and that it won't behave correctly if you run it again in the same, already "debianized", directory.

Make sure you're in the program source directory, and issue this:

       dh_make -e your.maintainer@address -f ../openacs-5.1.5.tar.gz

Of course, replace the string "your.maintainer@address" with your e-mail address for inclusion in the changelog entry and other files.

Some information will come up. It will ask you what sort of package you want to create. Gentoo is a single binary package - it creates only one binary, and thus one .deb file - so we will select the first option, with the `s' key, check the information on the screen and confirm by pressing <enter>.

After this execution of dh_make, a copy of the upstream tarball is created as openacs-5.1.5.orig.tar.gz in the parent directory to accommodate the creation of the non-native Debian source package with the diff.gz

Debian release

Let's say that a bug report was filed against your package and it describes a problem that you can solve. To create a new Debian revision of the package, you need to:

• Correct the problem in the package source, of course.

• Add a new revision at the top of the Debian changelog file, for example with `dch -i`, or explicitly with `dch -v <version>-<revision>' and then insert the comments using your preferred editor.

        Tip: how to easily get the date in required format? Use `822-date', or `date -R'.
        Include a short description of the bug and the solution in the changelog entry.

• Repeat a complete rebuild of the package. 

New upstream release

Let's consider a different, slightly more complicated situation - a new upstream version was released, and of course you want it packaged. You need to do the following:
 

• Download the new sources and put the tarball (e.g. named `openacs.5.2.1.tar.gz') in the directory above the old source tree (e.g. ~/openacs/).

• Enter the old source directory, and run:

            uupdate -u openacs.5.2.1.tar.gz
            uupdate will properly rename that tarball, try to apply all the changes from your previous .diff.gz file, and                 update the new debian/changelog file.

• Change directory to `../openacs.5.2.1', the new package source tree, and repeat a complete rebuild of the package

Complete rebuild

Enter the program's main directory and then issue this command:
        dpkg-buildpackage -rfakeroot

This will do everything for you. It will:

• clean the source tree (debian/rules clean), using fakeroot

• build the source package (dpkg-source -b)

• build the program (debian/rules build)

• build the binary package (debian/rules binary), using fakeroot

• sign the source .dsc file, using gnupg

• create and sign the upload .changes file, using dpkg-genchanges and gnupg

The only input that will be required of you is your GPG key secret pass phrase, twice.

After all this is done, you will see the following files in the directory above (~/openacs/):

• openacs_5.1.5.orig.tar.gz

This is the original source code tarball, merely renamed to the above so that it adheres to the Debian standard. Note that this was created using the `-f' option to dh_make when we initially ran it.

• openacs_5.1.5.dsc

This is a summary of the contents of the source code. The file is generated from your `control' file, and is used when unpacking the source with dpkg-source. This file is GPG signed, so that people can be sure that it's really yours.

• openacs_5.1.5.diff.gz

This compressed file contains each and every addition you made to the original source code, in the form known as "unified diff". It is made and used by dpkg-source. Warning: if you don't name the original tarball packagename_version.orig.tar.gz, dpkg-source will fail to generate the .diff.gz file properly!

If someone else wants to re-create your package from scratch, they can easily do so using the above three files. The extraction procedure is trivial: just copy the three files somewhere else and run dpkg-source -x openacs_5.1.5.dsc.

• openacs_5.1.5_i386.deb

This is your completed binary package. You can use dpkg to install and remove this just like any other package.

• openacs_5.1.5_i386.changes

This file describes all the changes made in the current package revision, and it is used by the Debian FTP archive maintenance programs to install the binary and source packages in it. It is partly generated from the `changelog' file and the .dsc file. This file is GPG signed, so that people can be sure that it's really yours.

Trivial repository construction

Trivial repositories consist of one root directory and of as many subdirectories as you wish. As the users have to specify the path to the root of the repository and the relative path between the root and the directory with the index files in it, you are free to do whatever you want (even to put everything into the root of the repository; then, the relative path will be simply “/”)

We'll create a trivial repository with two subdirectories 

(your repository root)
|
|-binary
+-source

 Creating Index Files

dpkg-scanpackages generates the Packages file and dpkg-scansources the Sources file.

They both send their output to stdout; thus, to generate compressed files, you can use a command chain like this one: dpkg-scanpackages arguments | gzip -9c > Packages.gz.

The two tools work the same way; they both take two arguments (in reality there are more, but I won't go into that here; you can read the manpages if you want to know more); the first the directory under which the packages are, and the second is the override file. We don't need override files for simple repositories, but as it is a required argument, we simply pass /dev/null.

dpkg-scanpackages scans the .deb packages; dpkg-scansources scans the .dsc files. It is thus necessary to put the .orig.gz, .diff.gz and .dsc files together. The .changes files are not needed.

$ cd my-repository
$ dpkg-scanpackages binary /dev/null | gzip -9c > binary/Packages.gz
$ dpkg-scansources source /dev/null | gzip -9c > source/Sources.gz

From Debian Maintainers' Guide, installer developed by Otto Solares updated by Adrián Catalán at Galileo University as a part of the E-LANE project

Related instructions for installing at:

• en:debian
• en:ubuntu