Translation(s): English


Icedove is the Thunderbird email client rebranded by Debian. This site describes Icedove development specific things.

Icedove Package Development

Preparation and Requirements

The sources of Icedove Debian package are within a git repo on git.debian.org. They're maintained using git-buildpackage. If you want to help or take a look inside you need to install some tools:

additional packages

git gitk git-buildpackage git-pbuilder devscripts git-email

Icedove is currently not yet converted to debhelper, the Icedove build is still done with CDBS. To be able to build a personal Icedove package you need to setup a build environment, the maintainers doing there testing and final builds with gbp-buildpackage and git-pbuilder.

Cloning and Updating the Repository

Icedove is one of the bigger packages with a lot of source code which have to be prepared to be buildable on every platform. Mostly with every major update on the Mozilla Thunderbird package the build for almost all platforms breaks. Any help to fix any build problems are much appreciated! Also any help to fight lintian issues! If you want to help please don't hesitate to write a mail to pkg-mozilla-maintainers@lists.alioth.debian.org.

If you've found a fix for a bug you can build a patch that is then applicable with the git am command. Use the following work flow to create such patches.

Be sure you have checked out the current Git tree of Icedove, if not done yet, just use git-buildpackage with the gbp clone command instead of manual git commands. This will make sure the necessary branch tracking is set up.

   1 $ gbp clone git://anonscm.debian.org/pkg-mozilla/icedove.git

If you already have a local clone of the repo just update your clone. Also, use the gbp pull command from git-buildpackage. This ensures that all the needed branches from remote get updated.

   1 $ gbp pull
   2 gbp:info: Branch 'master' is already up to date.
   3 gbp:info: Updating 'upstream'
   4 gbp:info: Branch 'pristine-tar' is already up to date.

Patching the upstream sources

In order to change the current behavior of Icedove you have to make changes to the original (upstream) sources. To make your changes later available for the package maintainers you have to respect some few things. If you don't understand the workflow you can write your questions to the package manitainers, and of course, improve then this article. :) Icedove uses the Debian Source 3.0 (quilt) format. In order to patch the upstream source you need to create a patch in debian/patches/. This is simplest when creating a patch queue. git-buildpackage will do the most of the needed steps. To start verify that your local repo is clean (check with git status) and you are on the 'master' branch. Let's start.

1. Import the patch queue

That imports the debian patch queue from the directory debian/patches on top of the source and switches to the branch patch-queue/master.

   1 user@host:~/gitprojects/icedove [master] $ gbp pq import
   2 gbp:info: Trying to apply patches at 'aa5491b2e4141b0ec1f829c1d6c003650a0000c3'
   3 Switched to branch 'patch-queue/master'
   4 ...
   5 gbp:info: Patches listed in 'debian/patches/series' imported on 'patch-queue/master'
   6 user@host:~/gitprojects/icedove [patch-queue/master] $

2. Modify the source as you wanted, for example improve something on the sources of Icedove/Thunderbird

For example change the file debian/icedove-branding/thunderbird-branding.js to point the News website to http://mozilla.debian.new/.

   1 user@host:~/gitprojects/icedove [patch-queue/master] $ vi debian/icedove-branding/thunderbird-branding.js
   2  ... # make your changes
   3 user@host:~/gitprojects/icedove [patch-queue/master] $ git diff
   4 diff --git a/debian/icedove-branding/thunderbird-branding.js b/debian/icedove-branding/thunderbird-branding.js
   5 index 7caf6b6..39256ad 100644
   6 --- a/debian/icedove-branding/thunderbird-branding.js
   7 +++ b/debian/icedove-branding/thunderbird-branding.js
   8 @@ -8,6 +8,6 @@ pref("mailnews.start_page.welcome_url", "about:");
   9  
  10  // start page override to load after an update
  11  //pref("mailnews.start_page.override_url", "chrome://messenger/content/start.xhtml");
  12 -pref("mailnews.start_page.override_url", "about:");
  13 +pref("mailnews.start_page.override_url", "http://mozilla.debian.new/");
  14  
  15  pref("app.vendorURL", "http://www.mozillamessaging.com/%LOCALE%/thunderbird/");

3. Commit your changes with the '-s' option, please fill in a useful commit message!

That should be easy. But don't forget to add a Gbp-Pq-Topic info, that's needed to classify the patch and make life easier if the patch queue must be reworked in case of working on a new major release. In most of the cases some patches doesn't apply then anymore and can be dropped or have to reworked, the Gbp-PqTopic helps then to decide if the patch will be needed any longer. Proper Gbp-Topic's will you find in form of the directory names in debian/patches/.

   1 user@host:~/gitprojects/icedove [patch-queue/master] $ tree -d debian/patches/
   2 debian/patches/
   3 ├── debian-hacks
   4 ├── fixes
   5 ├── icedove
   6 ├── iceowl
   7 ├── porting
   8 ├── prefs
   9 └── system-libs

Use one of these names to mark your patch in the Gbp-Pq-Topic, just add a line into your commit message with the correct topic. See the next shell output to know how.

   1 user@host:~/gitprojects/icedove [patch-queue/master] $ git commit -s debian/icedove-branding/thunderbird-branding.js
   2 ...
   3   1 thunderbird-branding.js: change the mailnews URI to mozilla.net
   4   2 
   5   3 Gbp-Pq-Topic: icedove   <--- adding a patch queue topic
   6   4 
   7   5 Signed-off-by: Peter Petersen <p.petersen@mailprovider.com>
   8   6
   9   7 # Please enter the commit message for your changes. Lines starting
  10   8 # with '#' will be ignored, and an empty message aborts the commit.
  11   9 # Explicit paths specified without -i nor -o; assuming --only paths...
  12  10 # On branch patch-queue/master
  13  11 # Changes to be committed:
  14  12 #   (use "git reset HEAD <file>..." to unstage)
  15  13 #
  16  14 #   modified:   debian/icedove-branding/thunderbird-branding.js
  17 

4. Export the patch queue

To do this just use gbp pq export from git-buildpackage. That exports the debian specific patches into a quilt patch series and change back to the master branch.

   1 user@host:~/gitprojects/icedove [patch-queue/master] $ gbp pq export
   2 gbp:info: On 'patch-queue/master', switching to 'master'
   3 Switched to branch 'master'
   4 gbp:info: Regenerating patch queue in 'debian/patches/'.
   5 # On branch master
   6 # Changes not staged for commit:
   7 #   (use "git add <file>..." to update what will be committed)
   8 #   (use "git checkout -- <file>..." to discard changes in working directory)
   9 #
  10 #       modified:   debian/patches/debian-hacks/Add-another-preferences-directory-for-applications-p.patch
  11 ... # you will see more of modified files, this is a know error in git-buildpackage !!! Read further!
  12 #       modified:   debian/patches/system-libs/Allow-to-build-against-system-libffi.patch
  13 #
  14 # Untracked files:
  15 #   (use "git add <file>..." to include in what will be committed)
  16 #
  17 #       debian/patches/thunderbird-branding.js-change-the-mailnews-URI-to-m.patch
  18 no changes added to commit (use "git add" and/or "git commit -a")

After this git-buildpackage has put the new generated patches into the directory debian/patches/.

5. Commit the new patch to the Icedove packaging repository

The next step is now to commit this patch (and only this patch!) but also the file series (debian/patches/series) to git.

If you work with Wheezy

Please please ignore the other modified patches, don't commit thees changes! The other noise comes from a known issue of git-buildpackage and is fixed in Testing/Jessie. You can install git-buildpackage from Testing to fix this problem.

   1 user@host:~/gitprojects/icedove [patch-queue/master] $ git add debian/patches/thunderbird-branding.js-change-the-mailnews-URI-to-m.patch
   2 user@host:~/gitprojects/icedove [patch-queue/master] $ git commit debian/patches/thunderbird-branding.js-change-the-mailnews-URI-to-m.patch debian/patches/series
   3 ...
   4   1 changing the News URI from 'about' to 'http://mozilla.debian.net'
   5   2 
   6   3 Signed-off-by: Peter Petersen <p.petersen@mailprovider.com>
   7   4 
   8   5 # Please enter the commit message for your changes. Lines starting
   9   6 # with '#' will be ignored, and an empty message aborts the commit.
  10   7 # On branch master
  11   8 # Your branch is ahead of 'origin/master' by 1 commit.
  12   9 #
  13  10 # Changes to be committed:
  14  11 #   (use "git reset HEAD^1 <file>..." to unstage)
  15  12 #
  16  13 #   new file:   debian/patches/thunderbird-branding.js-change-the-mailnews-URI-to-m.patch
  17  14 #
  18  15 # Changes not staged for commit:
  19  16 #   (use "git add <file>..." to update what will be committed)
  20  17 #   (use "git checkout -- <file>..." to discard changes in working directory)
  21  18 #
  22  19 #   modified:   debian/patches/debian-hacks/Add-another-preferences-directory-for-applications-p.patch
  23  20 #    .... more of modified files
  24 

Now you can clean up all of this modified marked files because we don't want them.

   1 user@host:~/gitprojects/icedove [master] $ git co -f
   2 Your branch is ahead of 'origin/master' by 1 commit.
   3 user@host:~/gitprojects/icedove [master] $ git st
   4 # On branch master
   5 # Your branch is ahead of 'origin/master' by 1 commit.
   6 #
   7 nothing to commit (working directory clean)

6. Extract your last changes and mail them to the maintainers

Just use git-email to provide your patch(es) to pkg-mozilla-maintainers@lists.alioth.debian.org or append your patch to an existing bug.

   1 user@host:~/gitprojects/icedove [master] $ git format-patch HEAD~1
   2 0001-changing-the-News-URI-from-about-to-http-mozilla.deb.patch


Building own Packages

After some modifing the build environment or the sources itself you have to build your own package of Icedove to check if the changes you have made are just fine. To do this sure you have already set up, or have updated your build environment.

To build your own version is very easy with git-buildpackage. It will checks most of the needed things to let you successfull build your own package version. After you have made some changes in the way decribed above your next step will be to update the debian/changelog file so git-buildpackage can hand over a correct version the building tool (pbuilder, cowbuilder, ...). Please use the command git-dch to do this. This will create a correct formated new entry to debian/changelog.

   1 git-dch -a -S    # -a means 'automatic' and -S means 'Snapshot'
   2 

After this you have to commit the changed debian/changelog file because git-buildpackage is normaly unhappy with uncommitted files.

   1 git commit debian/changelog -m "made my own test version"

Next you can start you build.

   1 git-buildpackage --git-pbuilder --git-pristine-tar

That's it, after some time and two coffees later you will hopefully se your own created Icedove package.

Building own Packages other the HEAD

You can rebuild every tagged Debian version of Icedove. To do this you have to checkout the tagged version into a new local branch, for example if you want to rebuild or modify the tag debian/3.0.11-1+squeeze15 let git this checkout in the local branch mine-3.0.11-1+squeeze15:

   1 git checkout -b mine-3.0.11-1+squeeze15 debian/3.0.11-1+squeeze15

If you want to change something like the source itself do it like described above. If you just want to modify something like compiler options you just have to commit your changes you made into the git tree. For example:

   1 vi debian/rules    # modify some variables
   2 git commit debian/rules

If you are ready with your changes don't forget to change the file debian/changelog too! Remember, git-dch -a -S will do this for you. If you want to change the version in the changelog file please consider that the version must be greater then the previous version in the changelog file, normaly there is nothing to be done by you. Finaly you have to commit your changes to the changelog file like described above because git-buildpackage read out the version that the deb package will become.

The call of git-buildpackage differs a little bit because you are not on a Debian branch anymore. The old version 3.0.11-squeeze15 in this example is used in Squeeze stable, so at minimum you have to tell it git-buildpackage. Also the plattform you are using, for example amd64. To build your changed version the call of git-buildpackage have to look like:

   1 git-buildpackage --git-pbuilder --git-pristine-tar --git-ignore-branch  --git-arch=amd64 --git-dist=squeeze


CategoryIcedove