Tentative howto for attracting new members into the debian-med project
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
yourname@youraddress -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://yourAliothLogin@svn.debian.org/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
Reply to: