dpatch - Debian Patch System
============================


0. What is it?
--------------

It is an "apply patches" system, what else? :)

dpatch does not need a separate tarball for upstream source like dbs
does. It all happens in "normal" unpacked source. So it is simple to
use and needs nearly no re-order of your source tree.

A subdirectory debian/patches is used to store the patches you want to
apply at build time.

1. How to use it
----------------

Build-Depend on dpatch. If you use the architecture specific 00list
files (see below) the Build-Depends needs to be versioned for dpatch
(>= 1.11).

Include /usr/share/dpatch/dpatch.make in your debian/rules file. This
gives you the make targets `patch`', `patch-stamp' and `unpatch'. (No,
don't copy & paste the targets to your debian/rules file, just a simple
include line is enough.)

Next, have the `clean' target depend on `unpatch'.

Also, set the make variable PACKAGE to the name of your package
(or to the name of the source package in a multiple-binary package).
This is used only for cosmetic stuff in the patch-stamp file.

For the patching itself, you have two targets to choose from;
`patch-stamp' and `patch'. Choose `patch-stamp' if you use stamp files
in your Makefile (ie: build-stamp). If you don't, and instead have the
`build' target run each time (relying on upstream's Makefiles to rebuild
anything that's out-of-date or not, as the case may be), use the `patch'
target, which is phony.

Look into /usr/share/doc/dpatch/examples/ for example rules files. Or
look into the source of cdrtools or sam packages for "real world"
examples.

1.a Using .PHONY (or not)
-------------------------

What you do now depends on what you like most/what your package needs.
There are 2 ways:
- You can add build, patch and unpatch to your .PHONY line. Then they are no
  real targets and always re-run. Use that if you want to let Upstream
  Makefiles decide if there is something to do.
- You can use stamp-files to let the debian/rules make decide if there
  is the need to re-run the target. For that you create a new target
  called build-stamp, create a empty stamp file at the end of the
  build and let the real build target depend on it. (Dont forget to
  delete the stamp file in your clean target). That way your
  debian/rules decides if a target needs to be rebuilt. Ah, and you
  should better let build-stamp (or whatever target runs first, before
  configuring and building the package - it could even be
  config.status) depend on patch-stamp rather than patch or it would
  rerun patch (and hence build) because "patch" is phony and always
  considered out-of-date.

For examples look at the difference between sample.rules and
sample.rules2 (well, the other difference, not the one with|without
debhelper :) ).


2. The patches
--------------

The files in debian/patches are called patches, but dpatch really
doesn't care if it is a patch or some other thing. A "patchfile" needs
to follow these two points to work:
 - It needs to be executable (this is taken care of by the patch
   target, so you don't have to worry about it)
 - It needs to understand -patch and -unpatch.
   -patch should do the changes to the source needed to get it working,
    whatever that maybe.
   -unpatch should undo these changes in conformance with Debian
    Policy.
Everything else is up to the user.

What follows is an example of a dpatch file which is a shell-script
(and the most-used form of a dpatch file):

#! /bin/sh -e
## XX_PATCHNAME.dpatch by YOUR NAME <YOUR EMAIL>
##
## All lines beginning with `## DP:' are a description of the patch.
## DP: No description.

[ -f debian/patches/00patch-opts ] && . debian/patches/00patch-opts
patch_opts="${patch_opts:--f --no-backup-if-mismatch ${2:+-d $2}}"

if [ $# -lt 1 ]; then
    echo >&2 "`basename $0`: script expects -patch|-unpatch as argument"
    exit 1
fi
case "$1" in
       -patch) patch $patch_opts -p1 < $0;;
       -unpatch) patch $patch_opts -p1 -R < $0;;
	*)
		echo >&2 "`basename $0`: script expects -patch|-unpatch as argument"
		exit 1;;
esac

exit 0
@DPATCH@

The patch simply follows this header. Simple, isn't it?

Note that, without the @DPATCH@ tag, dpatch-edit-patch will not preserve the
header. It will instead substitute the header from debian/patches/00template,
if such exists. Failing that, it will use its hardcoded default.

3. Defining patches to apply
----------------------------

In the debian/patches subdir you have a file called 00list. This lists
all patches that should be applied, in order. To disable a patch,
simply remove its entry from this file.

The format of 00list should be one patch listed per line, comments
allowed. Each line starting with a hash (`#') is treated as a comment
- ignored.

The .dpatch extension of the filename should not be included. So if
you have a dpatch with the filename `24_upstream_setuid_fix.dpatch',
it should be listed in 00list as `24_upstream_setuid_fix'. If you do
include it, you must build-depend on dpatch (>= 1.19).

3a. Filename syntax
-------------------

The filename of a patch should be XX_name.dpatch where XX is a number
(priority of patch), name is something to give a short hint what the
patch does and, .dpatch is just an extension. However, this is only a
recommendation, in reality you can name your patches to your liking,
only the .dpatch extension is really required.

3a. Different Architectures for patches
--------------------------------------

Since version 1.7 of dpatch it is possible to apply patches only if
the source is built on a special Architecture. For this you create a
file named 00list.$ARCH (where $ARCH is replaced by the Architecture
you want the patch, eg. hppa, i386 or similar) and list the patch only
in this file.  dpatch magically applies your patch if you are building
on a matching $ARCH, everywhere else it is ignored.

4. Order of patches
-------------------

The order of patches is determined by the order they are listed in
00list and 00list.$ARCH. But please be aware that the architecture
independent and dependent patch lists (00list and 00list.$ARCH) are
NOT munged together, arch-specific patches will be applied after
arch-independent ones.

5. Another way to defines patches to apply
------------------------------------------

If you don't like 00list files you are free to export the variable
PATCHLIST from your debian/rules. If this variable is set dpatch will
not look for 00list files in debian/patches, it simply uses files
defined here.  Watch out for the dpatch-* shell utilities, though.
They don't all respect PATCHLIST and always require a 00list file.

Your patches still need to be in debian/patches, the .dpatch extension
and the -patch|-unpatch params are still necessary, but how you define
PATCHLIST is up to you.

By default it contains every entry from 00list and 00list.$ARCH,
unsorted, as they are listed in those two files, one after another.

6. Tools made for dpatch
------------------------

6a. dpatch-edit-patch
---------------------

Sometimes one wants to edit patches, or to create new ones. To ease this
task, dpatch-edit-patch(1) was written.

Run dpatch-edit-patch from the toplevel directory of your unpacked
source tree, as such:

    $ dpatch-edit-patch <patchname> [basepatch]

<patchname> is the patch you wish to edit or create, as it would be
listed in 00list. [basepatch] is an optional parameter, and only used
when creating a new patch; if this is the case, all patches up to and
including [basepatch] will be applied to source trees. Presumably, the
patch you create will be added to 00list in the position immediately
following that of [basepatch].

If you're editing an existing patch, the source directories will have
all patches up to and including <patchname> applied.

Speaking of working directories, dpatch-edit-patch first runs
'debian/rules clean', in your source directory, then apply what patches
need to be applied, then copies the source directory to a working
directory.

Once the working directory has been prepared, dpatch-edit-patch spawns
an interactive shell for your use. Edit your files, and exit the shell -
after the shell has exited, dpatch-edit-patch will update your patch (or
create it if it's a new one).

Should you wish to abort dpatch-edit-patch from that interactive
subshell, exit the shell with an exit value of 230. In most (all?)
shells, this can be accomplished by exiting the shell with 'exit 230'.

6b. dpatch-list-patch
---------------------

This one, written by Junichi Uekawa <dancer@debian.org>, simply lists
the available patches with their comments from debian/patches.
Simply run it in your source tree and have fun. :)

6c. dpatch-convert-diffgz
-------------------------

Another one written by Junichi Uekawa <dancer@debian.org>, which tries
to get a .dpatch file from the Debian .diff.gz file. Before you run
this you have to prepare your debian/rules as described in section 1.

7. dpatch development
---------------------

dpatch development is happening at alioth, see
https://alioth.debian.org/projects/dpatch/

Read also README.arch for how the get the actual current version.

If you have a bug report, or feature request, and want to submit code,
look there first.

Joerg Jaspert <joerg@debian.org>
