View source for Dh-make-mahara

'''dh-make-mahara''' (DHMM) will build Debian packaging for a given Mahara checkout, and can be run again in a directory that has already been converted in order to install fixes to the debian packaging.

It installs all of the normal files, such as <code>rules</code>, <code>control</code>, <code>postinst</code> etc. Some of these files it expects to be the sole author of, and some of them are left to the maintainer to deal with. It also installs a couple of files that are not normally in debian packaging, but that it requires, such as <code>debian/apache-templater.sh</code>.

When a fix to dh-make-mahara needs to be applied to an existing debianised Mahara, simply run dh-make-mahara on it again. It will show you the differences and ask if you really want to upgrade.

== Getting dh-make-mahara ==

=== Source Control ===

dh-make-mahara is in [http://git.catalyst.net.nz/gw?p=dh-make-mahara.git;a=summary gitpublic]:

<pre>git clone git://git.catalyst.net.nz/dh-make-mahara.git</pre>

== Usage ==

Let's assume that you have a Mahara checkout for a client at <code>$HOME/work/mahara-client</code>.

=== Performing the Initial Debianisation ===

<pre>nigel@freud:~$ dh-make-mahara.pl --basepath $HOME/work/mahara-client
What name should be given to this Mahara installation? This should be a
short name, all in lower-case, that will be used for the debian package
name and filesystem paths.
Mahara Installation Name: client

Who is the maintainer for the installation?
Maintainer Name [Nigel McNie]: [Nigel McNie]

What is the e-mail address of the maintainer?
Maintainer E-mail [nigel@catalyst.net.nz]: [nigel@catalyst.net.nz]

Now at dhmm 0.2.4
nigel@freud:~$ </pre>

Some questions are asked, in order to set up the initial packaging.

You have to give a name for the installation, which will be used in the debian package name. You can specify this on the command line with the <code>--name</code> argument if you wish.

The maintainer question defaults will be automatically guessed from your environment - in particular, DEBFULLNAME and DEBEMAIL, if you have them set.

If you like, you can specify the <code>--assume-defaults</code> argument to dh-make-mahara, which will result in it asking you no questions:

<pre>nigel@freud:~$ dh-make-mahara.pl --basepath $HOME/work/mahara-client --name client --assume-defaults
Now at dhmm 0.2.4
nigel@freud:~$ </pre>

==== Version Numbers ====

The package will be given a version number of the Mahara upstream version as obtained from htdocs/lib/version.php. Every time the package is built, if the upstream version is incorrect then it will be corrected for you, and you will be given the chance to commit the change. You can run the sanity checker script manually if you like, to ensure you have got it correct:

<pre>nigel@freud:~/work/mahara-client$ sh debian/sanity-check.sh
Debian changelog version is not equal to the upstream version, fixing this for you...
Done. Now git commit the result.
nigel@freud:~/work/mahara-client$</pre>

Then you can commit the new changelog and run 'make' as normal.

=== Building and Installing the Package ===

You're largely done with dh-make-mahara at this point. Now you just need to customise the apache configuration as you see fit, then build and install the package.

To build the package for the first time, change to the <code>$HOME/work/mahara-client</code> directory. Before building the package, have a look in <code>debian/apache.conf</code>. This is the template file from which your apache configuration will be made. If you add more __MARKER__ placeholders in this file, a debconf question will be asked for you to fill in each one when the package is installed.

Once you are done playing with the apache config, run <code>make</code>:

<pre>nigel@freud:~/work/mahara-client$ make
sh debian/apache-templater.sh
dpkg-buildpackage -rfakeroot -us -uc -b -tc
dpkg-buildpackage: source package mahara-site-client
dpkg-buildpackage: source version 1.0.0-1
dpkg-buildpackage: source changed by Nigel McNie <nigel@catalyst.net.nz>
dpkg-buildpackage: host architecture i386
 fakeroot debian/rules clean
make[1]: Entering directory `/home/nigel/work/mahara-client'
dh_testdir
dh_testroot
dh_clean
make[1]: Leaving directory `/home/nigel/work/mahara-client'
 debian/rules build
make[1]: Entering directory `/home/nigel/work/mahara-client'
make[1]: Nothing to be done for `build'.
make[1]: Leaving directory `/home/nigel/work/mahara-client'
 fakeroot debian/rules binary
make[1]: Entering directory `/home/nigel/work/mahara-client'
dh_testdir
dh_testroot
dh_installchangelogs
dh_installdocs
dh_installdebconf
dh_installcron
dh_installlogrotate
dh_compress
dh_fixperms
dh_installdeb
dh_installdirs
dh_install
dh_gencontrol
dh_md5sums
dh_builddeb
dpkg-deb: building package `mahara-site-client' in `../mahara-site-client_1.0.0-1_all.deb'.
make[1]: Leaving directory `/home/nigel/work/mahara-client'
 dpkg-genchanges -b >../mahara-site-client_1.0.0-1_i386.changes
dpkg-genchanges: binary-only upload - not including any source code
 fakeroot debian/rules clean
make[1]: Entering directory `/home/nigel/work/mahara-client'
dh_testdir
dh_testroot
dh_clean
make[1]: Leaving directory `/home/nigel/work/mahara-client'
dpkg-buildpackage: binary only upload (no source included)
nigel@freud:~/work/mahara-client$ </pre>

The package will be in the parent directory. You can run <code>lintian</code> on it if you want - it will most likely moan about some included license files, and that the first release of a package should close an ITP bug, which is a debianism that can be ignored.

Copy it to wherever you're installing the package and install it. You will be asked debconf questions for the database details, and for any markers that are in your apache config - likely at least server name.

=== Upgrading the Package ===

Now let's assume you have new changes you wish to roll out. You need to increment the version of the debian package, and build the package again:

<pre>nigel@freud:~/work/mahara-client$ dch -i
[edit the changelog]
nigel@freud:~/work/mahara-client$ make
[snip]</pre>

==== What happens when I want to change the apache configuration? ====

Changing the apache configuration involves rebuilding the package, just as with any other upgrade. If you add a new __MARKER__ in your apache config, when you install the package you will be asked to fill in the value for that question, as you would expect.

If you remove a marker, the question template will still remain in <code>debian/templates</code>, as will the db_input line in <code>debian/config</code>. If you're really sure, you can edit those files and remove them, but if you're not sure then at least if you put the marker back later, debconf on any server you upgrade the package on will still know the value for it.

==== How do I make the questions more user friendly? ====

Simply run the apache templater manually, then edit debian/templates to change the wording of the questions:

<pre>nigel@freud:~/work/mahara-client$ sh debian/apache-templater.sh
nigel@freud:~/work/mahara-client$ vim debian/templates</pre>

==== What happens if there is a bug in a part of the debian packaging that DHMM is responsible for? ====

You need to fix, or get someone else to fix, the bug in dh-make-mahara itself. Then run the new version against your installation. dh-make-mahara will show you a diff of changes between the new and old packaging, and if you accept, it will apply them.

Here is an example where there was a bug in the postinst. Running the fixed version of dh-make-mahara against the existing codebase imported the fix:

<pre>nigel@freud:~$ dh-make-mahara.pl --basepath $HOME/work/mahara-client
diff -u /home/nigel/work/mahara-client/debian-pre-dhmm/postinst /home/nigel/work/mahara-client/debian/postinst
--- /home/nigel/work/mahara-client/debian-pre-dhmm/postinst	2008-02-08 17:26:52.000000000 +1300
+++ /home/nigel/work/mahara-client/debian/postinst	2008-02-08 17:26:52.000000000 +1300
@@ -73,13 +73,13 @@
                 ENABLE_SITE="true"
             fi
 
-            cp /var/lib/sitedata/mahara-site-client/apache.conf.working /etc/apache2/sites-available/mahara-site-client.conf
+            mv /var/lib/sitedata/mahara-site-client/apache.conf.working /etc/apache2/sites-available/mahara-site-client.conf
 
             if [ "$ENABLE_SITE" != "" ]; then
                 a2ensite mahara-site-client.conf
             fi
         elif [ -d /etc/apache/conf.d ]; then
-            cp /var/lib/sitedata/mahara-site-client/apache.conf.working /etc/apache/conf.d/mahara-site-client.conf
+            mv /var/lib/sitedata/mahara-site-client/apache.conf.working /etc/apache/conf.d/mahara-site-client.conf
         else
             echo "[strange] apache or apache2 config directories not detected. I left your"
             echo "config file in /var/lib/sitedata/mahara-site-client"
Does this diff look ok?: y
Upgraded to dhmm 0.0.2
nigel@freud:~$ </pre>