<refentry id="sbman">
      <refentryinfo>
        <address>
          <email>blade@debian.org</email>
          </address>
        <address>
          &dhemail;
        </address>
        <author>
          <firstname>Eduard</firstname>
          <surname>Bloch</surname>
          <contrib>This manual page was written by Eduard Bloch in roff.
          </contrib>
        </author>
        <author>
          <firstname>Goneri</firstname>
          <surname>Le Bouder</surname>
          <contrib>Converted manpages to SGML.</contrib>
        </author>
        <author>
          &dhfirstname;
          &dhsurname;
          <contrib>Converted manpages to DocBook XML and current Debian maintainer
          </contrib>
        </author>
        <copyright>
          <year>2009</year>
          <holder>&dhusername;</holder>
        </copyright>
        &dhdate;
      </refentryinfo>
      <refmeta>
    &dhucpackage;

    &dhsection;
  </refmeta>
      <refnamediv>
        <refname>&dhpackage;</refname>
        <refpurpose>build Debian packages from SVN repository</refpurpose>
      </refnamediv>
      <refsynopsisdiv>
        <cmdsynopsis>
          <command>&dhpackage;</command>
          <arg>[ <replaceable>OPTIONS</replaceable>... ]
            [ <replaceable>OPTIONS</replaceable> for
              <command>dpkg-buildpackage</command> ]
          </arg>
        </cmdsynopsis>
      </refsynopsisdiv>
      <refsect1>
        <title>DESCRIPTION</title>
        <para>Builds a Debian package from a Subversion repository. The source code
 repository must be in the format created by
      <command>svn-inject</command>, and this script must be executed from the
      working directory (<filename>trunk/<replaceable>package</replaceable></filename>).
      </para>
      <para>By default, the working directory is used as the main source directory
      (assuming the whole upstream source is being stored in the repository).
      The alternative is so called "merge mode". With this method, only the
      <filename>debian</filename> directory (and maybe some other modified files) are stored in
      the repository.  At build time, the contents of the svn trunk are
      copied to the extracted tarball contents (and can overwrite parts of
      it). To choose this working model, set the <command>svn</command> property
      <emphasis>mergeWithUpstream</emphasis> on the <filename>debian</filename> directory
      </para>
        <programlisting>
$ svn propset mergeWithUpstream 1 debian
      </programlisting>
      <para><emphasis>mergeWithUpstream</emphasis> requires that the build
      system can prepare a tarball, typically using <command>make dist</command>
      and autotools. All upstream packages will have some form of tarball
      creation support and native packages that use autotools or which have
      internal tarball support can use <emphasis>mergeWithUpstream</emphasis>
      to handle generated files that are needed to build the package but
      are not present in SVN. See the HOWTO guide for examples of how this
      can be done. Native packages that do not use autotools and do not
      have internal tarball support can still add generated files to the
      source package tarball using the <emphasis>useNativeDist</emphasis>
      make target in the top level <filename>Makefile</filename>. This
      custom target must be idempotent and only modify / generate the
      desired files using only the exported SVN source and build
      dependencies. To allow <command>svn-buildpackage</command> to
      use an <command>make native-dist</command> target in your top level
      <filename>Makefile</filename>, set the  
      <emphasis>useNativeDist</emphasis> property on the
      <filename>./debian/</filename> directory:
      </para>
        <programlisting>
$ svn propset useNativeDist 1 debian
      </programlisting>
        <para>
      The default behaviour of <command>svn-buildpackage</command> is
      as follows:
      </para>
        <para>Check the working directory, complain on uncommited files (also
      see <option>--svn-ignore-new</option>)
      </para>
        <para>Copy the orig tarball to the build area if necessary (also
        see <option>--svn-no-links</option>)
        </para>
        <para>Extract the tarball (in merge mode) or export the svn work
        directory to the build directory (also see below and
        <option>--svn-no-links</option>)
        </para>
        <para>Build with <command>dpkg-buildpackage</command> (also see
        <option>--svn-builder</option>,
        <option>--svn-lintian</option>, etc.)
        </para>
        <para>Create a changelog entry for the future version</para>
      </refsect1>
      <refsect1>
        <title>OPTIONS</title>
        <para><command>&dhpackage;</command> accepts the following options
        on the command-line:
        </para>
        <variablelist>
          <varlistentry>
            <term>
              <option>--svn-builder=COMMAND</option>
            </term>
            <listitem>
              <para>Specifies  alternative  build  command instead of
              <command>dpkg-buildpackage</command>, eg.
              <command>debuild</command>, <command>pdebuild</command>,
              etc. Every parameter that <command>svn-buildpackage</command>
              doesn't know (<emphasis>--svn-*</emphasis>) is passed to
              <option>COMMAND</option>. There is no difference between the
              command line and config file parameters . They are used at
              the same time.
              </para>
              <para>WARNING: shell quotation rules do not completely apply
              here, better use wrappers for complex constructs. Using this
              option may break <emphasis>--svn-lintian</emphasis> and
              <emphasis>--svn-move</emphasis> functionality. Some functions
              may be disabled when a custom build command is used because
              the output file location is not predictable.</para>
              <para>Default: use <command>dpkg-buildpackage</command>.</para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term>
               <option>--svn-ignore-new</option> |
               <option>--svn-ignore</option>
            </term>
            <listitem>
              <para>Don't stop on svn conflicts or new/changed files.
              To set this behaviour for single files set the
              <userinput>deb:ignoreM</userinput> property to 1 on them.
              Also see documentation of the svn:ignore property in the
              SVN book.
              </para>
              <para>Default: Stop on conflicts or new/changed files.</para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term>
              <option>--svn-dont-clean</option>
            </term>
            <listitem>
              <para>Don't run debian/rules clean.</para>
              <para>Default: clean first</para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term>
              <option>--svn-no-links</option>
            </term>
            <listitem>
              <para>Don't use file links but try to export or do hard copies
              of the working directory. This is useful if your package
              fails to build because some files, empty directories,
              broken links, ...  cannot not be transported with in the
              default link-copy mode.
              </para>
              <para>Default: use links where possible.</para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term>
              <option>--svn-dont-purge</option>
            </term>
            <listitem>
              <para>Don't remove the build directory when the build is
              done.</para>
              <para>Default: remove after successful build.
              </para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term>
              <option>--svn-reuse</option>
            </term>
            <listitem>
              <para>If possible, reuse an existing build directory in
              subsequent builds. The build directory is not purged after
              the build, it is not renamed when a build starts and the
              files are just copied over into it. Useful in
              <emphasis>mergeWithUpstream</emphasis> mode with large
              packages.
              </para>
              <para>Default: build directory is removed.</para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term>
              <option>--svn-rm-prev-dir</option>
            </term>
            <listitem>
              <para>If a previous build directory is found, remove it
              before building instead of renaming it. if
              <emphasis>--svn-reuse</emphasis> is also given in the same
              line, the reuse behaviour occurs.
              </para>
              <para>Default: rename old directories with a
              '<option>obsolete</option>' suffix.</para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term>
              <option>--svn-export</option>
            </term>
            <listitem>
              <para>Just export the working directory and do necessary
              code merge operations, then exit.
              </para>
              <para>Default: Off.</para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term>
              <option>--svn-tag</option>
            </term>
            <listitem>
              <para>Final build: Tag, export, build cleanly &amp; make
              new changelog entry.
              </para>
              <para>Default: Off.</para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term>
              <option>--svn-tag-only</option> |
              <option>--svn-only-tag</option>
            </term>
            <listitem>
              <para>Don't build the package, do only the tag copy.</para>
              <para>Default: Off.</para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term>
              <option>--svn-retag</option>
            </term>
            <listitem>
              <para>If an existing target directory has been found while
              trying to create the tag copy, remove the target directory first.
              </para>
              <para>Default: Off.</para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term>
              <option>--svn-noautodch</option>
            </term>
            <listitem>
              <para>No new Debian changelog entry is added automatically.
              </para>
              <para>Default: A new <emphasis>UNRELEASED</emphasis>
              changelog entry is set via <command>dch</command>.
              </para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term>
              <option>--svn-lintian</option>
            </term>
            <listitem>
              <para>Run lintian on the resulting changes file when done.
              </para>
              <para>Default: Off.</para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term>
              <option>--svn-move</option>
            </term>
            <listitem>
              <para>When done, move the created files (as listed in
              <filename>.changes</filename>) to the parent directory,
              relative to the one where <command>svn-buildpackage</command> was started.
              </para>
              <para>Default: Off.</para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term>
              <option>--svn-move-to=...</option>
            </term>
            <listitem>
              <para>Specifies the target directory to which to move the
              generated files.
              </para>
              <para>Default: Off. (Files are left where the build command
              puts them.)</para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term>
              <option>--svn-pkg=packagename</option>
            </term>
            <listitem>
              <para>Overrides the detected package name. Use with caution
              since it could be set too late during the processing (eg.
              still have the old value when expanding shell variables).
              </para>
              <para>Default: Off.</para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term>
              <option>--svn-arch=ARCH</option>
            </term>
            <listitem>
              <para>Allows specifying the build architecture (e.g.
              i386 build on an amd64 machine).
              </para>
              <para>Default: Off.</para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term>
              <option>--svn-override=var=value,anothervar=value</option>
            </term>
            <listitem>
              <para>Overrides any config variable that has been
              autodetected or found in <emphasis>.svn/deb-layout</emphasis>.
              </para>
              <para>Default: Off.</para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term>
              <option>--svn-prebuild</option> |
              <option>--svn-postbuild</option> |
              <option>--svn-pretag</option> |
              <option>--svn-posttag</option>
            </term>
            <listitem>
              <para>Commands (hooks) to be executed before/after the build/tag
             command invocations, e.g. to download the orig tarballs from the
             archive. Shell code can be emdded here though it is not
             recommended. Various helping variables are available in the
             environment, see ENVIRONMENT VARIABLES below for detailed explanation.
             </para>
             <para>Please note that the prebuild and postbuild hooks
             replace the normal prebuild and postbuild actions of
             <command>svn-buildpackage</command>. For prebuild, this means
             that the build dependencies will not be checked. For postbuild,
             this means that the resulting files won't be moved, and lintian
             will not be run.
             </para>
              <para>Defaults: Off.</para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term>
              <option>--svn-noninteractive</option>
            </term>
            <listitem>
              <para>With this parameter <command>svn-buildpackage</command> will not interact
              with the user.
              </para>
              <para>Default: Off.</para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term>
              <option>--svn-savecfg</option>
            </term>
            <listitem>
              <para>By default, <command>svn-buildpackage</command> used to create
              <filename>.svn/deb-layout</filename> on every invocation.
              Since version 0.6.22 this behaviour is deprecated.
              </para>
              <para>With this parameter <command>svn-buildpackage</command>
              will (partly) replicate the old behaviour. In contrast to the
              deprecated behaviour, the <emphasis>.svn/deb-layout</emphasis>
              is regarded as a local override; the old behaviour simply
              ignored any versioned layout information if it found
              <emphasis>.svn/deb-layout</emphasis>.
              </para>
              <para>This option was provided since it can be useful when
              creating a local override file.</para>
              <para>Default: Off.</para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term>
              <option>--svn-download-orig</option>
            </term>
            <listitem>
              <para>This option makes <command>svn-buildpackage</command> try to download the upstream tarball using <command>apt</command> and
              <command>uscan</command>.</para>
              <para>Default: Off.</para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term>
              <option>--svn-verbose</option>
            </term>
            <listitem>
              <para>More verbose program output.</para>
              <para>Default: Off.</para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term>
              <option>-h</option> |
              <option>--help</option>
            </term>
            <listitem>
              <para>Show the help message.</para>
            </listitem>
          </varlistentry>
        </variablelist>
      </refsect1>
      <refsect1>
        <title>EXAMPLES</title>
        <para>
        For more detailed information on how to use <command>svn-buildpackage</command>,
        see the HOWTO. <ulink url="http://svn-bp.alioth.debian.org/">
        http://svn-bp.alioth.debian.org/</ulink>.
        </para>
        <para>
        To start working with existing native Debian package from a
        <filename>*.dsc</filename> file, import it into the repository with command:
        </para>
        <screen>
svn-inject package_0.1.dsc svn://host/debian/devel/packages
        </screen>
        <para>
        To start working with existing upstream package in Debian from a
        <filename>*.dsc</filename> file, import it into the repository with command:
        </para>
        <screen>
svn-inject -o package_0.1-2.dsc svn://host/debian/devel/packages
        </screen>
        <para>
        Before building an upstream package, ensure the original source
        is available, e.g. if <command>uscan</command> is working:
        </para>
        <screen>
svn mkdir ../tarballs
svn propset svn:ignore "*" ../tarballs
uscan --force-download --destdir ../tarballs
        </screen>
        <para>
        To test building the package from Subversion repository, use command below. Refer
        to <citerefentry> <refentrytitle>dpkg-buildpackage</refentrytitle>
        <manvolnum>1</manvolnum> </citerefentry>
        manual page for the <option>-us</option> etc. options:
        </para>
        <screen>
svn-buildpackage --svn-lintian -us -uc -rfakeroot
        </screen>
        <para>
        To check that package build in a clean state, test it with <citerefentry>
        <refentrytitle>pbuilder</refentrytitle> <manvolnum>1</manvolnum> </citerefentry>:
        </para>
        <screen>
svn mkdir ../build-area  # To store results
svn propset svn:ignore "*" ../build-area
svn-buildpackage --svn-ignore-new --svn-builder=pdebuild
        </screen>
        <para>
        When a new upstream release becomes available, commit all changes and
        have the working tree in clean state. Then use <citerefentry>
        <refentrytitle>svn-upgrade</refentrytitle> <manvolnum>1</manvolnum> </citerefentry>
        to import the new release:
        </para>
        <screen>
svn status   # Check that there are no uncommited changes
svn-upgrade --verbose ../package-2.0.tar.gz
        </screen>
      </refsect1>
      <refsect1>
        <title>CONFIGURATION FILE</title>
        <para><command>svn-buildpackage</command>'s behaviour can be modified
       using the file <filename>~/.svn-buildpackage.conf</filename>. Additional
       parts can be added in each package working directory using the file
       <filename>.svn/svn-buildpackage.conf</filename>. It is
       essentially a list of the long command line options (without leading
       minus signs), one argument per line (without quotes surrounding
       multi-word arguments). The variables are expanded with the system shell
       if shell variables are found there. Avoid ~ sign because of unreliable
       expansion: it is better to use $HOME instead.  Example:</para>
        <screen>
svn-builder=debuild -EPATH
svn-no-links
svn-override=origDir=$HOME/debian/upstream/$PACKAGE
# svn-ignore-new
#svn-lintian
        </screen>
      </refsect1>
      <refsect1>
        <title>DIRECTORY LAYOUT HANDLING</title>
        <para>By default, <command>svn-buildpackage</command> expects
        a configuration file with path/url declaration,
        <filename>.svn/deb-layout</filename>. The values there can be
        overridden with the <option>--svn-override</option>  option,
        see above. If a config file could not be found, the settings are
        autodetected following the usual assumptions about local directories
        and repository layout.  In addition, the contents of a custom file
        <filename>debian/svn-deblayout</filename> will be imported during the
        initial configuration. Package maintainers can store this file in
        the repository to pass correct defaults to new <command>svn-buildpackage</command>
        users. The format is the same as in the file
        <filename>.svn/deb-layout</filename>. As an alternative to the
        <filename>debian/svn-deblayout</filename> file, maintainers can
        set Subversion properties for the <filename>debian/</filename>
        directory; any properties of <filename>debian/</filename> which
        have a name of the form <emphasis>svn-bp:<replaceable>PROP</replaceable></emphasis> will be
        the source of a <replaceable>PROP</replaceable> setting which has the value indicated by the
        first line of the property value. If a full svn URL is not
        given, the repository root will be prepended to this value.
        </para>
      </refsect1>
      <refsect1>
        <title>ENVIRONMENT VARIABLES</title>
        <para>The following environment variables are exported by
        <command>svn-buildpackage</command> and can be used in hook
        commands or the package build system.
        </para>
        <variablelist>
          <varlistentry>
            <term>PACKAGE</term>
            <term>package</term>
            <listitem>
              <para>The source package name.</para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term>SVN_BUILDPACKAGE</term>
            <listitem>
              <para>Version of <command>svn-buildpackage</command>.</para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term>TAG_VERSION</term>
            <term>debian_version</term>
            <listitem>
              <para>The complete Debian version string, also used for the
              tag copy.
              </para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term>non_epoch_version</term>
            <listitem>
              <para>Same as <option>debian_version</option> but without any epoch strings.</para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term>upstream_version</term>
            <listitem>
              <para>Same as debian_version but without Debian extensions</para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term>guess_loc</term>
            <listitem>
              <para>Guessed upstream source package name in the pool,
              something like
              <filename>libm/libmeta-html-perl_3.2.1.0.orig.tar.gz</filename>
              </para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term>DIFFSRC</term>
            <listitem>
              <para>(experimental) shows the location of generated diff file</para>
            </listitem>
          </varlistentry>
        </variablelist>
        <para>All the layout properties are exported to the environment, too.
        The following ones have meaning to <command>svn-buildpackage</command>.</para>
        <variablelist>
          <varlistentry>
            <term>buildArea</term>
            <listitem>
              <para>the location of build area directory</para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term>trunkUrl</term>
            <listitem>
              <para>the URL of the trunk directory for the current package.</para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term>tagsUrl</term>
            <listitem>
              <para>the URL of the tags base directory for the current package.</para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term>origDir</term>
            <listitem>
              <para>the local directory where the orig tarball should be
              located.
              </para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term>origUrl</term>
            <listitem>
              <para>the URL from where the orig tarball for the current
              package can be pulled from.
              </para>
            </listitem>
          </varlistentry>
        </variablelist>
        <para>The following variables are understood by <command>svn-buildpackage</command>:
        </para>
        <variablelist>
          <varlistentry>
            <term>FORCETAG</term>
            <listitem>
              <para>Ignore the signs of an incomplete changelog and tag
              the repository anyway.
              </para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term>FORCEEXPORT</term>
            <listitem>
              <para>Export upstream source from the repository even if
              <userinput>mergeWithUpstream</userinput> property is set.
              </para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term>DEBIAN_FRONTEND</term>
            <listitem>
              <para>If <option>DEBIAN_FRONTEND</option> is set to 'noninteractive'
              <option>--svn-noninteractive</option> is called silently.
              </para>
            </listitem>
          </varlistentry>
        </variablelist>
      </refsect1>
      <refsect1>
        <title>RECOMMENDATIONS</title>
        <para>Use shell aliases. Here are some examples for Bash:</para>
        <programlisting>
alias svn-b="svn-buildpackage -us -uc -rfakeroot --svn-ignore"
alias svn-br="svn-b --svn-dont-purge --svn-reuse"
alias svn-bt="svn-buildpackage --svn-tag -rfakeroot"
        </programlisting>
        <para>Those commands have respective meanings: build regardless
        of new or changed files; build regardless of new or changed
        files and reuse the build directory; build (for upload) and tag.
        </para>
        <para>SSH is the easiest way to access remote repositories,
        although it usually requires entering a password more frequently
        with <command>svn-buildpackage</command>.  Workarounds include
        using an ssh key without a passphrase (although this is insecure
        and still relatively slow), or the SSH connection caching feature
        present in recent versions of SSH. For details, see the
        <command>svn-buildpackage</command> manual.
        </para>
        <para>Another way to get a remote link is using the Subversion
        DAV module (with SSL and Apache user authentication), see the
        <command>svn-buildpackage</command> HOWTO manual for details.
        </para>
      </refsect1>
      <refsect1>
        <title>SEE ALSO</title>
        <variablelist>
          <varlistentry>
            <term>
              <citerefentry>
                <refentrytitle>/usr/share/doc/svn-buildpackage/</refentrytitle>
              </citerefentry>
            </term>
            <listitem>
              <para>The svn-buildpackage HOWTO manual</para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term>
              <citerefentry>
                <refentrytitle>svn-inject</refentrytitle>
                <manvolnum>1</manvolnum>
              </citerefentry>
            </term>
            <listitem>
              <para>puts a Debian source package into Subversion repository</para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term>
              <citerefentry>
                <refentrytitle>svn-upgrade</refentrytitle>
                <manvolnum>1</manvolnum>
              </citerefentry>
            </term>
            <listitem>
              <para>upgrade source package from a new upstream revision</para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term>
              <citerefentry>
                <refentrytitle>svn</refentrytitle>
                <manvolnum>1</manvolnum>
              </citerefentry>
            </term>
            <listitem>
              <para>Subversion command line client tool</para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term>
              <citerefentry>
                <refentrytitle>dpkg-buildpackage</refentrytitle>
                <manvolnum>1</manvolnum>
              </citerefentry>
            </term>
            <listitem>
              <para>Debian source package tools</para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term>
              <citerefentry>
                <refentrytitle>lintian</refentrytitle>
                <manvolnum>1</manvolnum>
              </citerefentry>
            </term>
            <listitem>
              <para>Debian package checker</para>
            </listitem>
          </varlistentry>
        </variablelist>
      </refsect1>
    </refentry>