Obnam, a backup program
=======================
Obnam is a backup program.
Home page
---------
The Obnam home page is at , see there
for more information.
Installation
------------
The source tree contains packaging for Debian. Run `debuild -us -uc -i.bzr` to
build an installation package.
On other systems, using the `setup.py` file should work: run
"python setup.py --help" for advice. If not, please report a bug.
(I've only tested `setup.py` enough for to build the Debian package.)
You need to install my Python B-tree library, and some of my other libraries
and tools, which you can get from:
*
*
* (for automatic tests)
*
*
*
*
*
* (for benchmarks)
You also need third party libraries:
* paramiko:
See debian/control for the full set of build dependencies and runtime
dependencies on a Debian system. (That set actually gets tested. The
above list is maintained manually and may get out of date from time
to time.)
Use
---
To get a quick help summary of options:
./obnam --help
To make a backup:
./obnam backup --repository /tmp/mybackup $HOME
For more information, see the manual page:
man -l obnam.1
Hacking
-------
The canonical version control repository for obnam itself is at:
http://code.liw.fi/obnam/bzr/
The 'trunk' branch is the main development one. Note that the URL points
at a bzr repository, it is not useful to browse it by hand.
To build and run automatic tests:
./check
./check --fast # unit tests only, no blackboxtests
./check --network # requires ssh access to localhost
`check` is a wrapper around `python setup.py`, but since using that
takes several steps, the script makes things easier.
You need my CoverageTestRunner to run tests, see above for where to get it.
A couple of scripts exist to run benchmarks and profiles:
./metadata-speed 10000
./obnam-benchmark --size=1m/100k --results /tmp/benchmark-results
viewprof /tmp/benchmark-results/*/*backup-0.prof
seivots-summary /tmp/benchmark-results/*/*.seivot | less -S
There are two kinds of results: Python profiling output, and `.seivot`
files.
For the former, `viewprof` is a little helper script I wrote,
around the Python pstats module.
You can use your own, or get mine from extrautils
(). Running the benchmarks under profiling
makes them a little slower (typically around 10% for me, when I've
compared), but that's OK: the absolute numbers of the benchmarks are
less important than the relative ones. It's nice to be able to look at
the profiler output, if a benchmark is surprisingly slow, without
having to re-run it.
`seivots-summary` is a tool to display summaries of the measurements
made during a benchmark run. `seivot` is the tool that makes the
measurements. I typically save a number of benchmark results, so that
I can see how my changes affect performance over time.
If you make any changes, I welcome patches, either as plain diffs, bzr
bundles, or public repositories I can merge from.
The code layout is roughly like this:
obnamlib/ # all the real code
obnamlib/plugins/ # the plugin code (see pluginmgr.py)
obnam # script to invoke obnam
_obnammodule.c # wrapper around some system calls
In obnamlib, every code module has a corresponding test module,
and "make check" uses CoverageTestRunner to run them pairwise. For
each pair, test coverage must be 100% or the test will fail.
Mark statements that should not be included in coverage test with
"# pragma: no cover", if you really, really can't write a test.
without-tests lists modules that have no test modules.
If you want to make a new release of Obnam, I recommend following
my release checklist: .
Feedback
--------
I welcome bug fixes, enhancements, bug reports, suggestions, requests,
and other feedback. I prefer e-mail the mailing list:
see
for instructions.
It would be helpful if you can run `make clean check` before submitting
a patch, but it is not strictly required.
Legal stuff
-----------
Most of the code is written by Lars Wirzenius. (Please provide patches
so that can change.)
The code is covered by the GNU General Public License, version 3 or later.
Copyright 2010-2013 Lars Wirzenius
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 3 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, see .