Creating Deb Packages from the downloaded material.

Creating `Deb` Packages from the downloaded material.
	Deb-packaging: multiple packages from the same source

Creating `Deb` Packages from the downloaded material.

	Warning
	The procedure below has been documented right after executing it, instead of the usual during. So beware of missing details.

Unpacking the gzipped files
We create a directory magma-2.15.10 ^[30] and unzip the files into it, giving:
-rw-r--r-- 1 jurjen jurjen 8931 2008-12-05 11:53 README.txt -rw-r--r-- 1 jurjen jurjen 12218 2009-01-23 01:53 INSTALL.txt -rw-r--r-- 1 jurjen jurjen 29660016 2009-06-15 11:14 magma.amd64.exe -rwxr-xr-x 1 jurjen jurjen 24230904 2009-06-15 11:14 magma.gen.exe.dyn.i386 -rw-r--r-- 1 jurjen jurjen 28259272 2009-06-15 11:14 magma.intel64.exe drwxr-xr-x 2 jurjen jurjen 136 2009-06-15 11:44 ThirdParty drwxr-xr-x 18 jurjen jurjen 4096 2009-06-15 11:44 package drwxr-xr-x 14 jurjen jurjen 4096 2009-06-15 11:44 libs drwxr-xr-x 2 jurjen jurjen 119 2009-06-15 11:44 InternalHelp drwxr-xr-x 3 jurjen jurjen 4096 2009-06-15 11:44 doc -rwxr-xr-x 1 jurjen jurjen 1394 2009-06-18 13:05 magma
Adjustment of the downloaded files
Judging from the INSTALL.txt, magma is usually installed monolithically, with all executables, documentation, license files and whatnot in a single tree. This is particularly well suited for installation on a network share, but it isn't for packages. To create packages, the HTML doc files will go into /usr/share/doc/magma, the config will go into /etc, large parts of the package will go into /usr/shared/magma, and at least a binary or script will have to go into /usr/bin. In order to facilitate that, we modify the magma script a bit, so that it accepts config in /etc/magma/magma.conf, which we also provide:
```
# This is where most of Magma goes
ROOT="/usr/share/magma"

# The admin can install the magmapassfile by hand in /etc/magma
MAGMAPASSFILE="$CONFDIR/magmapasswfile"

# If there is no magmapassfile in /etc/magma, look for it in the users' homedir.
# It won't be distributed with the package, so the default of looking in
# /usr/share/magma doesn't make sense.
[ -r $MAGMAPASSFILE ] || MAGMAPASSFILE="~/magmapassfile"

# The html/pdf help has been relocated at /usr/share/doc/magma
MAGMA_HTML_DIR="/usr/share/doc/magma/html"
	  
```

Creating a Makefile

We create a rudimentary Makefile, with an eye already on the multiple packages we want to create. Please note the usage of $(DESTDIR) to ease the use of debhelper scripts.

all:

install: install-doc install-common install-bin install-bin-i386 install-bin-amd64

install-doc:
install -d $(DESTDIR)/usr/share/doc/magma/html
cp -rp doc/* $(DESTDIR)/usr/share/doc/magma/html

install-common:
install -d $(DESTDIR)/usr/share/doc/magma
install -t $(DESTDIR)/usr/share/doc/magma README.txt INSTALL.txt
install -d $(DESTDIR)/usr/share/doc/magma/ThirdParty
install -t $(DESTDIR)/usr/share/doc/magma/ThirdParty ThirdParty/*
install -d $(DESTDIR)/usr/share/magma
cp -rp InternalHelp $(DESTDIR)/usr/share/magma
cp -rp package $(DESTDIR)/usr/share/magma
cp -rp libs $(DESTDIR)/usr/share/magma

clean:
rm -rf \
$(DESTDIR)/usr/share/doc/magma \
$(DESTDIR)/usr/share/magma

install-bin:
install -d $(DESTDIR)/usr/share/magma/bin
install -d $(DESTDIR)/usr/bin
install magma $(DESTDIR)/usr/bin/

install-bin-i386: install-bin
install  magma.gen.exe.dyn.i386 $(DESTDIR)/usr/share/magma/bin

install-bin-amd64: install-bin
install magma.amd64.exe $(DESTDIR)/usr/share/magma/bin
install magma.intel64.exe $(DESTDIR)/usr/share/magma/bin


install-config:
install -d $(DESTDIR)/magma
install -t $(DESTDIR)/magma magma.conf

Initial Debianization
To build the debian subdirectory, with examples, while in the magma-2.15.10 directory, we issue:
dh_make -e j.bokma --native -m

The control files

We edit debian.control to contain multiple packages:

Source: magma
Section: non-free/math 
Priority: extra
Maintainer: Jurjen Bokma <j.bokma@rug.nl>
Build-Depends: debhelper (>= 7)
Standards-Version: 3.7.3
Homepage: https://magma.maths.usyd.edu.au

Package: magma-common
Section: non-free/math
Architecture: all
Depends: ${shlibs:Depends}, ${misc:Depends} 
Suggests: magma-doc
Description: Magma, a powerful mathematics package, common files
Magma (https://magma.maths.usyd.edu.au) is 'a large, well-supported 
software package designed to solve computationally hard problems
in algebra, number theory, geometry and combinatorics. It provides
a mathematically rigorous environment for computing with algebraic,
number-theoretic, combinatoric, and geometric objects.'
This package contains the architecture-independent files.
Architecture-specific binaries are in the magma-<architecture>
packages.

Package: magma-doc
Section: non-free/doc
Architecture: all
Description: Documentation for Magma
Magma (https://magma.maths.usyd.edu.au) is 'a large, well-supported
<snip>

Package: magma-bin-i386
Section: non-free/math
Architecture: i386 
Depends: magma-common
Conflicts: magma-amd64
Description: 32-bit i386 binary for Magma
Magma (https://magma.maths.usyd.edu.au) is 'a large, well-supported
<snip>

Package: magma-bin-amd64
Section: non-free/math
Architecture: amd64
Depends: magma-common
Conflicts: magma-i386
Description: 64-bit amd64 binaries for Magma
Magma (https://magma.maths.usyd.edu.au) is 'a large, well-supported
<snip>

	If a package goes into `contrib` or `non-free`, both area and section have to be mentioned, like done here.
	The package `magma-common` doesn't depend on any of the binaries. You could argue that it should, as it provides no functionality of its own, but circular dependencies must not happen. So the only denpendency is the other way around: the `magma-bin-*` packages depend on `magma-common`.
	The long decription must be indented by spaces.
	One could argue that the `magma-bin-i386` package should also be generated for `amd64` architectures. We don't.

Multiple packages from one source
1. As can be seen above, the debian/control file must list multiple packages.
2. Wherever the control files are package-specific, their name should be prefixed with the package name and a dot, so instead of debian/install we get debian/magma-common.install, debian/magma-doc.install etc. All in all, in debian/ we have:
  -rw-r--r-- 1 jurjen jurjen 2 2009-06-16 11:08 compat -rw-r--r-- 1 jurjen jurjen 495 2009-06-16 11:08 magma.doc-base.EX -rw-r--r-- 1 jurjen jurjen 171 2009-06-16 11:08 README.Debian -rw-r--r-- 1 jurjen jurjen 34 2009-06-16 11:08 docs -rw-r--r-- 1 jurjen jurjen 128 2009-06-16 11:08 changelog -rw-r--r-- 1 jurjen jurjen 154 2009-06-16 11:08 README -rw-r--r-- 1 jurjen jurjen 32 2009-06-16 11:27 dirs -rw-r--r-- 1 jurjen jurjen 25 2009-06-18 12:37 magma-doc.install -rw-r--r-- 1 jurjen jurjen 1080 2009-06-18 16:17 magma-bin-i386.postinst -rw-r--r-- 1 jurjen jurjen 967 2009-06-18 16:19 magma-bin-i386.postrm -rw-r--r-- 1 jurjen jurjen 967 2009-06-19 11:36 magma-bin-amd64.postrm -rw-r--r-- 1 jurjen jurjen 1561 2009-06-19 11:45 magma-bin-amd64.postinst -rw-r--r-- 1 jurjen jurjen 783 2009-06-19 11:45 copyright -rw-r--r-- 1 jurjen jurjen 2553 2009-06-19 12:38 control -rw-r--r-- 1 jurjen jurjen 57 2009-06-19 13:14 magma-bin-i386.install -rw-r--r-- 1 jurjen jurjen 88 2009-06-19 13:14 magma-bin-amd64.install -rw-r--r-- 1 jurjen jurjen 177 2009-06-19 13:15 magma-common.install -rwxr-xr-x 1 jurjen jurjen 2942 2009-06-19 14:27 rules
3. The *.install files list per package the files that should be copied into the packages and where they should be copied. E.g. for magma-bin-amd64.install:
  usr/bin/magma usr/share/magma/bin/magma.amd64.exe usr/share/magma/bin/magma.intel64.exe
4. The debian/rules file, in particular, must not be prefixed. It must remain, but a few adjustments are necessary relative to a single-package rules file.
  The install-indep target has to be tweaked a bit:
  # Add here commands to install the indep part of the package into # debian/<package>-doc. #INSTALLDOC# $(MAKE) DESTDIR=$(CURDIR)/debian/tmp install-doc $(MAKE) DESTDIR=$(CURDIR)/debian/tmp install-common
  
  The binary-arch target has to be tweaked even a bit more:
  # Add here commands to install the arch part of the package into # debian/tmp. $(MAKE) DESTDIR=$(CURDIR)/debian/tmp install-bin-$(DEB_HOST_ARCH_CPU)
Other debianization
Of course as with any packaging, Copyright, README, Changelog etc. must be modified. And proper {pre,post}{install,rm} scripts must be created.
As Debian/Ubuntu doesn't distinguish between amd64 (x86_64 in RPM/Intel parlance) architecture systems with Intel and AMD processors, and because Magma does, I have the postinst script of the bin-amd64 package install both binaries and try to gues the machine's CPU brand during install. The alternative would be to create different packages and let the sysadmin decide.
Generating the packages
To create the i386 and architecture independent files, from magma-2.15.10, call:
fakeroot dpkg-buildpackage -b -ai386
Repeat for amd64.
Checking the packages for errors
The resulting packages can be checked for errors with lintian:
lintian ../magma*.deb W: magma-doc: zero-byte-file-in-doc-directory usr/share/doc/magma/html/html/rel/images.out W: magma-common: package-contains-upstream-install-documentation usr/share/doc/magma-common/INSTALL.txt.gz W: magma-common: extra-license-file usr/share/doc/magma/ThirdParty/ATLAS_LICENSE.txt W: magma-common: extra-license-file usr/share/doc/magma/ThirdParty/ECM_LICENSE.txt.gz W: magma-common: extra-license-file usr/share/doc/magma/ThirdParty/GMP_LICENSE.txt.gz <snip>
I found a few textfiles with execure permissions, and set them properly in the unpacked source. As long as no errors come up, I'm fine for now.
Checking the contents of the package

dpkg --contents ../magma-bin-i386_2.15.10_i386.deb dpkg --info ../magma-bin-i386_2.15.10_i386.deb mkdir /tmp/magma-bin-i386-control dpkg --control ../magma-bin-i386_2.15.10_i386.deb /tmp/magma-bin-i386-control
Installing the package

dpkg -i ../magma-bin-i386_2.15.10_i386.deb ../magma-common_2.15.10_all.deb ../magma-doc_2.15.10_all.deb

	Note
	The file `magmapassfile`, which determines whether magma is allowed to run on a particular machine, is not packaged, and shouldn't be. When starting with my example config file in `/etc/magma/`, magma looks for it in `/etc/magma/magmapassfile` and in `~/magmapassfile`.

Warning

ToDo (in no particular order):

Perhaps use update-alternatives for managing all options.
See if we can create a non-native package and use the combined downloaded files as a tar.orig of sorts.
Fix a few missed dependencies.
Create/generate manpages.
Use debconf to determine the architecture and only fall back on autodetection.
Install the specialized i386 binaries instead of the generic one.
See if we can build all packages at once instead of in an amd64 and then an i386 run.
Build the package with PBuilder in a chroot jail.
Test installation on Debian Etch and Lenny, and on Ubuntu Hardy, Intrepid and Jaunty.

^[30] This dirname is part of the requirements for packaging.


Fetching the software		DebPackaging binary-only tarbundles (Tivoli)