Building proper Ubuntu packages through the example of wxMaxima

Preface

This document will guide the reader through the process of building proper Ubuntu packages. It shows the basis of package building in some steps through the example of maxima computer algebra system and it's interface, wxMaxima. More detailed guides can be found in the related articles of Ubuntu Wiki. We do not give a full, complete description, because of the complexity of the task, but we will give a good base to start.

There are many solutions to build packages, however, this one provides more possibilities and leads to a complete result. Packages built with devscripts are fully configurable, but other easier solutions like checkinstall and epm do not result in proper packages. This solution requires more work and reading, but think about it as an investment. We will see how proper, official packages are built. There are some cases where easier methods are suitable, since we do not need to build proper packages all the time. If we plan to publish the packages, they have to be of good quality.

Devscripts is a script collection made by Debian developers, which helps building and checking packages. Checking is provided by Lintian, which is also a Debian product, so if it does not find any mistakes, it is a good sign.

Packaging of wxMaxima

Preparation

• For building packages we will need a GPG-keypair to sing them. A how-to about GPG can be found here.
• This how-to was tested on Ubuntu 9.10. And before we start, let's run
  apt-get update && apt-get upgrade
  After this, we need some packages
  sudo apt-get install build-essential debhelper devscripts git-core gnupg-agent autotools-dev
• If we want to build packages locally, not in PPA, install wxmaxima's and maxima's build-time dependencies too.
  sudo apt-get install libwxgtk2.8-dev sbcl texinfo libgmp3-dev libreadline5-dev automake-1.9 libncurses5-dev autoconf2.13 texlive-latex-recommended sharutils libxmu-dev libxaw7-dev
• It is worth to set up some environment variables. Warning: these three value belong together, they were given to the key generator. These values are going into the debian/changelog. The most comfortable way is to put these commands into the ~/.bashrc, but we can execute them in the command line as well. These are my values, change them!
  The GPG-key to sign the package:
  export GPGKEY=1D4320FD
  Email address belonging to the key:
  export DEBEMAIL="somogyi.andras@gmail.com"
  Full name belonging to the key:
  export DEBFULLNAME="András Somogyi"
  If we put them into the ~/.bashrc, we need to run
  source ~/.bashrc
  to apply the changes.
  Note:A mini how-to about backup and import keys can be found here.

---

Obtaining the source

• Download the source of wxmaxima. For example:
  wget http://downloads.sourceforge.net/project/wxmaxima/wxMaxima/0.8.4/wxMaxima-0.8.4.tar.gz
• Extract the tar.gz,
  tar -xf wxMaxima-0.8.4.tar.gz
  then rename the directory to lowercase.
  mv wxMaxima-0.8.4 wxmaxima-0.8.4

---

Preparing the orig.tar.gz

• Rename the original tar to Debian compatible.
  mv wxMaxima-0.8.4.tar.gz wxmaxima_0.8.4.orig.tar.gz

---

Obtaining Debian files

• Download wxmaxima sources from the Debian git repository to an other directory. The last parameter of the command will be the name of the directory.
  git clone git://git.debian.org/git/debian-science/packages/wxmaxima.git wxmaxima_git
  
• All we need is the debian/ directory, so copy it to the source directory that we got from the tar.gz.
  mv wxmaxima_git/debian/ wxmaxima-0.8.4/

---

New changelog entry

• Go to the wxmaxima-0.8.4 directory
  cd wxmaxima-0.8.4
  and run
  dch -i
  This will make a new changelog entry (with the default editor) in the debian/changelog file.
  Important! The name of directory and the orig.tar.gz is debianconform and they have to correspond to the version given in changelog. If the changelog entry is 0.8.4, then the version in the name of the directory and the orig.tar.gz have to be the same. In this case, the header of the changelog entry will be
  wxmaxima (0.8.4) karmic; urgency=low
• Edit the files in the debian/ directory. For example, the dependencies in the control file. Dependencies can be separate with a comma, and a space.

---

Building the source package

• If we don't want to upload the package to the PPA, then skip to the "Using Ubuntu PPA" section and read about the source package.
• There is no need to make a source package for local building, skip to the next step.

---

Building the binary package

• Stay in the wxmaxima-0.8.4 directory, and run
  debuild
  
• Note 1: This will build the binary package. Build time dependencies given in the debian/control file have to be installed, but if something is missing, read the debuild output.
• Note 2: However, Ubuntu Wiki advises pbuilder for building binary packages, but in this case we will not need a chrooted environment.
• Note 3: The well-known ./configure and make programs are executed in this step, so lay back for some minutes.

Packaging Maxima

Obtaining the source code and the debian directory. Preparation.

• Make a directory to work in and enter it.
• Obtain the source of maxima.
  wget http://downloads.sourceforge.net/project/maxima/Maxima-source/5.20.1-source/maxima-5.20.1.tar.gz
• Extract it.
  tar -xf maxima-5.20.1.tar.gz

---

Preparing the orig.tar.gz

• Rename the original tar to debian conform.
  mv maxima-5.20.1.tar.gz maxima_5.20.1.orig.tar.gz
  

---

Obtain the Ubuntu source package.

• Run the following command:
  apt-get source maxima
  
• This will make a directory with the source of the package. Copy the debian directory to the source directory that we got from the tar.gz.
  mv maxima-5.17.1/debian/ maxima-5.20.1/

---

Necessary changes

• Go to the source directory,
  cd maxima-5.20.1
  then run
  dch -i
  and make a proper entry in the changelog of the package.
  Warning! Pay attention to version numbers! Version numbers in changelog, in the name of orig.tar.gz and in the name of the source directory have to match!
• Change the rules file in the debian directory. It has to be changed to use sbcl or any other lisp implementations. Basically, we have to change the parameters of configure to use the chosen lisp implementation. For example, change the
  GCL_ANSI=t ./configure --enable-gcl $$(gcl -batch -eval '#-native-reloc(princ "--enable-gcl-alt-link")(bye)') \ line to
  SBCL=t ./configure --enable-sbcl \
  (Modify every instance of GCL_ANSI too, or keep them unaltered. Of course, it's much prettier if modified.)
• Naturally, build time dependencies are also changing, so modify the control file in the debian directory. In this case, gcl has to be changed to sbcl.
• We also need to change gcl in the name of directories in the debian/rules file, which are made during building. Seek for every instance of gcl and change as required.
• Since the release of maxima 5.17.1, the interface of run_testsuite(); has changed, so we have to modify this too.
  Search for it in the rules file, and correct it: run_testsuite(display_all = false); (true is also good, if we want to see the verbose output of the tests.)
• If we use sbcl, comment out or delete the readline-related line, otherwise the build process will fail. This line will work only with gcl.

---

Building the source package

• If we don't want to upload the package to PPA, skip to the "Using Ubuntu PPA" section, and read for information about the source package.
• There is no need to make source package for local building, skip to the next step.

---

Building the binary package

• Stay in the maxima-5.20.1 directory, and run
  debuild
  If everything went fine, the package will be built.

• Warning! Packages patched with quilt are not supported.
• Sbcl is available only on i386 and amd64. Lpia is not supported.
• After creation of a new PPA it is worth to waiting some time. Generating the key of PPA takes some time, so if we upload a source package before the key generation is ended, the signing of the binary package will fail. The package will still work, but the users will not be able to validate it.

Preparation

• Although we only need to upload a source package it is also worth to perform a test build. PPA is queueing up jobs, so a lot of time can be lost if the source package is rejected, or accepted but fails to build.
• Please read the documentation carefully!

---

Versions

• We have to extend the version number with the ~ppaN suffix, where N is a serial number. We need that, because the package in PPA has to make the current Ubuntu package obsolete, but a newer official build has to make our (non-official) build obsolete.
• An example...
  Let's suppose, in the Ubuntu repository wxmaxima-0.8.2-1 is the newest package. If we want to build a newer one, then give the wxmaxima-0.8.2-2~ppa1 version. This way, if a new wxmaxima-0.8.2-2 is coming to the official repository, it will supersede our non-official package.

---

Building the source package

• Since we will not be uploading a modification of an existing version but a new version, let's run
  debuild -S -sa
  in the source directory.
  This will make all the files we need to upload.

---

Uploading

• Go to the directory where the source directory and the files of the source package are located.
• We use dput to upload. We can read the exact command on the page of our PPA, but let's see some explanation.
  dput ppa:andras-somogyi/as <source.changes>
• In the command above, andras-somogyi is my user name and as is the name of the PPA. Replace <source.changes> with the .changes file.
• We will receive an email about the acceptance or rejection of our source package and the outcome of the building process.

---

Using PPA, from the user's viewpoint

• The repository can be added with a simple command.
  sudo add-apt-repository ppa:andras-somogyi/as
  This PPA is just an example, modify the command as you like.

---