ubuntu Packaging Guide - Complete 2

xiaosuzi

                Packaging Python modules with CDBS
CDBS is
also very well suited for packaging Python modules, when these make use
of the distutils building system. Following is an example of a
debian/rules file, which in fact could be used ad verbatim for a great number of not-too-complicated modules. Notice that we also tell CDBS not to compress Python source files:  
DEB_PYTHON_SYSTEM=pysupport
include /usr/share/cdbs/1/rules/debhelper.mk
include /usr/share/cdbs/1/class/python-distutils.mk
# Don't compress .py files
DEB_COMPRESS_EXCLUDE := .pyImportant note on DEB_AUTO_UPDATE_DEBIAN_CONTROL:: Do not use DEB_AUTO_UPDATE_DEBIAN_CONTROL:=yes
to automatically change debian/control. It can cause bad things, and
Debian considers it a reason to reject a package from entering the
archives. See
http://ftp-master.debian.org/REJECT-FAQ.html
for more information.
For more information on CDBS, see Marc Dequènes's guide at
https://perso.duckcorp.org/duck/cdbs-doc/cdbs-doc.xhtml
.
">

Advanced Packaging
" lang="en">">
Creating More Than One Binary Package
Often you will want to split a source package into more than one binary package.
For single binary packages files are installed to debian/ and packaged from there.  For multiple packages they are installed to debian/tmp and split up by using multiple .install files  ">

" lang="en">">
Packaging Shared Libraries
This document explains what shared libraries are, focusing on exported symbols, and explains some of the details of how to package them.
It is a work in progress, based on a
MOTU/School
session. To see the log of that session please see
MOTU/School/LibraryPackaging

Shared Libraries
Shared libraries are object files containing compiled code that can be linked in to an executable. This is usually done for one of two reasons:

To provide a dynamically loaded plugin mechanism using dlopen.

To share code between multiple applications. This guide will mainly concern itself with the second application.
The structure of an (ELF) shared library is an object file containing "symbols" split in to "sections". Usually the details of the sections used are not important when packaging, merely the list of symbols, and as such we will focus on those.
A symbol is an item that is exported from the shared object. This means that it is accessible from an executable that loads the shared library. A symbol can be a variable, or a function, or something else like a struct. If it is a variable then the executable can read and write the value of the variable, and if it is a function then the executable can call the function.
The important thing to note is that if an executable contains code to call a function do_foo that it expects to find in libfoo.so and libfoo.so does not export a function with that name the program will not run. There are more complications that arise if the program and the library differ in what they think the definition of a symbol are, and so we must strive to make sure that this never happens.
Where a symbol comes from
Symbols are created by the compiler from certain constructs in the source code. Consider the following code:
#include
static int static_global = 42;
int extern_global;
const int const_extern_global = 42;
static void
local_function(int n)
{
        int local_var = 3;
        static int static_local_var = 23;
        if (n > 3) {
                local_var = n;
                static_local_var = 2 * n;
        }
        if (local_var > 4) {
                fprintf(stderr, "static_var=%d\n", static_global);
        } else {
                fprintf(stderr, "static_local_var=%d\n", static_local_var);
        }
}
void
global_function(int n)
{
        fprintf(stderr, "extern_global=%d\n", extern_global);
}
int
main(int argc, char **argv)
{
        local_function(argc);
        global_function(argc);
        return 0;
}When this code is compiled the compiler will decide whether each of the variables, functions etc. used in the code should be exported as a symbol. If we compile this code we will be able to see what becomes a symbol. Save the code to a file named

example.c and then run the following command to compile it:

$ gcc -c example.c -o example.oThis doesn't create a shared library yet, just an object file, but we are able to see some of the symbol information. Use nm to see the symbol list:
$ nm example.o
00000000 R const_extern_global
00000004 C extern_global
         U fprintf
0000006b T global_function
00000000 t local_function
00000092 T main
00000000 d static_global
00000004 d static_local_var.1781
         U stderrIn the rightmost column you can see the name of each of the symbols. There is one created for most of the variables and functions used in the file. However, local_var is not there, as this is a local variable to a function, and as such is allocated on the stack.
The other interesting feature is the number that is included in the name of static_local_var. This is to avoid name clashes if you were to have a static variable named static_local_var in another function in the file. (However, as we will see, this symbol will not make it in to the shared object, so this point is not too important.)
In the middle column of the output there are letters that correspond to the type of symbol. You can find the definitions in man nm. The ones listed above are

• R - The symbol is in the read only data section.
  
• C - Common symbol, i.e. uninitialized data.
  
• U - The symbol is defined somewhere other than this file.
  
• T - The symbol is in the text section, i.e. it is code.
  
• t - The symbol is in the text section.
  
• d - The symbol is in the initialized data section.
  

You may notice that the local symbols are given a lowercase letter, and the global symbols an uppercase letter. This means that only symbols with an uppercase letter will make it in to the shared object.
The interesting symbols are the ones given the symbol U, which indicates that they refer to the symbol, but do not define it, which means that it must be defined elsewhere. In this case stderr and fprintf fall in to that category, as they are defined in libc. The symbols will be matched up by the linker later.

CategoryPackagingGuide
">


Common Mistakes
dh_make Example Files
When you use dh_make to create the initial "debianisation", example files for various tasks are created in the debian/
directory. The templates have a .ex extension. If you want to use one,
rename it to remove the extension. If you do not need it, remove it to
keep the debian/ directory clean.
Abusing {{{.dirs}}} files
Many packages wrongly use dh_installdirs and .dirs files to create directories. 99% of those cases are not necessary, since dh_install and .install files will automatically take care of creating directories. You only need to use dh_installdirs if your package needs to ship empty nonstandard directories, e. g. /etc/mypackage/plugins.d/.

Changing the Original Tarball
" lang="en">">
There are two types of source packages, native and non-native.  
A native package is one that is specific to Ubuntu/Debian. It has the debian/ directory containing the packaging information and any changes to the source included in the tarball (usually _.tar.gz).  
Non-native
packages are more common. A non-native package splits the source
package into a _.orig.tar.gz tarball
that is identical (hopefully including md5sum) to the source tarball
downloaded from the project's homepage and a .diff.gz file that
contains all the differences (debian/ directory and patches) from the original source tarball. This whole paragraph just deals with non-native packages.
Here is a list of potential problems that can occur if you change the original tarball:

Reproducibility: If you take just the .diff.gz and .dsc, you or someone else has no means to reproduce the changes in the original tarball.

Upgradeability:
It is much easier to upgrade to a new upstream (from the author)
version if the .orig.tar.gz is preserved and there is a clear
separation between the upstream source and the changes made to produce
the Ubuntu source package.

Debian to Ubuntu Synchronization: Changing original tarballs makes it hard to automatically sync from Debian to Ubuntu.
Normally, only the .diff.gz and .dsc files change within the same
upstream version, since the .orig.tar.gz file is shared by all the
Debian or Ubuntu revisions. It is much more difficult to sync if the md5sums of the .orig.tar.gz files are not the same.

Usage of Revision Control for Debian package: If you use svn (and svn-buildpackage)
or similar tools to handle your Debian package, you usually don't store
the original tarball inside. If someone else does a checkout, he'll
need to get the original tarball separately. Other revision control
systems can be used to track only the packaging files (debian/, etc.) and not the whole source. However, if the .orig.tar.gz is not the same, then obviously problems can occur.

Security tracking: Consider a situation where someone wants
to introduce a backdoor/rootkit or other evil stuff. If the original
tarball is intact, it can be scanned easily through the .diff.gz to see
if the person who modified the package tried to do something evil. If
the tarball has changed, however, you also need to check the
differences between the tarball and the original source.

The .diff.gz:
The option to use the .diff.gz to reflect changes to the original
tarball already exists, so it is easy to make changes without touching
the original tarball.
It is acceptable to change the original tarball if one or more of the following hold true:

• It
  contains non-free parts that cannot be redistributed. Remove those
  parts, and note it in the packaging. Often such packages use "dfsg"
  (which stands for Debian Free Software Guidelines) in the package name
  and/or versioning to indicate that non-free parts have been removed.
• The authors only provide bzip2'ed source.
  • Just bunzip2 the .tar.bz2 and gzip -9 the resulting tar.
    
  • The md5sums of the .tar you provide and the original .tar must match!
  • Eventually provide a get-orig-source rule in debian/rules that does this conversion automatically.
• Directly imported from SVN
  • Provide get-orig-source in debian/rules.

The following are not reasons to change the original tarball:

• Wrong Directory Layout
• Files
  need to be removed to keep the .diff.gz small (e.g., files created by
  autotools). Everything that needs to be deleted should be removed in
  the clean rule. Since the .diff.gz is created with diff -u, you will not see removed files in the .diff.gz.
  
• Files need to be modified. Files that need to be modified should to go into .diff.gz. That is its purpose!
• Wrong permissions on files. You can use debian/rules to do this.
  

">

Solutions
" lang="en">">

• get-orig-source target:
  get-orig-source:
          cd ..; wget http://somesite.org/stuff/somesoftware-4.2.tar.bz2
          bzcat ../somesoftware-4.2.tar.bz2 | gzip -9fn -c - > ../somesoftware-4.2.tar.gz
          ln -s somesoftware-4.2.tar.gz ../${DEB_SOURCE_PACKAGE}_4.2.orig.tar.gzanother get-orig-source target:
  get-orig-source:
          cd .. && wget http://somesite.org/stuff/somesoftware-4.2.tar.bz2
          tar xjf ../somesoftware-4.2.tar.bz2
          rm ../somesoftware-4.2.tar.bz2
          mv somesoftware-4.2 somesoftware-4.2.orig
          tar -cf ../somesoftware-4.2.orig.tar somesoftware-4.2.orig
          rm -fr somesoftware-4.2.orig
          gzip -9fn ../somesoftware-4.2.orig.tar(and maybe also provide the rule  ../somesoftware_4.2.orig.tar.gz: get-orig-source , or list get-orig-source within .PHONY).
  if you use a watch file, this can be:
  # Path to the debian directory
  DEBIAN_DIR := $(shell echo ${MAKEFILE_LIST} | awk '{print $$1}' | xargs dirname )
  UPSTREAM_VERSION ?=$(shell uscan --dehs | sed -n 's/.*\(.*\).*/\1/p')
  get-orig-source:
          cd ${DEBIAN_DIR}/.. && uscan --force-download
          bzcat ../somesoftware-${UPSTREAM_VERSION}.tar.bz2 | gzip -9fn -c - > \
          ${CURDIR}/${DEB_SOURCE_PACKAGE}_${UPSTREAM_VERSION}.orig.tar.gzdirectly imported from cvs
  CVSDATE+=22 May 2007
  SW_VERSION+=4.2
  TARFILE+=somesoftware_$(SW_VERSION)~cvs$(shell date -d "$(CVSDATE)" +%Y%m%d).orig.tar.gz
  CVSHOME+=:pserver:anonymous@somesoftware.cvs.sourceforge.net:/cvsroot/somesoftware
  get-orig-source::
          cvs -d$(CVSHOME) login
          cvs -d$(CVSHOME) export -D "$(CVSDATE)" somesoftware
          tar czf $(CURDIR)/../$(TARFILE) $(CURDIR)/somesoftware
          rm -rf $(CURDIR)/somesoftware
  ../$(TARFILE):: get-orig-source

">

Tips
" lang="en">">

• Always remember to
  reference get-orig-source: in debian/rules when you need to repack the
  orig.tar.gz, explaining why you repacked it, and how others can verify
  your work.
• It's
  always a good idea to contact upstream and ask that stuff like
  autoconf-issues or directory layout (or old FSF-address) or other
  things you need to "patch" afterwards in .diff.gz be corrected.
• Older
  packages (from Debian Policy 3.3.8 or earlier) keep the information on
  repacking in debian/README.Debian-source. When updating an older
  package, it is acceptable to leave it here, although when upgrading or
  packaging new software, debian/copyright is much preferred.
• If a package already contains a debian/
  dir: Do not repackage it. You can ask the author(s) to delete the
  debian/ dir and provide a diff.gz instead. This makes it easier to
  review their work, and it separates packaging from program source. It
  is always a good idea to contact the program's author(s) and ask if you
  may correct autoconf issues, directory layout, an outdated Free
  Software Foundation address in COPYRIGHT files, or other things that
  are not specific to the packaging but would be convenient for you so
  you do not need to "patch" the source in .diff.gz.
  

">


Copyright Information
" lang="en">">
When dealing
with copyright information of packages, the following points are
critical, since they determine whether we are allowed at all to
redistribute the package. Packages must not be accepted if any of these
points is not fulfilled:

• The
  upstream tarball must contain verbatim copies of all licenses that are
  used by the files in the tarball. References to URLs or paths to system
  files (such as /usr/share/common-licenses/) are not sufficient.  The license(s) must accompany the source code.
  
• For
  all files it must be clear under which license they fall. Source code
  files should usually have a short comment at the top which points out
  the license.
• Files
  shipped under the GPL must be in the 'preferred form of modification'
  format. This applies to some other free licenses like the MPL, too (but
  e. g. not to BSD). Negative examples are Flash animations (*.swf), most PostScript/PDF files, and automatically generated source code. The suspicious-source script in the ubuntu-dev-tools package helps to spot such files.
  
• debian/copyright must list the primary copyright holders and all licenses (use pointers to /usr/share/common-licenses/ licenses included there), and declare which licenses apply to which parts of the package.
  
• Since
  there are now multiple versions of the GPL and LGPL, the copyright
  headers and files must be clear about which version(s) apply.

Common errors:

• Not shipping a copy of the LGPL when e. g. the build system is under LGPL, but the actual source is GPL
• Shipping PDFs and other files without source like a LaTeX or
  OpenOffice
  document
  
• Documentation is actually under GFDL, but debian/copyright does not mention it. As of gutsy, the GFDL is in /usr/share/common-licenses/, so a pointer there is sufficient for debian/copyright.
  
• debian/copyright only mentions a license, but no copyright
  
• The source files and/or debian/copyright are not clear about which files fall under which license
  
• Source is shipped under "GPL 2 only", while debian/copyright says "GPL 2 or later"
  
• GPLed packages link against OpenSSL (directly or indirectly)
• Different
  copyright holders and different licenses not mentioned in
  debian/copyright. Please grep -ir copyright * your package's directorys
  to make sure you got them all. In the case of large numbers of trivial
  copyright holders, not all need be mentioned (ask on IRC if you are in
  doubt), but all licenses must be listed.

The
rule of thumb is: look at copyright definitions in the source code, the
accompaning COPYING/AUTHORS file and at the involved licenses. There is
no such thing as a general rule of thumb to get it right: Different
licenses have different requirements for redistribution. While a public
domain license may even state that you can do everything with the
source code (which would mean that you need not put anything into
debian/copyright, or could even choose your own "may be distributed in
cd form only on rainy saturday's"-license), other licenses will impose
certain restrictions like including the copyright statement and/or
authors and making it clear if the source code is altered from its
original form. Sometimes the involved licenses even conflict with each
other (e.g. GPL and OpenSSL-license), which means that the resulting
binary package cannot be distributed.
">

Example 1: GPL
" lang="en">">
The GPL
requires that the complete license text is distributed (you can refer
to /usr/share/common-licenses/GPL, which is always there on
debian/ubuntu systems), the authors and the short disclaimer of
warranty (which you should include into debian/copyright). For example
   
    Copyright (C)   
    This program is free software; you can redistribute it and/or modify
    it under the terms of the GNU General Public License as published by
    the Free Software Foundation; either version 2 of the License, or
    (at your option) any later version.
    This program is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    GNU General Public License for more details.
    You should have received a copy of the GNU General Public License
    along with this program; if not, write to the Free Software
    Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301 USA
    On Debian GNU/Linux systems, the complete text of the GNU General
    Public License can be found in the /usr/share/common-licenses/GPL file.Please
also note, that upstream may also choose to restrict the license to one
specific version of the GPL, then you'll need to modify the text above.
Usually that very disclaimer can be found in the sourcecode of a
package. Then you can simply paste it to debian/copyright.
Always ensure you are using the correct version, GPL 2 or 3, LGPL 2.0, 2.1 or 3.  Use licencecheck
to check that the licence of all files is consistent. Make sure full
copies of the licences used are included by upstream, it is not
uncommon for LGPL or FDL to be missing.
">

General advice
Combining
GPL and another license will always make the combined work to be GPL
or, if the licenses conflict, undistributable. What licenses can be
combined can be found at
http://www.gnu.org/licenses/license-list.html
.
Usually
you will need to list the different licenses as well in
debian/copyright. A good way to do this, is to list files with a
different license together with the license in question. Whether you
will actually need to list the different licenses depends solely on the
license involved.
What
you don't need to mention is licenses from libraries against which the
package links. They are accompanied by their own copyright file and the
package in question can never be installed w.o. the library in
question. Of course there are exceptions which impose different
restrictions, like the OpenSSL license which requires a disclaimer to
be present in debian/copyright if it's used (as in linked against) in a
project. But these additional restriction mean, that the used library is incompatible with the GPL.
While
usually most of the projects don't have any legal issues, it's very
simple to introduce these with inaccurate copyright-files. Finally
there is a rule of thumb: Better safe than sorry - be verbose and list
everything which you are not sure if it should go into debian/copyright
or not.

Reference Packages
" lang="en">">
   Simple installation of files
   ubuntu-artwork
   example-content
   PHP
   gallery2
   roundcube
   
   Python                          
   Python Central   
   Python Support
   jokosher      
   linda        
   scribes        
   bittornado   
   pyenchant      
   aptoncd      
   python-imaging
   exaile      
   pyparallel     
   rhythmbox   
   debconf
   wvdial
   Maintainer scripts (postinst, postrm, prerm, preinst)
   

   Java packages
   
">

Patch Systems
" lang="en">">
Quite often
it turns out that the upstream source needs to be patched, either to
adjust the program to work with Ubuntu or to fix bugs in the source
before they are fixed upstream. But how should we represent these
changes? We could simply make the changes in the unpacked source
package, in which case the patch would be expressed in the .diff.gz
file. However, this is not ideal. If there is more than one patch you
lose the ability to separate the patches as you just see one big diff
that also contains the packaging files (in debian/).
This can make it more difficult when you want to send the patches
upstream. It is also very convenient to separate the author's source
from the changes made for Ubuntu. The best place to put this
information is in the debian/ that is
already used for the packaging files. For the rest of this chapter we
will be looking at the various ways to set up patches in this way.
">

General Tips
" lang="en">">
There will almost always be the need to apply patches before building a package. Here are a few patching tips taken from
http://wiki.debian.org/Games/ToolsDiscuss
.
Some tips on how to use patches efficiently (Thanks Linas Žvirblis):

• Provide
  descriptive file names for your patches:
  'fix-loading-libfoo-on-architecture-bar.patch' is a good name,
  '001.patch' is not;
• Make your patches stand-alone. Each patch should apply cleanly without depending on any other patch being applied;
• Avoid modifying the same file in multiple patches;
• If
  you absolutely need to create patches that depend on each other,
  specify that in the filenames: '00patchfoo-do-this.patch',
  '01patchfoo-do-that.patch' or similar;
• Do not include multiple unrelated modifications into a single patch;
• Patch
  your packages at build time. There is no need to ship a patch plus an
  already patched source. This only increases the size of the diff.
• Make sure patch is applied before anything else happens with your package. Make configure rule depend on the patch rule;
• Clean
  first, unpatch afterwards. Some files could have been modified during
  the build so unpatching may fail, unless you restore them. If simply
  makecleaning the sources does not restore their state, it may be a good
  idea to make backup copies, for example, in patch rule.
• Debian policy 3.8.0 imposes that packages specify explicit how to apply their patches when using a patch system (cf. [WWW]
  http://lists.debian.org/…ce/2008/06/msg00001.html
  ). The page
  README.sourceHowTo
  attempts to collect sample README.source file for each packaging systems.
  
• To find out which patch system is used, use what-patch from the ubuntu-dev-tools package:
  daniel@lovegood:~/jokosher-0.9$ what-patch
  cdbs
  daniel@lovegood:~/jokosher-0.9$ or
  daniel@lovegood:~/seahorse-2.22.2$ what-patch
  quilt
  daniel@lovegood:~/seahorse-2.22.2$

">

Patching Without a Patch System
" lang="en">">
As was
mentioned above, one can patch the original source by simply making the
changes in the unpacked source directory. A real-life example of this
is cron. If you grab cron's source package and look at the .diff.gz you will see that several of the original source's files were changed.
apt-get source cron
zgrep +++ cron*.diff.gzBut
as we mentioned before this is not really the best way to represent
patches. One better way is to create individual patch files, put them
in debian/patches/ and apply the patches (using patch) in debian/rules. This is what is done for udev:
apt-get source udev
zgrep +++ udev*.diff.gz
ls udev*/debian/patches/
less udev*/debian/rulesThe rules file has the following rules for applying and unapplying the patches:
# Apply patches to the package
patch: patch-stamp
patch-stamp:
        dh_testdir
        @patches=debian/patches/*.patch; for patch in $$patches; do \
                test -f $$patch || continue; \
                echo "Applying $$patch"; \
                patch -stuN -p1 That is all very nice, but how do we create new patches for udev using this scheme? The general approach is:

copy the clean source tree to a temporary directory

apply
all patches up to the one you want to edit; if you want to create a new
patch, apply all existing ones (this is necessary since in general
patches depend on previous patches)
if you want, you can use debian/rules for this: remove the patches that
come *after* the one you want to edit, and call 'debian/rules patch'.
The actual name for the patch target varies, I have seen the following
ones so far: patch setup apply-patches unpack patch-stamp. You have to
look in debian/rules to see what it is called.

copy the whole source tree again: cp -a /tmp/old /tmp/new

go into /tmp/new, do your modifications

go back into your original source tree, generate the patch with: diff -Nurp /tmp/old /tmp/new > mypatchname.patch
">

Example 1.
" lang="en">">
Let us make a new patch for udev called 90_penguins.patch which replaces Linux with Penguin in the udev README file:
cd udev*/
cp -a . /tmp/old
pushd /tmp/old
debian/rules patch
cp -a . /tmp/new; cd ../new
sed -i 's/Linux/Penguin/g' README
cd ..
diff -Nurp old new > 90_penguins.patch
popd
mv /tmp/90_penguins.patch debian/patches
rm -rf /tmp/old /tmp/new
">

Example 2.
" lang="en">">
What happens if we want to edit an existing patch? We can us a similar procedure as
Example 1
but we will apply the patch to be edited first:
cp -a . /tmp/old
pushd /tmp/old
cp -a . /tmp/new
cd ../new; patch -p1  10-selinux-include-udev-h.patch
popd
mv /tmp/10-selinux-include-udev-h.patch debian/patches
rm -rf /tmp/old /tmp/new
">

So
this way of patching the source, while technically fine, can become
very complicated and unmanageable. To make patching easier and more
straightforward patch systems were developed. We will take a look at
couple popular ones.
CDBS with Simple Patchsys
" lang="en">">
The CDBS
build helper system (see the section called “Packaging With CDBS”) has
a very simple patch system built in. You simply need to add an include
for simple-patchsys.mk in debian/rules. An example is pmount. Its entire rules looks like:  
include /usr/share/cdbs/1/rules/debhelper.mk
include /usr/share/cdbs/1/class/autotools.mk
include /usr/share/cdbs/1/rules/simple-patchsys.mk
common-post-build-arch::
        # Generate a POT file
        cd po; intltool-update -p --verbose Simple patchsys also has a patch editor built in called cdbs-edit-patch. You can give cdbs-edit-patch
either the name of an existing patch to edit or a new patch to create.
It will apply the existing patch, if it exists, and put you in a new
shell. You can then make any changes you want added to the patch and
finally type Ctrl-D to exit the shell and create the new patch. The patches are stored in debian/patches/
">

cdbs with simple-patchsys (example package: pmount)
" lang="en">">
cdbs'
simple-patchsys.mk module matches its name; it has no bells and
whistles whatsoever. However, it is pretty popular since it is
sufficient for most tasks, and long ago Martin Pitt wrote a script 'cdbs-edit-patch' which most people can live with pretty well. This script is contained in the normal cdbs package.
You
just supply the name of a patch to the script, and depending on whether
it already exists or not, it will create a new patch or edit an
existing one.
Example with pmount:
  cd /wherever/you/unpacked/the/source/pmount-0.9.11
  cdbs-edit-patch 03-simple-readme.patch
  echo 'This should document pmount' > README
  Editing an already-existing patch works exactly the same way.
">

Since the Ubuntu Edgy version of cdbs, cdbs-edit-patch also works for packages using tarball.mk, and it can edit patches which produce rejections.
dpatch
" lang="en">">
A popular patch system is dpatch. It has a dpatch-edit-patch script like cdbs has but stores the patches a little differently. It uses a file named debian/patches/00list
to find the name and order of patches to apply. This means you can
order your patches in whichever way you want and can disable a patch
without removing it altogether. However, it also means you need to
update 00list if you add a patch. If dpatch-edit-patch
is called with two arguments it will edit/create the the patch named by
the first argument relative to the patch named by the second argument.
In other words:
dpatch-edit-patch new.dpatch old.dpatch will apply patches up to old.dpatch and then create new.dpatch. Note that dpatch patches usually have a .dpatch suffix. This is because dpatch stores the patches in a slightly different format than a normal patch that adds a special header.
">

quilt (example package: xterm)
" lang="en">">
quilt is the other non-dumb standard patch system. Like dpatch, it has a list of patches to apply in debian/patches/series. It is non-trivial to set up and has a lot of advanced commands which make it very flexible, but not very easy to use.
So I will only show a small example here, too. First, set yourself up to use quilt:
  cd /wherever/you/unpacked/the/source/
  mkdir debian/patches
  export QUILT_PATCHES=debian/patches
  touch debian/patches/seriesNow let's edit the already existing patch 901_xterm_manpage.diff:
  quilt push 901_xterm_manpage.diff
  sed -i 's/Copyright/Copyleft/' xterm.man
  quilt refresh 901_xterm_manpage.diff
  quilt pop -aSo unlike the other patch systems, quilt works with patched inline sources, but keeps track of modifications.
Finally, let's add a new patch to the top of the stack:
  quilt push -a
  quilt new muhaha.diff
  quilt add README  # you have to do that for all files you modify
  sed -i '1 s/^/MUHAHA/' README
  quilt refresh
  quilt pop -a
">

Patching other people's packages
The most
important thing to keep in mind when patching packages maintained by
other people is to keep the patch system (or lack thereof) that the
maintainer has set up. This will ensure consistency and make the
package maintainer more likely to accept your patch.
It
is also a good idea to separate patches logically rather than creating
one giant patch. If the upstream authors apply one of your changes but
not another it is much easier to just drop a patch than edit a
monolithic patch to update it.
KDE
" lang="en">">
The
basic packaging
section in the
PackagingGuide
will explain the basic, while this page tries to explain KDE specific bits.
If it's not already done, you have to install all the software listed in the
Debian New Maintainer's Guide
and the
Debian Developer's Reference
.  
Also recommended are  

• the kdesdk package which furnish many useful applications and scripts and
  
• docbook2x,
  because it can be useful to convert docbook into man pages (remember
  debian policy implies that every single application has a man page!).
  

">

Essential Packaging Bits
" lang="en">">
KDE 3 applications usually use the GNU autoconf/automake build system.  There is a CDBS include file designed for KDE.
include /usr/share/cdbs/1/class/kde.mkYou will need to build-dep on kdelibs4-dev and, if the package build kcontrol modules, kdebase-dev.
If you patch any Makefile.am or configure.in.in files you will need to re-run the auto-tools.  Do this with:
make -f debian/rules buildprepThis is also necessary if your upstream has not already run this, e.g. if there is no configure file.
KDE 4 applications use a new build system, CMake.
The way we build KDE 4 packages is still changing so there is no file
included in CDBS yet. You can get a suitable kde.mk by downloading the
source for kde4libs and copying debian/cdbs.
include debian/cdbs/kde.mkYou will need to build-depend on kdelibs5-dev and sometimes also libphonon-dev and kdepimlibs5-dev.
If there is already a KDE 3 application with the same name in the archive, rename the package to -kde4.
">

KDE Manpages
" lang="en">">
A template of a KDE manpage can be found here
http://people.ubuntu.com/~dholbach/packagingguide/kde/sample.1.docbook

This
file is a standard file for a basic KDE application. Customize it for
your application and check that every important command line option is
described in detail. If you don't want to edit the file by hand,
install the manedit package and type
manedit [manpage name or file]Add a build-depend on docbook2x in debian/control.
After that just add this line to the debian/rules file (assuming the name of the binary package is myapp):
build/myapp::
        docbook2x-man debian/myapp.1.docbook
cleanbuilddir/myapp::
        rm -f myapp.1
DEB_INSTALL_MANPAGES_myapp = myapp.1Of course you have to replace myapp.1.docbook with your manual source file. You also have to add a docbook2x build dependency to the debian/control
file. If you have more than one manpage to install (e.g. if your .deb
installs a program and its daemon) simply separate their names with a
space:
DEB_INSTALL_MANPAGES_myapp = myapp.1 myappdaemon.8As an alternative you can use the kdemangen.pl script to generate a man page based on the command line help of the program.
">

Supplementary Files

.desktop Files
" lang="en">">
In order to
ensure that the menus are properly populated, and that software is
easily installable with Add/Remove Packages, each package should
contain a .desktop file. As a matter of policy, .desktop files should
only be present for GUI interfaces: software intended to be used from
the command-line should not provide such an interface.
.desktop
files may be included in packages in two ways, either as part of the
upstream distribution, or as part of the distribution packaging.
Including the .desktop file in the upstream distribution is vastly
preferred, as this allows for appropriate translation of the .desktop
file. If it cannot be included upstream, the .desktop file should be
stored in the debian/ directory.
Criteria for the inclusion of .desktop files:

The package must provide a binary with a GUI interface

The binary must be typically executed with constant arguments

Users would expect to launch the program from the menu Packages
typically not needing a .desktop file are: Window Managers, programs
that do not have sensible defaults, programs that only act on files
(rather than having a standard interface), programs that have no GUI,
programs that start up invisible.
Some packaging notes:

• In debian/control, if cdbs is not used, Build-Depend on debhelper (>= 4.2.21).
  
• In debian/rules, if cdbs's gnome.mk is not used, call dh_desktop in binary*
  
• ensure that .desktop files are installed or moved to /usr/share/applications/.desktop
  
• ensure that icon files are installed or moved to /usr/share/pixmaps/
  

Some ideas about icons:

• Provide an 32x32 pixel XPM icon for use by the Debian menus
• Optionally
  provide a 48x48 pixel PNG icon for use by freedesktop.org menus (the
  Debian icon will be used if this is unavailable)
• If neither format is available, many formats can be converted as follows:
• Get a base icon (clip of package graphic, .ico file, from scratch, etc.)
• Crop / resize to 32x32 pixels
• run convert editedicon.ico .xpm (requires imagemagick)
  
• if convert generated multiple images, select one (and name correctly)

About .desktop files generally:

• Check the spec at
  http://standards.freedesktop.org/desktop-entry-spec/latest/
  
  
• Avoid Absolute pathnames in .desktop files
  
• Do not include a file type extension in Icon=
• Ensure that Categories= includes at least one Registered Category
  
• Add any other applicable Additional Categories
• Check with desktop-file-validate to ensure everything is correct
  

The Workflow:

• Find a package without a .desktop file
  

• Verify there is no .desktop file in the latest development version
  
• If no .desktop file is needed, add the package to the list below
  
• If a .desktop is needed:
  
• Check to see if there is a .desktop in the upstream or Debian bug tracker
  
• Create the necessary .desktop / icon if necessary
  
• Open a wishlist bug in the package reporting the missing .desktop file
  
• Attach the .desktop file and icon to the bug (optionally a patch for both)
  
• Link the bug to the Debian BTS (create a BTS bug if required)
• Tag the bug with "desktop-file"
  

Simple Creation techniques:

• In GNOME: use Nautilus' "Create Launcher" to create a template file
• Scripted:
  Some of this can be automated. Please check the results of the
  automation prior to submission. Most importantly, please ensure that
  any useful additional categories are included.

Shell sniplets that might prove useful:

• Using an absolute path for an icon:
  grep -E "^Icon=\/usr\/" /usr/share/applications/*.desktop | cut -d: -f1 | xargs dlocate
• Using an absolute path for a binary:
  grep -E "^Exec=\/usr\/" /usr/share/applications/*.desktop | cut -d: -f1 | xargs dlocate
• .desktop file fails validation:
  for i in /usr/share/applications; do desktop-file-validate $i >> /dev/null || echo $i; done | xargs dlocate

A minimal desktop file for a program to appear in the application menu looks like this:
[Desktop Entry]
Name=foo
Name[xx]=foo
GenericName=Bar description
Exec=kfoo
Icon=kfoo
Terminal=false
Categories=Qt;KDE;Utility;You
should ensure that the icon pointed to by Icon= exists in the hicolor
namespace and not in the crystalsvg or oxygen themes, this is so it can
be found by Gnome and other desktops.
Some notes about KDE .desktop files:
" lang="en">">
KDE also uses .desktop files to describe many resources such as libraries to be loaded or kcontrol modules.
.desktop files for applications should be in /usr/share/applications/kde for KDE 3 or  /usr/share/applications/kde4 for KDE 4.
Sometimes packages install the desktop file in the old directory (/usr/share/applnk). You may want to copy the furnished desktop file to the new location (/usr/share/applications/kde). Add these lines to debian/rules:
install/myapp::
    #other stuff
    dh_install desktop_file usr/share/applications/kde
">

">

Man Pages
Using POD
" lang="en">">
POD is a
very simple but also elegant format for writing manual pages. It is
much easier to learn than writing it directly in groff or using other
alternatives like docbook.
Basic template
Below
is a sample manpage template in POD format. Customize it for your
application and check that every important command line option is
described in detail. You can see a real example
here
.
=head1 NAME
Command - Short one-line description.
=head1 SYNOPSIS
command [options...]
=head1 DESCRIPTION
Command is a foo that does bar.
=head1 OPTIONS
=over 8
=item B>
Uses the given value as key.
=item B
Shows an easter egg (don't explain this in real man pages ;)).
=item B
Doesn't do anything.
=item B
Displays information about the currently installed version and exists.
=head1 BUGS
This command has absolutely no bugs, as I have written it. Also, as it has no bugs, there is no need for a bug tracker.
=head1 AUTHORS
B was written by Joe Hacker  and John Dough . This manual page was written by Cool Packager .
Both are released under the GNU General Public License, version 3 or later.
=cut
Some formatting options
B  -  "...text..." will be shown in bold.
I  -  "...text..." will be shown in italics.Usually,
the command name is always written in bold (except in the NAME and
SYNOPSIS sections), and variables that the user should replace in
italics (as in --key=I).
Necessary packaging changes

- Add a build dependency on 'perl' in debian/control. - After that just add this line to the debian/rules file (assuming the name of the binary package is 'myapp' and that it is using cdbs):
build/myapp::
        pod2man --section=1 --release=$(VERSION) --center "" debian/myapp.pod > myapp.1
cleanbuilddir/myapp::
        rm -f myapp.1
DEB_INSTALL_MANPAGES_myapp = myapp.1

Of
course you have to replace 'myapp.pod' with the name of your manpage
source file, and the section number with that one corresponding to what
you are documenting (see 'man man' for a list of all sections).
If
you have more than one manpage to install (e.g. if your .deb installs a
program and its daemon) simply separate their names with a space:
DEB_INSTALL_MANPAGES_myapp = myapp.1 myappdaemon.8
">

Recipes
Recipe: Updating An Ubuntu Package
Introduction
In this recipe we'll update brasero 0.5.2-0ubuntu1 to 0.6.1-0ubuntu1. This should give you a good introduction to updating packages to a new upstream version.
Ingredients
" lang="en">">

To sign the package once it's finished, you'll need a GPG key. See the
GnuPrivacyGuardHowto
for a guide.

The
debian packaging tools use some environment variables to put your name
and e-mail address in the changelog and to find your GPG key ID. To set
these up, edit ~/.bashrc and add your name and mail address (the ones you used for the GPG key), example:
export DEBFULLNAME='Daniel Holbach'
export DEBEMAIL='daniel.holbach@ubuntu.com'to make these changes take affect, start a new terminal or type source ~/.bashrc in the terminal.

pbuilder is a very handy command used to test-build packages. See the
PbuilderHowto
for a guide to setting it up for the active development release.

Install some necessary tools:
sudo apt-get install devscripts build-essential wget cdbs fakeroot liburi-perl debhelper pbuilder dpatch quilt gnome-pkg-tools
">

Method
" lang="en">">

Get the source of the old brasero package.
For that, you'd usually just run apt-get source brasero. As this is just an example, you can run:
dget -xu http://people.ubuntu.com/~dholbach/motu/brasero_0.5.2-0ubuntu1.dsc

Get the new source.
Usually, you'd look up from where the old version was downloaded (check debian/copyright) and use the source from there. But as this is a prepared example...:
wget http://people.ubuntu.com/~dholbach/motu/brasero-0.6.1.tar.gz

Unpack and rename the new source tarball:
tar xfz brasero-0.6.1.tar.gz
mv brasero-0.6.1.tar.gz brasero_0.6.1.orig.tar.gz (If you use the _.orig.tar.gz scheme, a .diff.gz file will be created automatically during one of the next steps that contains all your changes regarding the Upstream Tarball.)

Copy the packaging over into the new source tree:
cp -r brasero-0.5.2/debian brasero-0.6.1/

Add a debian/changelog entry:
cd brasero-0.6.1
dch -i Here you enter something like "New upstream version" and make sure the version number is 0.6.1-0ubuntu1.

Create the source package from it:
debuild -S -sa

Try to build it:
cd ..
sudo pbuilder build brasero_0.6.1-0ubuntu1.dsc

DONE
**Note: This package does not build using pbuilder in Intrepid. It
looks like the old brasero package uses an older version of GCC. You
should not have this problem when you build other packages.
">

For Bonus Points...
" lang="en">">

Check configure.in for changes you need to reflect in the packaging:
diff -u brasero-0.{5.2,6.1}/configure.in Sometimes this file might be called configure.ac. Most software programmed in C or C++ has this file which generates checks during the configure run of the build.
BR
If you look closely, you'll notice that most changes are reformatting and only
-LIBBURN_REQUIRED=0.2.3
+LIBBURN_REQUIRED=0.3.4 might be relevant to us. In debian/control you'll see that we don't use libburn, so we're done here.

Read the NEWS file before:
less brasero-0.6.1/NEWS
This file (if the upstream project uses it) contains valuable
information about what the package update is about. As a maintainer you
want to know what's been going on.

Compare the contents of the old vs. the new package:
wget http://people.ubuntu.com/~dholbach/motu/brasero_0.5.2-0ubuntu1_i386.deb
debdiff brasero_0.5.2-0ubuntu1_i386.deb /var/cache/pbuilder/result/brasero_0.6.1-0ubuntu1*.deb

The
output will show you that some icons have been replaced with others and
some translations were added. Nothing to worry about. All looks good.

To download the old package, you would normally run something like
aptitude download brasero

Get working on upgrade bugs:
https://bugs.launchpad.net/ubuntu/+bugs?field.tag=upgrade

">

Creating A Debdiff
Introduction
In this
recipe we'll fix a simple problem with a package and create a debdiff
which you can send to others or attach to bug reports to fix a package.
Ingredients
" lang="en">">

The
debian packaging tools use some environment variables to put your name
and e-mail address in the changelog and to find your GPG key ID. To set
these up, edit ~/.bashrc and add your name and mail address (the ones you used for the GPG key), example:
export DEBFULLNAME='Daniel Holbach'
export DEBEMAIL='daniel.holbach@ubuntu.com'to make these changes take effect, start a new terminal or type source ~/.bashrc in the terminal.

pbuilder is a very handy command used to test-build packages. See the
PbuilderHowto
for a guide to setting it up for the active development release.

Install some necessary tools:
sudo apt-get install devscripts build-essential wget fakeroot cdbs patchutils debhelper

To sign the package once it's finished, you'll need a GPG key. See the
GnuPrivacyGuardHowto
for a guide. Note that this is only important if you plan to upload the
result to a access-restricted archive directly : most of the time it is
not important when creating a debdiff.
">

Method
" lang="en">">

Let's pretend we got a bug report saying that colour in the description of xicc should be color and we want to fix it. (This is just a bad joke and a bad example.) First verify if that's true:
$ apt-cache show xicc
Package: xicc
Priority: optional
Section: universe/x11
Installed-Size: 72
Maintainer: Ross Burton
Architecture: amd64
Version: 0.2-2
Depends: libc6 (>= 2.3.4-1), libglib2.0-0 (>= 2.8.0), libice6, libsm6, libx11-6
Filename: pool/universe/x/xicc/xicc_0.2-2_amd64.deb
Size: 8224
MD5sum: a266d60cd721ef91fcb1d3d47ecd6a40
SHA1: b8da21b8dfba7ed9c7ac6fa5c9c3e70b438d7124
SHA256: 635c287a1c43df31670a20194e774561479d70d981bf24c143c3711799bd839a
Description: set the ICC colour profile for an X display
This utility lets you set an ICC colour profile for an X display, so that
applications can use it to display colour calibrated images.  Applications have
to specifically look for this atom but several applications such as Gimp and
Eye Of Gnome already do.
Bugs: mailto:ubuntu-users@lists.ubuntu.com
Origin: Ubuntu

Time to act on it... get the source of the package:
dget -xu http://people.ubuntu.com/~dholbach/motu/xicc_0.2-2.dsc

Edit debian/control and fix colour:
cd xicc-0.2
sed -i 's/colour/color/g' debian/controlOf course patching is not always that easy and you might have to patch bigger parts of the package. Please refer to our
Patch guidelines
.

Adhere to
DebianMaintainerField
: Edit debian/control and replace
Maintainer: Ross Burton  with
Maintainer: Ubuntu MOTU Developers
XSBC-Original-Maintainer: Ross Burton You can use the update-maintainer tool (in the ubuntu-dev-tools package) for that.

Update debian/changelog:
dch -i and describe the changes you did.

Generate a new source package:
debuild -S or if you're creating an unsigned package:
debuild -S -us -uc

Look at the debdiff:
cd ..
debdiff xicc_0.2-2.dsc xicc_0.2-2ubuntu1.dsc | less

To create a patch file that you can send to others, run
debdiff xicc_0.2-2.dsc xicc_0.2-2ubuntu1.dsc > xicc_0.2.2ubuntu1.debdiff

And we're done. You can now attach the debdiff to a bug report or send it to the relevant person.
SponsorshipProcess
explains how to get a package uploaded to Ubuntu.
">

Creating And Using A debian/watch File
Introduction
This should show you why it is important to add a debian/watch file to your package and how easy it is to upload a new upstream version.
Note: the method is exactly the same for an Ubuntu package, just change revision number in changelog version.
Ingredients
" lang="en">">

To sign the package once it is ready, you will need a GPG key. See
GnuPrivacyGuardHowto
for a guide.

Debian
packaging tools use some environment variables to put your name and
e-mail address in the changelog and to find your GPG key ID. To set
these up, edit ~/.bashrc and add your name and mail address (the ones you used for the GPG key), example:
export DEBFULLNAME='Arthur Loiret'
export DEBEMAIL='arthur.loiret@gmail.com'to make these changes take effect, start a new terminal or type source ~/.bashrc in the terminal.

pbuilder is a very handy command used to test-build packages. See the
PbuilderHowto
for a guide on how to set it up for the current development release.

Install some necessary tools:
sudo apt-get install devscripts build-essential wget fakeroot
">

Method
" lang="en">">
In this recipe we will update medit 0.8.5-1 to 0.9.4-0ubuntu1 using uscan and uupdate.  

Get the source of the current medit (0.8.5) package. Run:
dget -xu http://people.ubuntu.com/~dholbach/motu/medit_0.8.5-1.dsc

Now,
instead of getting new upstream sources by hand, we are going to add a
debian/watch file, which is going to allow us to check automatically
new upstream versions using uscan.
The very first line of the watch file must be the format version, currently 3, and then other lines can contain urls to parse.
For example, we are going to try
version=3
http://sf.net/mooedit/medit-(\d.*)\.tar\.bz2As you can see the syntax for [
http://sourceforge.net

SourceForge
] projects is http://sf.net// (see the man page of [
http://dehs.alioth.debian.org/uscan.html
uscan] for more information).

Then, we are going to run uscan to ensure the debian/watch works, run in sources directory:
uscan --verbose
-- Scanning for watchfiles in .
-- Found watchfile in ./debian
-- In debian/watch, processing watchfile line:
   http://sf.net/mooedit/medit-(\d.*)\.tar\.bz2
-- Found the following matching hrefs:
     medit-0.6.98.tar.bz2
     medit-0.6.99.tar.bz2
     medit-0.7.0.tar.bz2
     medit-0.7.1.tar.bz2
     medit-0.7.9.tar.bz2
     medit-0.7.95.tar.bz2
     medit-0.7.96.tar.bz2
     medit-0.7.97.tar.bz2
     medit-0.8.0.tar.bz2
     medit-0.8.1.tar.bz2
     medit-0.8.10.tar.bz2
     medit-0.8.11.tar.bz2
     medit-0.8.2.tar.bz2
     medit-0.8.3-b20060223.tar.bz2
     medit-0.8.3.tar.bz2
     medit-0.8.4.tar.bz2
     medit-0.8.5.tar.bz2
     medit-0.8.6.tar.bz2
     medit-0.8.7.tar.bz2
     medit-0.8.8.tar.bz2
     medit-0.8.9.tar.bz2
     medit-0.9.0.tar.bz2
     medit-0.9.1.tar.bz2
     medit-0.9.2.tar.bz2
     medit-0.9.3.tar.bz2
     medit-0.9.4.tar.bz2
Newest version on remote site is 0.9.4, local version is 0.8.5
=> Newer version available from
    http://qa.debian.org/watch/sf.php/mooedit/medit-0.9.4.tar.bz2
-- Downloading updated package medit-0.9.4.tar.bz2
-- Successfully downloaded updated package medit-0.9.4.tar.bz2
    and symlinked medit_0.9.4.orig.tar.bz2 to it
-- Scan finishedPerfect, we have just got the new upstream version :)

Have a look at the new orig tarball name. Just type:
ls ..
medit-0.8.5/  medit_0.8.5-1.diff.gz  medit_0.8.5-1.dsc  medit_0.8.5.orig.tar.gz  medit_0.9.4.orig.tar.bz2  medit-0.9.4.tar.bz2So,
new orig tarball's name is medit_0.9.4.orig.tar.bz2. Don't worry about
the archive type, uupdate supports .tar.gz, .tar.bz2, .tar.Z, .tgz,
.tar and .zip formats, but if you still have doubts about the new orig
tarball format, please read [
https://wiki.ubuntu.com/PackagingGuide/Basic#ChangingOrigTarball
this]

Run uupdate on new orig tarball:
uupdate ../medit_0.9.4.orig.tar.bz2
New Release will be 0.9.4-0ubuntu1.
-- Untarring the new sourcecode archive ../medit_0.9.4.orig.tar.bz2
8 out of 11 hunks FAILED -- saving rejects to file config.sub.rej
4 out of 6 hunks FAILED -- saving rejects to file config.guess.rej
uupdate: the diffs from version 0.8.5-1 did not apply cleanly!
Rejected diffs are in ./config.sub.rej
./config.guess.rej
Remember: Your current directory is the OLD sourcearchive!
Do a "cd ../medit-0.9.4" to see the new package
(Did you see the warnings above?)Don't
worry about the failure on config.sub, this usually happens very often.
Go to the new directory and remove config.sub.rej ;)
BR
Now
the package is almost ready. You have to update changelog and check it
builds fine. For that the easiest and the cleanest way is to type dch -e, here is the result you should get:
medit (0.9.4-0ubuntu1) intrepid; urgency=low
  * New upstream release
  * Add debian watch
-- Your Name   Tue, 04 Nov 2008 20:32:22 -0500(You dont have to forget to include the debian/watch on previous upload don't worry

)

Let's test the new upstream release, run debuild -S -sa, and finally:
sudo pbuilder build ../medit_0.9.4-0ubuntu1.dsc)
">

Notes
Steps 3 and 5 (of the
howto
) can be combined by using additional parameters in the URL line of the watch file
version=3
http://sf.net/medit/mooedit-(.*).tar.bz2 debian uupdate
You may want to continue at
MOTU/Contributing#head-b205c74e27fe15e79e10c9e7f14d3cdfb359d81d
to create an interdiff for sponsorship.
Appendix
Additional Resources
" lang="en">">
Debian Resources

• 
  Debian New Maintainers Guide
  - Good resource for learning to package.
  
• 
  Debian Policy
  - The essential Policy manual for Debian and Debian-based distros.
  
• 
  Debian Developer's Reference
  - Specific information for Debian Developers but has some items of interest for packagers.
  
• 
  Library Packaging Guide
  - Guide for packaging libraries.
  
• 
  Debian Women Packaging Tutorial
  - Another good introduction to Debian packaging.
  
• 
  Debian Mentors FAQ
  
  
• 
  debian-mentors mailing list
  - new maintainers can ask questions and find a Debian sponsor here
  
• 
  Generating multiple binaries from a single source
  
  
• 
  Debian New Python Policy
  
  
• 
  Debian CLI Policy
  
  
• 
  Debian Packaging Handbook
  
  

Wiki Resources

• 
  MOTU/GettingStarted
  
  
• 
  PackagingGuide
  
  
• 
  UbuntuDevelopment
  
  
• 
  PbuilderHowto
  
  
• 
  DebootstrapChroot
  
  
• 
  UbuntuDevelopment/NewPackages
  
  

Other Resources

• 
  IBM Packaging Tutorial
  
  
• 
  Duckcorp CDBS Documentation
  
  
• 
  Managing packages with Subversion and pbuilder
  
  
• 
  Creating .desktop files
  (
  Categories
  )
  
• 
  Debian Library Packaging Guide
  
  
• 
  Make Manual
  (debian/rules is a Makefile)
  

">

example files
" lang="en">">

• Readme.Debian
  is used to document changes that you have made to the original upstream
  source that other people might need to know or information specific to
  Debian or Ubuntu.
  
• conffiles.ex: If the package installs a configuration file, when the package is upgraded dpkg
  can prompt a user whether to keep his or her version if modified or
  install the new version. Such configuration files should be listed in conffiles
  (one per line). Do not list configuration files that are only modified
  by the package or have to be set up by the user to work.
  
• cron.d.ex:
  If your package requires regularly scheduled tasks to operate properly,
  you can use this file to configure it. If you use this file, rename it
  to cron.d.
  
• dirs specifies the directories that are needed but the normal installation procedure (make installapplication) somehow doesn't create.
  
• docs specifies the filenames of documentation files that dh_installdocs will install into the temporary directory.
  
• emacsen-*.ex specifies Emacs files that will be bytecompiled at install time. They are installed into the temporary directory by dh_installemacsen.
  
• init.d.ex: If your package is a daemon that needs to be run at system startup rename this file to init.d and adjust it to your needs.
  
• manpage.1.ex and manpage.sgml.ex are templates for man pages if the package does not already have one.
  
• menu.ex is used to add your package to the Debian menu. Ubuntu uses the
  freedesktop.org
  standard
  .desktop
  files but remember that packages in Universe/Multiverse are widely used
  in other (desktop-less) environments. Beside, we strongly want to
  give-back to Debian (where menu files are required by policy),
  therefore you are encouraged to include them in your Ubuntu package
  too.
  
• watch.ex: The package maintainer can use the uscan program and a watch file to check for a new upstream source tarball. (
  PackagingGuide/Recipes/DebianWatch
  )
  
• ex.package.doc-base is used to register your package's documentation (other than man and info pages) with doc-base.
  
• postinst.ex, preinst.ex, postrm.ex, and prerm.ex: These maintainer scripts are run by dpkg when the package is installed, upgraded, or removed.
  

For more details refer to the Debian New Maintainer's Guide.
">

List of Debhelper Tools
">

• dh_builddeb - build debian packages
  
• dh_clean - clean up package build directories
  
• dh_clideps - calculates CLI (.NET) dependencies
  
• dh_compress - compress files and fix symlinks in package build directories
  
• dh_desktop - Register .desktop files
  
• dh_fixperms - fix permissions of files in package build directories
  
• dh_gconf - generate GConf schema registration scripts
  
• dh_gencontrol - generate and install control file
  
• dh_install - install files into package build directories
  
• dh_installcatalogs - install and register SGML Catalogs
  
• dh_installchangelogs - install changelogs into package build directories
  
• dh_installcligac - register assemblies to be late installed into a GAC
  
• dh_installcron - install cron scripts into etc/cron.*
  
• dh_installdeb - install files into the DEBIAN directory
  
• dh_installdebconf - install files used by debconf in package build directories
  
• dh_installdefoma - install a defoma related scripts
  
• dh_installdirs - create subdirectories in package build directories
  
• dh_installdocs - install documentation into package build directories
  
• dh_installemacsen - register an emacs add on package
  
• dh_installexamples - install example files into package build directories
  
• dh_installinfo - install and register info files
  
• dh_installinit - install init scripts into package build directories
  
• dh_installlogcheck - install logcheck rulefiles into etc/logcheck/
  
• dh_installlogrotate - install logrotate config files
  
• dh_installman - install man pages into package build directories
  
• dh_installmanpages - old-style man page installer
  
• dh_installmenu - install debian menu files into package build directories
  
• dh_installmime - install mime files into package build directories
  
• dh_installmodules - register modules with modutils
  
• dh_installpam - install pam support files
  
• dh_installppp - install ppp ip-up and ip-down files
  
• dh_installtex - register Type 1 fonts, languages, or formats with TeX
  
• dh_installudev - install udev rules files
  
• dh_installwm - register a window manager
  
• dh_installxfonts - register X fonts
  
• dh_installxmlcatalogs - install and register XML catalog files
  
• dh_link - create symlinks in package build directories
  
• dh_listpackages - list binary packages debhelper will act on
  
• dh_make - Debianize a regular source archive
  
• dh_makeclilibs - automatically create clilibs file
  
• dh_makeshlibs - automatically create shlibs file
  
• dh_md5sums - generate DEBIAN/md5sums file
  
• dh_movefiles - move files out of debian/tmp into subpackages
  
• dh_perl - calculates perl dependencies
  
• dh_pycentral - use the python-central framework to handle Python modules and extensions
  
• dh_pysupport - use the python-support framework to handle Python modules
  
• dh_python - calculates python dependencies and adds postinst and prerm python scripts
  
• dh_scrollkeeper - generate
  ScrollKeeper
  registration scripts
  
• dh_shlibdeps - calculate shared library dependencies
  
• dh_strip - strip executables, shared libraries, and some static libraries
  
• dh_suidregister - obsolete suid registration program
  
• dh_testdir - test directory before building debian package
  
• dh_testroot - ensure that a package is built as root
  
• dh_testversion - ensure that the correct version of debhelper is installed
  
• dh_undocumented - obsolete undocumented.7 symlink program
  
• dh_usrlocal - migrate usr/local directories to maintainer scripts
  

=====================================================================
The process needs internet connection and configured source.list.
1, Download the source package
#apt-get source packname_packversion-debianversion
2, Patch the source
#cd packname_packversion
Modify the source as you want.
You'd better inscrase the debianversion of the package by modifying
debian/changelog, to avoid conflict.
3, Rebuild source package
#dpkg-buildpackage -S
4, Build binary package
#cd .. && pbuilder packname_packversion-newdebianversion.dsc
You will find your packages in /var/cache/pbuilder/result

note: If you use pbuilder for first time, you must use "pbuilder create"
to create your base.tgz before the above command.
               
               
               
               
               

本文来自ChinaUnix博客，如果查看原文请点：http://blog.chinaunix.net/u1/52215/showart_1758051.html