1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
|
Obnam, a backup program
=======================
Obnam is a backup program.
Home page
---------
The Obnam home page is at <http://liw.fi/obnam/>, 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:
* <http://liw.fi/larch/>
* <http://liw.fi/ttystatus/>
* <http://liw.fi/coverage-test-runner/> (for automatic tests)
* <http://liw.fi/tracing/>
* <http://liw.fi/cliapp/>
* <http://liw.fi/genbackupdata/>
* <http://liw.fi/summain/>
* <http://liw.fi/cmdtest/>
* <http://liw.fi/seivot/> (for benchmarks)
You also need third party libraries:
* paramiko: <http://www.lag.net/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
(<http://liw.fi/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: <http://liw.fi/obnam/release/>.
Feedback
--------
I welcome bug fixes, enhancements, bug reports, suggestions, requests,
and other feedback. I prefer e-mail the mailing list:
see <http://vlists.pepperfish.net/cgi-bin/mailman/listinfo/obnam-flarn.net>
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 <http://www.gnu.org/licenses/>.
|
