borgbackup for Debian - information regarding the packaging
===========================================================



Building the package
--------------------

Please note that a simple "debuild" does not necessary build the
Debian package correctly, *when called in a git clone*.

This is because upstream uses python-setuptools-scm to generate
version numbers, which can produce unexpected results when parsing
the debian tags.  If called outside a git clone, it will fall back
to reading the (upstream-provided) metadata files, which works fine.

It is therefore recommended to build from outside a git clone.

Git-buildpackage includes an "export" feature which will transfer
the files to a scratchpad directory and call debuild/cowbuilder in
that directory; read gbp-buildpackage(1) for details.  The included
debian/gbp.conf file by default activates exporting and uses
"../build-dir/" as a scratchpad.

tl,dr:
1. use "gbp buildpackage" instead of debuild
2. to incrementally work on changes, use a command like
    git add -u && gbp buildpackage --git-ignore-new --git-export=INDEX



Auto-generated files that are included in upstream tarball
----------------------------------------------------------

The upstream tarball contains some files that can be automatically
generated, mainly the Cython-processed *.c files.

After discussion at #792096, it was agreed that we should rebuild
the cython *.c files during build.  This is currently done by deleting
them using the debian/clean file, and letting the upstream build-system
automatically regenerate them as needed.

When updating the package, please check whether files have been added
or removed from this set and update debian/clean accordingly.



Manpage generation
------------------

The manpage included in this package is created using the upstream Sphinx
build system, which includes a "make man" command.

See also upstream issue 208 about manpages:
https://github.com/borgbackup/borg/issues/208



Python3-msgpack dependency
--------------------------

When updating the package, please also check whether the explicitly
given versioned runtime dependency on python3-msgpack is still
necessary.

When building without it, python3:Depends may only pick up a non-versioned
dependency for the binary package, resulting in an installable, yet not
runnable binary package in a backport situation.
(At the time of writing, stable/jessie only has 0.4.2)



Priority extra because of lz4 dependency
----------------------------------------

Keep an eye on liblz4 (source package lz4), which is currently (Jan 2016)
priority extra.  If it gets increased to optional, we can re-include
borgbackup in the optional set.
