bup-init.md: update after dropping automatic ~/.bup init.

[bup.git] / README.md

diff --git a/README.md b/README.md
index aca769072a4578f4cfbccf2387f6067cad62bd08..87cbc2f2090429350012169a6ca5de722bae15c1 100644 (file)
--- a/README.md
+++ b/README.md
@@ -1,4 +1,3 @@
-
 bup: It backs things up
 =======================
 
@@ -72,7 +71,7 @@ Reasons you might want to avoid bup
    for you, but we don't know why.  It is also missing some
    probably-critical features.
    
- - It requires python >= 2.4, a C compiler, and an installed git version >=
+ - It requires python >= 2.5, a C compiler, and an installed git version >=
    1.5.3.1.
  
  - It currently only works on Linux, MacOS X >= 10.4,
@@ -89,7 +88,7 @@ From source
 
  - Check out the bup source code using git:
  
-        git clone git://github.com/apenwarr/bup
+        git clone git://github.com/bup/bup
 
  - Install the needed python libraries (including the development
    libraries).
@@ -98,10 +97,10 @@ From source
 
             apt-get install python2.6-dev python-fuse
             apt-get install python-pyxattr python-pylibacl
+            apt-get install linux-libc-dev
 
-   Substitute python2.5-dev or python2.4-dev if you have an older
-   system.  Alternately, on newer Debian/Ubuntu versions, you can try
-   this:
+   Substitute python2.5-dev if you have an older system.  Alternately,
+   on newer Debian/Ubuntu versions, you can try this:
     
             apt-get build-dep bup
 
@@ -110,9 +109,14 @@ From source
 
             yum groupinstall "Development Tools"
             yum install python python-dev
-            yum fuse-python pyxattr pylibacl
+            yum install fuse-python pyxattr pylibacl
             yum install perl-Time-HiRes
 
+   In addition to the default CentOS repositories, you may need to add
+   RPMForge (for fuse-python) and EPEL (for pyxattr and pylibacl).
+
+   On Cygwin, install python, make, rsync, and gcc4.
+
  - Build the python module and symlinks:
 
         make
@@ -124,6 +128,15 @@ From source
     (The tests should pass.  If they don't pass for you, stop here and send
     me an email.)
 
+ - You can install bup via "make install", and override the default
+   destination with DESTDIR and PREFIX.
+
+   Files are normally installed to "$DESTDIR/$PREFIX" where DESTDIR is
+   empty by default, and PREFIX is set to /usr.  So if you wanted to
+   install bup to /opt/bup, you might do something like this:
+
+        make install DESTDIR=/opt/bup PREFIX=''
+
 
 From binary packages
 --------------------
@@ -142,6 +155,10 @@ Binary packages of bup are known to be built for the following OSes:
 Using bup
 ---------
 
+ - Initialize the default BUP_DIR:
+
+        bup init
+
  - Try making a local backup as a tar file:
  
         tar -cvf - /etc | bup split -n local-etc -vv
@@ -245,6 +262,27 @@ Notes on NetBSD/pkgsrc
    anything useful.
 
 
+Notes on Cygwin
+---------------
+
+ - There is no support for ACLs.  If/when some entrprising person
+   fixes this, adjust t/compare-trees.
+
+ - In t/test.sh, two tests have been disabled.  These tests check to
+   see that repeated saves produce identical trees and that an
+   intervening index doesn't change the SHA1.  Apparently Cygwin has
+   some unusual behaviors with respect to access times (that probably
+   warrant further investigation).  Possibly related:
+   http://cygwin.com/ml/cygwin/2007-06/msg00436.html
+
+
+Notes on OS X
+-------------
+
+ - There is no support for ACLs.  If/when some entrprising person
+   fixes this, adjust t/compare-trees.
+
+
 How it works
 ============
 
@@ -315,13 +353,32 @@ mailing list (see below) if you'd like to help.
  
     On the plus side, they actually do have support now, but it's new,
     and not remotely as well tested as tar/rsync/whatever's.  If you'd
-    like to help test, please do; something like 'rsync -niaHAX src/
-    restore/' may be useful on that front.
+    like to help test, please do (see t/compare-trees for one
+    comparison method).
 
     In addition, at the moment, if any strip or graft-style options
     are specified to 'bup save', then no metadata will be written for
     the root directory.  That's obviously less than ideal.
 
+ - bup is overly optimistic about mmap.  Right now bup just assumes
+   that it can mmap as large a block as it likes, and that mmap will
+   never fail.  Yeah, right... If nothing else, this has failed on
+   32-bit architectures (and 31-bit is even worse -- looking at you,
+   s390).
+
+   To fix this, we might just implement a FakeMmap[1] class that uses
+   normal file IO and handles all of the mmap methods[2] that bup
+   actually calls.  Then we'd swap in one of those whenever mmap
+   fails.
+
+   This would also require implementing some of the methods needed to
+   support "[]" array access, probably at a minimum __getitem__,
+   __setitem__, and __setslice__ [3].
+
+     [1] http://comments.gmane.org/gmane.comp.sysutils.backup.bup/613
+     [2] http://docs.python.org/2/library/mmap.html
+     [3] http://docs.python.org/2/reference/datamodel.html#emulating-container-types
+
  - 'bup index' is slower than it should be.
  
     It's still rather fast: it can iterate through all the filenames on my
@@ -402,6 +459,11 @@ and you can subscribe by sending a message to:
 
        bup-list+subscribe@googlegroups.com
 
+Please see <a href="HACKING">./HACKING</a> for
+additional information, i.e. how to submit patches (hint - no pull
+requests), how we handle branches, etc.
+
+
 Have fun,
 
 Avery