<?xml version="1.0"?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
<!ENTITY svn-upgrade SYSTEM "svn-upgrade.xml">
<!ENTITY svn-inject SYSTEM  "svn-inject.xml">
<!ENTITY svn-buildpackage SYSTEM "svn-buildpackage.xml">
<!ENTITY svn-do SYSTEM  "svn-do.xml">
<!ENTITY uclean SYSTEM  "uclean.xml">
<!ENTITY dhfirstname "<firstname>Neil</firstname>">
<!ENTITY dhsurname "<surname>Williams</surname>">
<!ENTITY dhdate "<date>May 2009</date>">
<!ENTITY dhsection "<manvolnum>1</manvolnum>">
<!ENTITY dhemail "<email>codehelp@debian.org</email>">
<!ENTITY dhusername "Eduard Bloch">
<!ENTITY dhucpackage "<refentrytitle>svn-buildpackage</refentrytitle>">
<!ENTITY ucleanpackage "uclean">
<!ENTITY dopackage "svn-do">
<!ENTITY upgradepackage "svn-upgrade">
<!ENTITY injectpackage "svn-inject">
<!ENTITY dhpackage "svn-buildpackage">
<!ENTITY debian "<productname>Debian</productname>">
<!ENTITY gnu "<acronym>GNU</acronym>">
<!ENTITY gpl "&gnu; <acronym>GPL</acronym>">
]>
<book lang="en">
  <bookinfo>
    <title>svn-buildpackage - maintaining Debian packages with Subversion</title>
    <copyright>
      <year>2003-2007</year>
      <holder>Eduard Bloch</holder>
    </copyright>
    <copyright>
      <year>2009-2010</year>
      <holder>Neil Williams</holder>
    </copyright>
    <date>Tue Aug 31 21:01:26 BST 2010</date>
    <releaseinfo>Release: 0.8.2</releaseinfo>
    <legalnotice id="GPL">
      <title>The GNU GENERAL PUBLIC LICENSE Version 3, 29 June 2007</title>
      <para>This documentation is part of &dhpackage;.</para>
      <para>&dhpackage; 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 3 of the License, or
    (at your option) any later version.</para>
      <para>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.</para>
      <para>You should have received a copy of the GNU General Public License
    along with this program.  If not, see
    <ulink url="http://www.gnu.org/licenses/">http://www.gnu.org/licenses/</ulink>.
    </para>
    </legalnotice>
  </bookinfo>
  <chapter id="intro">
    <title>Introduction</title>
    <sect1 id="purpose">
      <title>Purpose</title>
      <para>This short document is only intended to give a short help in
      converting packages to Subversion management. It is primarily
      intended for developers not really familiar with Subversion or CVS
      management and/or converting from maintaining their packages using
      common tools (<command>dpkg-dev</command>, <command>devscripts</command>)
      only to version control system Subversion.
      </para>
    </sect1>
    <sect1 id="why">
      <title>Why a version control system?</title>
      <para>But the first question may be: why use a version control
      system at all? Look at how the source is handled by the Debian
      package. First, we have the pure upstream source, which is often
      maintained by another person. The upstream author has his own
      development line and releases the source in snapshots (often
      called releases or program versions).
      </para>
      <para>The Debian maintainer adds an own set of modifications,
      leading to an own version of the upstream package. The difference
      set between this two version finally ends in Debian's <filename>.diff.gz</filename>
      files, and this patchset is often appliable to future upstream
      versions in order to get the "Debian versions".
      </para>
      <para>So the obvious way to deal with source upgrades/changes is
      using local copies, patch, different patchutils and scripts to
      automate all this, e.g. <command>uupdate</command>. However, it often becomes nasty
      and uncomfortable and there is no way to undo changes that you
      may do by mistakes.
      </para>
      <para>At this point, the Subversion system can be used to simplify
      that work. It does the same things that you normaly would do
      by-hand but keeps it in an own archive (a repository). It stores
      the development lines of Upstream and Debian source, keeping them
      in different directories (different branches). The branches are
      wired internally (the VCS "knows" the history of the file and
      tracks the differences between the Upstream and Debian versions).
      When a new upstream version is installed, the differences between
      the old and new upstream versions and the Debian version are
      merged together.
      </para>
      <para>You can create snapshots of your Debian version ("tag" it)
      and switch back to a previous state, or see the changes done in
      the files. You can store when commiting the file to the repository
      or place custom tags on the files ("properties") serving various
      purposes.
      </para>
    </sect1>
    <sect1 id="features">
      <title>Features</title>
      <para><command>svn-buildpackage</command> and other scripts around
      it has been created to do the following things:
      </para>
      <itemizedlist>
        <listitem><para>Keep Debian package under revision control, which means
        storing different versions of files in a Subversion repository.
        </para></listitem>
        <listitem><para>Allow easy walking back trough time using <command>svn</command> command.
        </para></listitem>
        <listitem><para>Easy retrieval of past versions.
        </para></listitem>
        <listitem><para>Keep track of upstream source versions and modified
        Debian versions.
        </para></listitem>
        <listitem><para>Easy installation of new upstream versions, merging
        the Debian changes into it when needed (similar to the <command>uupdate</command>
        program).
        </para></listitem>
        <listitem><para>Automated package building in clean environment,
        notifying about uncommited changes.
        </para></listitem>
        <listitem><para>Create version tags when requested to do the final build
        and update changelog when needed.
        </para></listitem>
        <listitem><para>allow co-work of multiple Debian developers on the same
        project.
        </para></listitem>
        <listitem><para>Auto-configure the repository layout, making it easy to
        use by people without knowing much about Subversion usage (mostly
        you need only the <command>add</command>, <command>rm</command> and
        <command>mv</command> commands of <command>svn</command>).
        </para></listitem>
        <listitem><para>Allow to store only the Debian specific changes in the
        repository and merge them into the upstream source in the build
        area (which nicely completes build systems like
        <command>dpatch</command> or <command>dbs</command>).
        </para></listitem>
        <listitem><para>If wished, keep the upstream tarballs inside of the
        repository.
        </para></listitem>
      </itemizedlist>
    </sect1>
    <sect1 id="overview">
      <title>Contents overview</title>
      <para>There are currently three scripts provided by the
      <command>svn-buildpackage</command> package:
      </para>
      <itemizedlist>
        <listitem><para>
        <command>svn-inject</command>: script used to insert an existing
        Debian package into a Subversion repository, creating the
        repository layout as needed.
        </para></listitem>
        <listitem><para><command>svn-buildpackage</command>: exports the contents
        of the directory associated with the starting directory from the
        Subversion repository to the clean environment and build the
        package there.
        </para></listitem>
        <listitem><para><command>svn-upgrade</command>: similar to <command>uupdate</command>,
        upgrades the trunk to a new upstream version, preserving and
        merging Debian specific changes.
        </para></listitem>
      </itemizedlist>
    </sect1>
    <sect1 id="layouts">
    <title>Popular repository layouts</title>
    <para>There are different ways to store the packages in the
    repositories (or in multiple repositories at your choice).
    <command>svn-buildpackage</command> normally expects a directory
    structure similar to the one well described in the Subversion Book,
    which looks like:
    </para>
    <example id="hierarchy">
    <title>Directory hierarchy example.</title>
    <programlisting>
packageA/
   trunk/
   branches/
   branches/upstream
   tags/

projectB/
   trunk/
   branches/
   branches/developerFoo
   tags/
   </programlisting>
   </example>
   <para><filename>packageA</filename> above may be a typical upstream-based source package
   and a <filename>projectB</filename> may be a Debian native package with a separate branch
   created by developer Foo for his own experiments. See <ulink
   url="http://svnbook.red-bean.com/html-chunk/ch04s02.html">
   Subversion Book/Branches</ulink> for more details about using
   Subversion branches.
   </para>
   <para>Also note that Tags work quite differently to those in CVS.
   Subversion does not maintain magic tags associated with some files.
   Instead, it tracks the file state and moves, so Tagging something
   means creating a copy (inside of the Repository, harddisk-space
   efficient) of a certain version of the file set. So the Debian branch
   of the released package source is contained in
   <filename>trunk/</filename> and is tagged by copying (mirroring) the
   trunk tree to <filename>tags/DEBIAN-REVISION</filename>. The same
   happens for the upstream releases. In addition, the most recent
   upstream version is mirrored to
   <filename>branches/upstream/current</filename>. After few package
   upgrade cycles, the directory tree may look like:
   </para>
<example id="branches">
<title>Example branch directory hierarchy</title>
<programlisting>
# svn ls -R file:///home/user/svn-repo/dev/translucency
branches/
branches/upstream/
branches/upstream/0.5.9/
branches/upstream/0.5.9/AUTHORS
branches/upstream/0.5.9/COPYING
...
branches/upstream/0.6.0/
branches/upstream/0.6.0/AUTHORS
branches/upstream/0.6.0/COPYING
...
branches/upstream/current/
branches/upstream/current/AUTHORS
branches/upstream/current/COPYING
... same stuff as in 0.6.0 ...
tags/
tags/0.5.9-1/
...
tags/0.5.9-1/debian/
tags/0.5.9-1/debian/README.Debian
...
tags/0.6.0-1/
tags/0.6.0-1/AUTHORS
...
tags/0.6.0-1/debian/
tags/0.6.0-1/debian/README.Debian
tags/0.6.0-1/debian/changelog
...
trunk/
trunk/AUTHORS
trunk/COPYING
... trunk where 0.6.0-2 is beeing prepared ...
</programlisting>
</example>
<para>
<command>svn-buildpackage</command> also supports the second repository layout suggested in
the Subversion Book (function/package) but <command>svn-inject</command> prefers the one
documented above. Both <command>svn-buildpackage</command> and <command>svn-upgrade</command> should be able to
auto-detect the repository layout and the location of package files.
</para>
<para>
In theory, you do not have to follow that examples and place the <filename>trunk</filename>,
<filename>branches</filename> and <filename>tags</filename> directory on the locations you like more.
But <command>svn-buildpackage</command> and other scripts won't locate the files
automaticaly so you will need to edit the <filename>.svn/deb-layout</filename> file in your
working directory and set paths. See the old <ulink
url="file:///usr/share/doc/svn-buildpackage/CONFIG">abstract</ulink>
about how auto-detection works and the <ulink
url="file:///usr/share/doc/svn-buildpackage/examples/config.example">
config example</ulink>.
</para>
<para>
Finally, the working directory structure on your development system may
look like:
</para>
<example id="config-example">
<title>Example configuration</title>
<programlisting>
dev/ # base directory, may be under version control or not
dev/foo # trunk directories of various packages
dev/bar # contents correspond to trunk, see above
dev/tarballs # where "orig" tarballs are stored, may be under VC or not
dev/build-area # where the packages are exported temporarily and built
</programlisting>
</example>
</sect1>
  </chapter>
  <chapter id="start">
  <title>Getting started</title>
<para>Besides the packages that are installed by dependencies when you
install <command>svn-buildpackage</command>, you may need
<command>ssh</command> and the obligatory tool chain:
<command>dpkg-dev</command>, <command>build-essential</command> and
all the packages they pull into the system.
</para>

<sect1 id="quick">
<title>Quick guide</title>
<para>
Here is a quick guide for those who wish to build an existing package
using an existing, publically available SVN repository. To create own
repositories, skip this section and look for more details below.
</para>
<itemizedlist><listitem><para>
svn co &lt;svn://server/path/to/trunk&gt; package
</para></listitem><listitem><para>
mkdir tarballs
</para></listitem><listitem><para>
cp dir-where-you-keep-the-source/package_version.orig.tar.gz tarballs/
</para></listitem><para>
NOTE: you need the upstream source tarballs, stored under a usual 
<command>dpkg-source</command>-compatible filename in <filename>tarballs/</filename>
</para><listitem><para>
cd <replaceable>package</replaceable>
</para></listitem><listitem><para>
svn-buildpackage -us -uc -rfakeroot
</para></listitem></itemizedlist>
</sect1>

<sect1 id="basics">
<title>Basic svn usage</title>
<para>
You need only few commands to start using <command>svn</command> with <command>svn-buildpackage</command>
scripts. If you wish to learn more about it, read parts of the
<ulink url="http://svnbook.red-bean.com/html-chunk/">
Subversion Book</ulink>. The most used commands
are:
</para>
<itemizedlist>
<listitem><para>
<command>add</command> -- put new files unto the revision control.
</para></listitem>
<listitem><para><command>rm</command> -- remove the files from the repository.
</para></listitem>
<listitem><para><command>mv</command> -- move files around, leting revision
control system know about it.
</para></listitem>
<listitem><para><command>commit</command> -- commit your changes to the
repository.
</para></listitem>
<listitem><para><command>resolved</command> -- tell <command>svn</command> that you have
resolved a conflict.
</para></listitem>
<listitem><para><command>diff</command> -- creates a "<command>diff -u</command>" between two
versions, specified by file revision number or by date. See the
<command>diff --help</command> output.
</para></listitem>
<listitem><para><command>cat -r <replaceable>revision</replaceable></command> -- useful to browse in some
previous revision of the file.
</para></listitem>
</itemizedlist>
<para>
If you are familiar with CVS you will probably know almost all you need.
</para>
</sect1>

<sect1 id="svncreate">
<title>Creating Subversion repository</title>
<para>
The main Subversion repository is easily created with:
</para>
<example>
<title>Repository creation example.</title>
<programlisting>
$ svnadmin create <replaceable>repo-directory</replaceable>
</programlisting>
</example>
<para>
For our example, we choose the name <filename>svn-deb-repo</filename>
and put it in <filename>/home/<replaceable>user</replaceable></filename>.
</para>
<para>If you plan to keep many packages in the one repository including
upstream tarballs, consider to put it on a hard disk with much free space
and good performance (especially short disk access times) since the
repository will grow and the filesystem may become fragmented over time.
</para>
</sect1>

<sect1 id="multidev">
<title>Using by multiple developers</title>
<para>
Multiple developers with local access to the repository may share it
using a common group. To do so, create a new group and add all
developers to it. Run "chgrp -R sharedGroup repdir ; chmod -R g+s
repdir" for the shared group and the repository directory. Now,
on local access to this repository everybody will create files with the
appropriate group setting. However, the developers will need to set a
liberal umask before using <command>svn</command> (like "0022").
</para>
<para>
If somebody resists to do so, there is still a brute-force solution:
fix the permissions with a post-commit script. However, this is an
"unsound" solution and may lead to <emphasis>ALL KINDS OF PROBLEMS</emphasis>.
<emphasis>MAKE SURE THAT YOU ARE AWARE OF THE POSSIBLE CONSEQUENCES BEFORE
YOU OPEN THE PANDORA BOX</emphasis>. See <ulink
url="http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=240630">
Debian BTS</ulink> for details. When you damage your repository, don't
blame me and remember that there is "<command>svnadmin recover</command>".
</para>
<example>
<title>post-commit hook example</title>
<programlisting>
#!/bin/sh

# POST-COMMIT HOOK
# The following corrects the permissions of the repository files

REPOS="$1"
REV="$2"

chgrp -R sharedGroup $REPOS
# replace sharedGroup with your group
chmod -R g+r $REPOS
chmod -R g+w $REPOS
</programlisting>
</example>
</sect1>

<sect1 id="svn-d-o">
<title>SVN over SSH</title>
<para>
To run Subversion over SSH, you basically need a shell on the target
system and a subversion repository located there which is created
following the description above. The repository must be configured for
access by the system users of the remote system.
</para>
<para>
Assuming that your user name on the client system is the same as on the
server side, there is not much to configure. Just change the protocol
specification from <filename>file://</filename> to
<filename>svn+ssh://<replaceable>remoteusername</replaceable>@<replaceable>server-hostname</replaceable></filename> in all
examples showed in this manual.
</para>
<para>
Note that during <command>svn-buildpackage</command> tools actions a lot of SSH calls can be made
and so the user is asked for his login data. The regular method to deal with
that is using an SSH key authentication method together with
<command>ssh-agent</command> and <command>ssh-add</command>
to cache the passphrase in memory. Another approach, which also brings
a significant speed boost, is using a cached SSH connection. This can be done
with a new feature of OpenSSH (see <ulink
url="http://gcc.gnu.org/wiki/SSH%20connection%20caching">
GCC SSH connection caching howto</ulink>) or a third-party tool like
<command>fsh</command>.
</para>
<para>If you wish to use <command>fsh</command> over
<command>ssh</command> you could specify a custom transport method in
the subversion configuration. To do so, edit the file
<filename>~/.subversion/config</filename> and add the section
<filename>[tunnels]</filename> to it, following by your custom transport
definition. Example:
</para>
<example>
<title>Example of a custom ssh tunnel command.</title>
<programlisting>
# personal subversion config with custom ssh tunnel command
[tunnels]
# SSH account on svn.d.o
# compression is enabled in the ssh config
deb = fsh -l &lt;user&gt;
# SSH account for NQ intranet, set fix username
nq = ssh -C -l zomb
</programlisting>
</example>
<para>
You can use the new defined tunnels in a similar ways as described above
but replace <filename>svn+ssh</filename> with
<filename>svn+<replaceable>tunnelname</replaceable></filename>, so the final URL looks like:
</para>
<programlisting>
svn+deb://svn.debian.org/svn/<replaceable>myproject</replaceable>/<replaceable>ourpackage</replaceable>/trunk
</programlisting>
</sect1>

<sect1 id="anon">
<title>Anonymous access</title>
<para>
You can allow outsiders to have anonymous (read-only) access using the
<command>svnserve</command> program, as described in the Subversion documentation.
</para>
<para>
Another method is using HTTP/WebDAV with Apache2. More about a such
setup can be found in the Subversion Book and the <ulink
url="http://wiki.debian.org/SubversionApache2SSLHowto">
SubversionApache2SSL Howto</ulink>. <ulink
url="http://svn.debian.org/">svn.debian.org</ulink> is an example site
granting anonymous access to some selected projects hosted there.
</para>
</sect1>
</chapter>

  <chapter id="import">
  <title>Importing Debian packages</title>
<sect1 id="existing">
<title>Importing from existing source package files</title>
<para>
The <command>svn-inject</command> utility is intended to import already
packaged source packages into a new subdirectory of the repository,
creating the repository layout as needed. Normally, it takes two
arguments: the <filename>.dsc</filename> file of your package and the base URL of the
Subversion repository.
</para>
<example>
<title>svn-inject example</title>
<programlisting>
svn-inject translucency_*dsc file:///tmp/z
cp /tmp/translucency_0.6.0.orig.tar.gz /tmp/tarballs || true
mkdir -p translucency/branches/upstream
tar  -z -x -f /tmp/translucency_0.6.0.orig.tar.gz
mv * current
svn -q import -m"Installing original source version" translucency file:///tmp/z/translucency
svn -m Tagging upstream source version copy file:///tmp/z/translucency/branches/
upstream/current file:///tmp/z/translucency/branches/upstream/0.6.0 -q
svn -m Forking to Trunk copy file:///tmp/z/translucency/branches/upstream/current file:///tmp/z/translucency/trunk -q
dpkg-source -x /tmp/translucency_0.6.0-1.dsc
dpkg-source: extracting translucency in translucency-0.6.0
svn_load_dirs file:///tmp/z/translucency/trunk . *
...
Running /usr/bin/svn propset svn:executable  initscript
Running /usr/bin/svn propset svn:executable  debian/rules
Running /usr/bin/svn propset svn:executable  mounttest.sh
Running /usr/bin/svn propset svn:executable  mount.translucency
Running /usr/bin/svn propget svn:eol-style base.h
Running /usr/bin/svn propget svn:eol-style Makefile
Running /usr/bin/svn propget svn:eol-style translucency.8
Running /usr/bin/svn commit -m Load translucency-0.6.0 into translucency/trunk.

Running /usr/bin/svn update
Cleaning up /tmp/svn_load_dirs_jD7OenzVjI
Storing trunk copy in /tmp/translucency.
svn co file:///tmp/z/translucency/trunk /tmp/translucency -q
svn propset svn:executable 1 debian/rules -q
svn -m"Fixing debian/rules permissions" commit debian -q
Done! Removing tempdir.
Your working directory is /tmp/translucency - have fun!
</programlisting>
</example>
<para>
If you omit the URL, <command>svn-inject</command> will try to use the
URL of the current directory as base URL. I would not rely on this, however.
</para>
</sect1>

<sect1 id="merging">
<title>On-Build-Time merging</title>
<para>
A special feature of <command>svn-buildpackage</command> is so called
<emphasis>mergeWithUpstream</emphasis> mode. Many projects do not want
to keep the whole upstream source under revision control, eg. because
of the large amount of required disc space and process time. Sometimes
it makes sense to keep only the <filename>debian/</filename> directory
any maybe few other files under revision control.
</para>
<para>
The task of exporting the source from repository and adding it to the
upstream source before building becomes annoying after a little time.
But the <command>svn-buildpackage</command> tools automate most of
this work for you by switching to
<emphasis>mergeWithUpstream</emphasis> mode if a special flag has
been detected: the mergeWithUpstream (Subversion) property of the
<filename>debian</filename> directory. <command>svn-buildpackage</command>
will merge the trunk with upstream source on build time and
<command>svn-upgrade</command> will only update the changed files in
this case.
</para>
<para>
To enable this feature during the initial import of the source package,
simply add the <option>-o</option> switch to the
<command>svn-inject</command> call and it will prepare the source for
with <emphasis>mergeWithUpstream</emphasis> mode. This reduces
the set of files to those modified for Debian and set the
<emphasis>mergeWithUpstream</emphasis> property.
</para>
<para>
But what, if you decide to switch to mergeWithUpstream-mode after the
package has been injected? To do this, checkout the whole repository,
remove the files not changed in the Debian package from both upstream
source and Debian branch (<command>svn rm</command>) and set the
<emphasis>mergeWithUpstream</emphasis> property on
<filename>debian</filename> in the <filename>trunk</filename> directory
with:
<programlisting>svn propset mergeWithUpstream 1 debian</programlisting>
</para>
<para>If you actually decide to stop using the
<emphasis>mergeWithUpstream</emphasis> mode, unset the
<emphasis>mergeWithUpstream</emphasis> property as follows:
<programlisting>svn propdel mergeWithUpstream debian/</programlisting>
</para>
<para>If you don't want to store the upstream sources of all your packages
in the repository, you can pass the <option>--no-branches</option>
switch to <command>svn-inject</command>, which will prevent
<command>svn-inject</command> from creating a <filename>branches</filename>
subdirectory.
</para>
<sect2>
<title><command>dpkg-source</command> format 3.0 support</title>
<para><command>svn-buildpackage</command> can build packages
using source format 3.0, including using
<filename>../tarballs/foo_1.2.3-1.orig.tar.bz2</filename> in
<emphasis>mergeWithUpstream</emphasis> mode.
Ensure that <filename>debian/source/format</filename> exists and has
been added to the local Subversion working copy.
</para>
<para>If <filename>debian/source/format</filename> exists and contains
<emphasis>3.0 *</emphasis>, <command>svn-buildpackage</command> checks for
a <filename>.orig.tar.bz2</filename> in the <filename>tarballs</filename>
directory and uses that for the subsequent build.
</para>
<example>
<title>checking source formats with <command>dpkg-source</command></title>
<para><command>dpkg-source</command> <option>--print-format</option>
needs a little help to understand common layouts used with subversion.
The command needs two directories - the current working directory is used
to find the original tarball and the specified directory is used to locate
<filename>./debian/changelog</filename>. Change to the directory containing
the tarball before running <command>dpkg-source</command>
<option>--print-format</option>:
</para>
<programlisting>
$ svn mkdir debian/source
$ echo "3.0 (quilt)" > debian/source/format
$ svn add debian/source/format
$ pushd ../tarballs/
$ dpkg-source --print-format ../trunk/
3.0 (quilt)
$ popd
</programlisting>
</example>
</sect2>
<sect2>
<title>Preparing patches in <command>dpkg-source</command> 3.0 packages</title>
<para>When using <option>3.0 (quilt)</option> and <option>mergeWithUpstream</option>,
use <command>svn-do</command> to unpack the upstream source
and then simply edit or patch the files necessary for the first patch.
Then get <command>dpkg-source</command> to prepare the patches for you:
</para>
<example>
<title>Letting <command>dpkg-source</command> prepare patches for <option>3.0 (quilt)</option></title>
$ dpkg-buildpackage -uc -us -S
</example>
<para>Now use a serviceable name for the patch and change that name
in the <filename>series</filename> file, exit the <command>svn-do</command> subshell for
the results to be copied back into <filename>trunk</filename>. Repeat
for subsequent patches.
</para>
</sect2>
</sect1>

<sect1>
<title>Using <command>svn-buildpackage</command> with native packages</title>
<para>A native package is designed to work with Debian rather than
general GNU/Linux distributions, many depend directly on specific
Debian behaviour or other Debian native tools. <emphasis>svn-buildpackage</emphasis>
is one such native package.
</para>
<para>With a native package, the contents of the <filename>debian/</filename>
directory are included in the source tarball (which uses a plain
<filename>.tar.gz</filename> suffix not the <filename>.orig.tar.gz</filename>
suffix) and no <filename>.diff.gz</filename> is generated.
</para>
<para>The principal marker for a native package is the Debian version
string. An upstream package uses:
</para>
<programlisting>
 foo (0.1.2-3)
</programlisting>
<para>A native package uses:</para>
<programlisting>
 foo (0.1.2)
</programlisting>
<sect2>
<title>Compiled native packages</title>
<para>Some native packages are compiled from source code and a lot of
these packages use autotools like <filename>./configure</filename>,
<command>autoreconf</command> and <command>make dist</command>. Such
packages can use autotools support to generate a typical GNU or autotools
style tarball with support for <emphasis>EXTRA_DIST</emphasis> and
similar rules in <filename>Makefile.am</filename>. This allows the maintainers
to not need to keep generated files (<filename>configure</filename>,
<filename>aclocal.m4</filename>, <filename>ltmain.sh</filename> and
<filename>libtool</filename>) in the subversion repository. With this
support, the package can directly control which files are included into
the source for the native package.
</para>
<para>To build such packages with <command>svn-buildpackage</command>,
<emphasis>mergeWithUpstream</emphasis> can be used even if the Debian
version string indicates a native package. The upstream tarball is the
one created by the <command>make dist</command> target and the maintainer
can choose how to make that tarball available to
<command>svn-buildpackage</command>:
</para>
<example>
<title>Using a native tarball and mergeWithUpstream</title>
<para>Makefile.am</para>
<programlisting>
all-local: Makefile
	ln -sf $(PACKAGE)-$(VERSION).tar.gz $(PACKAGE)_$(VERSION).orig.tar.gz
</programlisting>
<para>(Yes, this is an artefact of using mergeWithUpstream.
The <filename>.orig.tar.gz</filename> is not actually used - the Debian version string overrides
the merge property.)</para>
</example>
<para>SVN properties:</para>
<programlisting>
$ svn proplist ./debian/
Properties on 'debian':
  mergeWithUpstream
</programlisting>
<example>
<title>Output of using mergeWithUpstream inside a native package</title>
<para>The tarball generated by <command>make dist</command> is
located using the <emphasis>origDir</emphasis> property, in this
example, set to the top level package directory where
<command>make dist</command> would normally create it and where the
symlink is also created, as above.</para>
<para><command>svn-buildpackage</command> output:</para>
<para>(using langupdate as the example package)</para>
<programlisting>
$ svn-buildpackage -us -uc
	origDir: ./
Complete layout information:
	buildArea=/opt/working/emdebian/host/trunk/langupdate/build-area
	origDir=./
	tagsDir=/opt/working/emdebian/host/trunk/langupdate/tags
	tagsUrl=svn+ssh://codehelp@buildd.emdebian.org/var/emdebian/svn/current/host/trunk/langupdate/tags
	trunkDir=/opt/working/emdebian/host/trunk/langupdate/trunk
	trunkUrl=svn+ssh://codehelp@buildd.emdebian.org/var/emdebian/svn/current/host/trunk/langupdate/trunk
mergeWithUpstream mode detected, looking for .//langupdate_0.1.1.orig.tar.gz
I: mergeWithUpstream property set, looking for upstream source tarball...
 tar --no-same-owner --no-same-permissions --extract --gzip --file /opt/working/emdebian/host/trunk/langupdate/trunk/langupdate-0.1.1.tar.gz --directory &lt;1 more argument&gt;
 mv /opt/working/emdebian/host/trunk/langupdate/build-area/tmp-0.15173904069616/langupdate-0.1.1 /opt/working/emdebian/host/trunk/langupdate/build-area/langupdate-0.1.1
svn --force export /opt/working/emdebian/host/trunk/langupdate/trunk /opt/working/emdebian/host/trunk/langupdate/build-area/langupdate-0.1.1
Export complete.
</programlisting>
<para>Note how the tarball (created by <command>make dist</command> and
located by <emphasis>mergeWithUpstream</emphasis> due to the symlink)
is unpacked and then the exported SVN is applied on top. This allows
maintainers to test local changes using <option>--svn-ignore</option>.
</para>
</example>
</sect2>
<sect2>
<title>Native packages not using autotools</title>
<subtitle>The useNativeDist property.</subtitle>
<para>When <command>make dist</command> is not available, there are still
situations where generated files may need to be included into the source
tarball of the native package. <command>svn-buildpackage</command> supports
the <emphasis>useNativeDist</emphasis> SVN property (applied to the
<filename>./debian/</filename> directory) which allows for customised
<command>make native-dist</command> target to be run immediately
after the svn export.
</para>
<example>
<title>The useNativeDist property.</title>
<para><command>svn-buildpackage</command> uses this feature to include
the POT file to aid translators. The custom <command>make</command> rule needs to be defined
in the top level <filename>Makefile</filename>:
</para>
<programlisting>
# adds the POT file to the source tarball
native-dist: Makefile
	po4a-build --pot-only
</programlisting>
</example>
<para>The <emphasis>native-dist</emphasis> target needs to be idempotent
and able to run straight from the SVN export. Any changes made by
running the target will be directly reflected in the source tarball.
Ensure that no files are removed that would prevent the package being
built as a normal Debian package, using only the resulting source
package. (e.g. <command>cd</command> into the <filename>build-area</filename>,
unpacking the <filename>.dsc</filename> with
<command>dpkg-source -x</command> and rebuild the package, then
remove the test directory.)
</para>
<para>The net result is that the resulting source tarball includes the
<filename>po/svn-buildpackage.pot</filename> generated by the
<emphasis>make native-dist</emphasis> target without needing to
add the generated POT file to SVN (and requiring repeated commits each
time the POT file is timestamped).
</para>
</sect2>
</sect1>

<!--sect1>
<title>Importing directories</title>
<para>
Importing directories is a special case and I do not recommend using
this feature. The implementation may be buggy and wreak random havoc.
You have been warned!
</para>
<para>
You can specify source directories as input for svn-inject and
svn-upgrade. This may be useful for two things:
</para>
<itemizedlist>
   <listitem>
   Inserting pristine upstream source into the repository before running
   dh_make. You may wish to do so if you want to use Subversion from the
   beginning. If the version string cannot be extracted from the directory
   name, you will have to specify it manually with the
   <strong>-V</strong> option.
   </listitem>
   <listitem>tracking a local version of a Debian package with custom
   changes if you are not the maintainer. So you can inject and upgrade
   from the debianized package source (extracted with "dpkg-source -x")
   but keep your personal changes in the <filename>trunk</filename>.
   </listitem>
</itemizedlist>
</sect1-->
</chapter>
  <chapter id="tasks">
  <title>Common tasks</title>

<sect1 id="checkout">
<title>Checkout</title>
<para><command>svn-inject</command> will do the initial checkout for you.
If you need another working copy, run
</para>
<example>
<title><command>svn-inject</command> initial checkout</title>
<programlisting>
svn co <replaceable>protocol</replaceable>://<replaceable>repository-base-url</replaceable>/<replaceable>yourpackage</replaceable>
</programlisting>
</example>
</sect1>

<sect1 id="build">
<title>Building the package</title>
<para>Change to your <filename>trunk</filename> directory and run:
</para>
<example>
<title><command>svn-buildpackage</command></title>
<programlisting>
$ svn-buildpackage -us -uc -rfakeroot
</programlisting>
</example>
<para>You may recognise the options above -- they are passed directly to
the build command (<command>dpkg-buildpackage</command> by default).
Normally, the build is done in another directory (exporting the source
with <computeroutput>cp-la-like</computeroutput> method). If you want
the resulting packages to be placed in the directory above, use the
<option>--svn-move</option> option. To run Lintian after the build,
use <option>--svn-lintian</option> option. More options are
described in the <link linkend="sbman">manpage</link>.
</para>
<para>To build in a chroot using <command>pdebuild</command>, use:
</para>
<example>
<title>pdebuild example</title>
<programlisting>
svn-buildpackage --svn-builder pdebuild
</programlisting>
</example>
<para>For frequently used commands, use an alias in your
<filename>~/.bashrc</filename> file:
</para>
<example>
<title>Useful aliases</title>
<programlisting>
alias svn-bp='svn-buildpackage -rfakeroot -D --svn-noautodch --svn-builder debuild'
alias svn-bpi='svn-buildpackage -rfakeroot -D --svn-noautodch --svn-builder debuild --svn-ignore-new'
alias svn-bpir='svn-buildpackage -us -uc -rfakeroot -D --svn-noautodch --svn-builder debuild --svn-ignore-new --svn-rm-prev-dir'
alias svn-bpr='svn-buildpackage -us -uc -rfakeroot -D --svn-noautodch --svn-builder debuild --svn-rm-prev-dir'
alias svn-pbp='svn-buildpackage --svn-noautodch --svn-builder pdebuild'
</programlisting>
</example>
</sect1>

<sect1 id="handlesource">
<title>Working with source</title>
<para>Every time when you add or modify something,
<command>svn-buildpackage</command> won't let you proceed unless suspicious
files are in the clean state (unless you use the
<option>--svn-ignore</option> switch).  You use the commands described
in &quot;<link linkend="basics">basic svn usage</link>&quot; to register
the new files (or move or delete the old ones) and commit the changes to
the repository.
</para>
</sect1>

<sect1 id="upstream">
<title>Handling new upstream versions</title>
<para>
Upgrading with new upstream version normally happens in two steps:
</para>
<itemizedlist><listitem><para>
the <filename>current</filename> tree in the upstream branch is upgraded
with the source from the new upstream package (the old version is kept in
repository in <filename>branches/upstream/<replaceable>oldVersion</replaceable></filename>).
</para></listitem><listitem><para>
the version in <filename>trunk/</filename> becomes upgraded by merging
the changes between the upstream versions into the
<filename>trunk/</filename> directory.
</para></listitem></itemizedlist>
<para>
The script <command>svn-upgrade</command> (formerly
<command>svn-uupdate</command>) does both things for you and also creates
a new changelog entry. The first step is done internally by using a third
party script (<command>svn_load_dirs</command>, see Subversion book for
documentation), the second step is done with the <command>merge</command>
command of <command>svn</command>. Just run
<command>svn-upgrade</command> from you local working directory
(which corresponds the <filename>trunk/</filename> checkout product).
</para>
<para>After running <command>svn-upgrade</command> some files may be
in conflicting state. This is naturally happens if you have modified some
files in the upstream package and now upstream did something similar on
the same positions so <command>svn merge</command> was confused.
</para>
<para>When <command>svn-upgrade</command> complains about files in
conflicting state, fix them manually. When done, use the
<command>svn resolved</command> command to mark them as clean and
<command>svn commit</command> to update the repository.
</para>
</sect1>

<sect1 id="tagging">
<title>Finalizing the Revision</title>
<para>When you are ready to upload a new revision of your package,
everything builds fine, the changelog is cleaned up and the package is
tested, you can do the final build and tag the end version. To do so,
add <option>--svn-tag</option> switch and after the package is built,
it will be tagged (by creating a copy of the <filename>trunk/</filename>
directory as said above).
</para>
</sect1>
</chapter>

  <chapter id="reference">
  <title>Command reference</title>
    &svn-buildpackage;
    &svn-inject;
    &svn-upgrade;
    &svn-do;
    &uclean;
</chapter>

  <chapter id="misc">
  <title>Further documentation</title>
<sect1>
<title>Various links</title>

<itemizedlist>
<listitem><para>Subversion Homepage:
<ulink url="http://subversion.tigris.org/">http://subversion.tigris.org</ulink>
</para></listitem>
<listitem><para>The Subversion Book:
<ulink url="http://svnbook.red-bean.com/">http://svnbook.red-bean.com/</ulink>
</para></listitem>
<listitem><para>Subversion vs. CVS and others:
<ulink url="http://better-scm.berlios.de/">http://better-scm.berlios.de/</ulink>
</para></listitem>
</itemizedlist>
</sect1>

<sect1 id="copyright">
<title>Copyright</title>
<para>
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.
</para>
<para>
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.
</para>
<para>
A copy of the GNU General Public License is available as <ulink
url="file:///usr/share/common-licenses/GPL">
/usr/share/common-licenses/GPL</ulink>
in the Debian GNU/Linux distribution or on the World Wide Web at
<ulink url="http://www.gnu.org/copyleft/gpl.html">
http://www.gnu.org/copyleft/gpl.html</ulink>.
You can also obtain it by
writing to the Free Software Foundation, Inc., 59 Temple Place, Suite
330, Boston, MA 02111-1307, USA.
</para>
</sect1>
</chapter>
</book>