Dear all, I have wrote the attached howto, which I send to this list for comments. Its source is in docbook, so it is intended to be a html or pdf document in its final version.
The reason I wrote this is that I will recontact the people from bio-linux, and I would like to provide them with guidelines suggesting how they could contribute their packages to debian-med, and how we could build some together. In fact, I tried to be a bit more general, so that it is publishable and reusable. I welcome any comment. I did my best, but I am a beginner, and this preliminary howto might promote bad practices as well... Have a nice day, -- Charles
Packaging software for debian-med. _________________________________________________________________ Table of Contents [1]Before starting to package. [2]Preliminary binary package. [3]Modifications to the upstream sources. [4]Building clean source and binary packages. [5]Reaching the high quality standards of Debian. [6]The debiandirectory. [7]The manpage(s). [8]Regstering the documentation with doc-base. [9]Menu entries for graphical applications. [10]Last checks before releasing the package [11]Sharing your work [12]Uploading on mentors.debian.org [13]Uploading on the subversion repository of Alioth Warning This is a sort of verbose cheat card. It is intended to be read by someone who has already read the [14]new maintainer guide. Before starting to package. Check the licence. Does it meet the [15]DFSG? If not it may be still distributable, but in the non-free section. This section is not autobuilded, which means that each non-free package will add a work overhead on you and/or you co-maintainers. You may want to package something else first. Download the package and build it. The work to be done may be much bigger if you have first to deal with compilation issues. Once again, maybe you will want to package something else first. Avoid duplicate work. Double-check that the software is not packaged yet for Debian, officially or not, nor for derivatives such as Ubuntu. Once you are sure that nobody is working on it, inform the world about your intention to prepare a package. [16]File an ITP bug (Intend To Package). One of the simplest ways to do so is to type reportbug wnpp and follow the instructions. Try to be as complete as possible. The short and long descriptions can be re-used in the control file, the upstream author name and the license are needded for the copyright file, so it is worth taking the time to write a good ITP. Preliminary binary package. In order to find potential problems as soon as possible, start by preparing a preliminary package which can be built using debian/rules. After download, if necessary, rename the source directory packagename-version, and re-package the sources under the name packagename_version.orig.tar.gz. Note that the directory needs a dash and the tar archive an underscore. If you make mistakes at this step, it is likely that a native package will be build instead of a non-native one. Use the debian helper tools to create a debiandirectory. dh_make -e [EMAIL PROTECTED] -f ../packagename_version.orig.tar.gz will populate a debian directory and write a tentative rules makefile. You can skip the -e parameter if you have set the DEBEMAIL environnement variable. If your package has a GPL, LGPL, BSD or Artistic licence, you can use the -c option of dh_make, which will create a more detailed template for the copyright file. Is it working out of the box? Try to build the package with fakeroot debian/rules binary. Inspect its contents with dpkg -c ../yourpackage_version_arch.deb. If you encounter problems at this stage, it is normal. It is likely that you have to edit the debian/rules makefile in order to fix the packaging. It is then time to clean the debian/rules makefile. There are many lines which can be removed, such as the comments. Keeping the this file as simple as possible makes it easier to maintain the package as a team. If you do this for the first time, it is also a good opportunity to read the mapages of the many debhelper scripts, (the ones starting with 'dh_'). Modifications to the upstream sources. To be redistributable, your modifications need a licence. Do not forget to mention it in all the files you will include to the source package. You can use the copyright file to indicate that your patches, packaging work and new files are freely redistributable. Be careful if you incorporate parts of the existing documentation in new files, for instance in a manpage: the licence you chose must be compatible. It is otfen wise to choose the same licence as the software itself. To make modifications of the original source as obvious as possible, you can use the [17]dpatch system. Note that if you use dpatch, you will have to add it in the buid dependancies of your package. The manpage of dpatch explains how it works, but here is a few commands for a quick start. The patches are stored in the debian/patchesdirectory. It contains a special file, 00list which lists the patches to apply. The following instruction generates a patch and formats it for dpatch: diff -u source-tree-original/the-file source-tree/the-file | dpatch patch-template -p "number_short_desctiption" "What the patch is doing" > path/to/debian/patches/number_short_desctiption.dpatch. Try to apply / deapply your patches with the following commands: dpatch apply-all and dpatch deapply-all (to be run from the sources directory, not the debian one). Try them on cleaned sources as well. If it works without errors, you can modify the debian/rules makefile as indicated in the dpatch manpage. Patches which you think are of general interest should be submitted to the upstream author(s). Not only this shares your enhancements, but it also reduces the complexity of the package when they are accepted. Building clean source and binary packages. Having debian/rules binary working does not guarantee that you will manage to build the source and binary packages using the command dpkg-buildpackage. In particular, the source is always cleaned before building the binaries, so if the clean section of the rules file is buggy, the creation of the package will fail. I recommend to run two times fakeroot debian/rules clean before trying dpkg-buildpackage. The second run is to ensure that the cleaning does not fail when the files to clean are not present. For instance, rm src/*.o will not work in absence of .o files, and could be replaced by find src/ -name '*.o' -exec rm {} \;. Now you can run dpkg-buildpackage -rfakeroot. If you use dpkg-buildpackage repeatitdly for debugging, you can use the -us and -uc options, which will skip the gpg signing of the sources and the changes file. Reaching the high quality standards of Debian. Polishing a debian package is a task which takes time, but which is very straightforward. For this reason, I recommand to do this at the end. Therefore, if there were a major problem which prevents you to acheive the packaging of a software, you would not have wasted time on documenting it. The debiandirectory. The debian directory comes with a lot of templates which will have to be edited or deleted. Most of them are described in the [18]new maintainer guide. Using the information you gathered for your ITP bug, filling the copyright and the control files should be easy. The manpage(s). The Debian Policy requires all executable binaries to be documented by a manpage. As they are not frequently included with bioinformatic softwares, it means that we will have to write them. If you do not know the nroff syntax used to write the manpages, no problem. You can write them in docbook instead and convert them at build time. Docbook looks like html, but has been designed to be convertible in many other formats, including nroff. The debian directory created by dh_make contains an example for two docbook formats, sgml and xml. Good XML editors are for instance [19]jEdit or emacs in the nXML or psgml modes. The manpage template contains instructions on what to put in the makefile to build it. It also reminds that the source package will have to depend on xsltproc and docbook-xsl. Dynamically created nroff manpage need to be cleaned from the source when the source package is created. Adding their name after dh_clean in the rules makefile does this. Having written a manpage, it can be useful to submit it to the upstream author. It is a good opportunity to inform him by the way that Debian will distribute his software. Regstering the documentation with doc-base. The documentation of the software you package can be indexed by the doc-base system. There is a template for doing this in the debian directory. Menu entries for graphical applications. In Debian, the application menu is handled via a specific system. To register the application, you have to edit the package.menufile according to the template. To help the user to find the application, you can provide an icon, ideally coming from the original software sources. It has to be placed in /usr/share/pixmaps/ directory, which you will have to create through package.dirs and should comply to the [20]menu policy. The GNOME and KDE desktop environments provide another menu system. Registerind your application with them will integrate your application better, especially in distribution based on Debian which do not use its menu system, such as Ubuntu. A file similar in its principles but different in its syntax, package.desktop, has to be placed in /usr/share/applications/. You can find more informations on the [21]Ubuntu website. Last checks before releasing the package Build the package again. Inspect its contents (dpkg -c). Check the in the .diff.gz that it does not contain superfluous files (zgrep +++ yourpackage.diff.gz). Review your package with lintian and linda. Build it again in a naive environnement such as a chroot or a pbuilder. Install the package, and use the program. If your package passes all these tests without error, it may be ready for distribution. Sharing your work Uploading on mentors.debian.org [22]Mentors.debian.net is a useful service for sharing your work before it is integrated in the debian archives and autobuilded. Mentors is a source-only repository, so the users who will want to install the package will have to build it. However, it is a useful platform for sharing our preliminary work with persons willing to test it, for instance on multiple architectures. To upload a source package to you can use [23]dupload. Be careful with the alternative method, dput, which uploads to the main Debian archive by default, even in absence of configuration file. In the directory in which you built the sources, type dupload --to mentors yourpackage-itsversion.changes, after having created a configuration file according to the website's instructions. Uploading on the subversion repository of Alioth [24]Alioth is a service à la SourceForge, for the projects related to debian. It is open to everybody, one does not need to be an official developper to use it. The packaging effort of [25]debian-med is hosted on Alioth. To get an account on Alioth, just [26]open an account on Alioth, and then ask by e-mail to one of the administrators of the debian-med project to be added in the developpers team. This will give you a write access to the subversion repository. Debian has a dedicated tool for uploading a source package to subversion repositories, svn-inject, from the [27]svn-buildpackage package. In a directory where you want to hold the local copy of the subversion archive, and where you just built the package from source, type svn-inject yournewpackage.dsc svn+ssh://[EMAIL PROTECTED]/svn/debian-med/trunk/packages/. Références 1. http://charles-miroir.kunpuu.igloo/dmtmp01#before_starting 2. http://charles-miroir.kunpuu.igloo/dmtmp01#preliminary_package 3. http://charles-miroir.kunpuu.igloo/dmtmp01#modifications 4. http://charles-miroir.kunpuu.igloo/dmtmp01#buildpackage 5. http://charles-miroir.kunpuu.igloo/dmtmp01#polishing 6. http://charles-miroir.kunpuu.igloo/dmtmp01#id4685289 7. http://charles-miroir.kunpuu.igloo/dmtmp01#id4685326 8. http://charles-miroir.kunpuu.igloo/dmtmp01#docbase 9. http://charles-miroir.kunpuu.igloo/dmtmp01#id4686584 10. http://charles-miroir.kunpuu.igloo/dmtmp01#crosscheck 11. http://charles-miroir.kunpuu.igloo/dmtmp01#sharing 12. http://charles-miroir.kunpuu.igloo/dmtmp01#id4686707 13. http://charles-miroir.kunpuu.igloo/dmtmp01#id4686750 14. http://www.debian.org/doc/maint-guide/ 15. http://www.debian.org/social_contract#guidelines 16. http://www.debian.org/devel/wnpp 17. http://packages.debian.org/dpatch 18. http://www.debian.org/doc/maint-guide/ 19. http://www.jedit.org/ 20. http://www.debian.org/doc/packaging-manuals/menu.html/ch3.html#s3.7 21. https://wiki.ubuntu.com/MOTU/Packages/NoDesktopFile/Examples 22. http://mentors.debian.net/ 23. http://packages.debian.org/dupload 24. http://alioth.debian.org/ 25. https://alioth.debian.org/projects/debian-med/ 26. https://alioth.debian.org/account/register.php 27. http://packages.debian.org/svn-buildpackage