diff --git a/AUTHORS b/AUTHORS index 353d0747f..45cc6e41c 100644 --- a/AUTHORS +++ b/AUTHORS @@ -1,5 +1,5 @@ -Borg Contributors ("The Borg Collective") -========================================= +Contributors ("The Borg Collective") +==================================== - Thomas Waldmann - Antoine Beaupré diff --git a/docs/global.rst.inc b/docs/global.rst.inc index 265ad2658..eaa4648bc 100644 --- a/docs/global.rst.inc +++ b/docs/global.rst.inc @@ -16,12 +16,12 @@ .. _libattr: http://savannah.nongnu.org/projects/attr/ .. _liblz4: https://github.com/Cyan4973/lz4 .. _OpenSSL: https://www.openssl.org/ -.. _Python: http://www.python.org/ +.. _`Python 3`: http://www.python.org/ .. _Buzhash: https://en.wikipedia.org/wiki/Buzhash .. _msgpack: http://msgpack.org/ .. _`msgpack-python`: https://pypi.python.org/pypi/msgpack-python/ .. _llfuse: https://pypi.python.org/pypi/llfuse/ -.. _homebrew: http://mxcl.github.io/homebrew/ +.. _homebrew: http://brew.sh/ .. _userspace filesystems: https://en.wikipedia.org/wiki/Filesystem_in_Userspace .. _librelist: http://librelist.com/ .. _Cython: http://cython.org/ diff --git a/docs/installation.rst b/docs/installation.rst index 77cd99aad..efe8dadbc 100644 --- a/docs/installation.rst +++ b/docs/installation.rst @@ -4,153 +4,126 @@ Installation ============ -|project_name| pyinstaller binary installation requires: +There are different ways to install |project_name|: -* Linux: glibc >= 2.13 (ok for most supported Linux releases) -* MacOS X: 10.10 (unknown whether it works for older releases) -* FreeBSD: 10.2 (unknown whether it works for older releases) - -|project_name| non-binary installation requires: - -* Python_ >= 3.2.2 -* OpenSSL_ >= 1.0.0 -* libacl_ (that pulls in libattr_ also) -* liblz4_ -* some python dependencies, see install_requires in setup.py - -General notes -------------- -You need to do some platform specific preparation steps (to install libraries -and tools) followed by the generic installation of |project_name| itself: - -Below, we describe different ways to install |project_name|. - -- **dist package** - easy and fast, needs a distribution and platform specific - binary package (for your Linux/*BSD/OS X/... distribution). -- **pyinstaller binary** - easy and fast, we provide a ready-to-use binary file - that just works on the supported platforms -- **pypi** - installing a source package from pypi needs more installation steps - and will need a compiler, development headers, etc.. +- **distribution package** - easy and fast if a package is available for your + Linux/BSD distribution. +- **PyInstaller binary** - easy and fast, we provide a ready-to-use binary file + that comes bundled with all dependencies. +- **pip** - installing a source package with pip needs more installation steps + and requires all dependencies with development headers and a compiler. - **git** - for developers and power users who want to have the latest code or use revision control (each release is tagged). -**Python 3**: Even though this is not the default Python version on many systems, -it is usually available as an optional install. -Virtualenv_ can be used to build and install |project_name| without affecting -the system Python or requiring root access. +Installation (Distribution Package) +----------------------------------- -Important: -If you install into a virtual environment, you need to **activate** -the virtual env first (``source borg-env/bin/activate``). -Alternatively, directly run ``borg-env/bin/borg`` (or symlink that into some -directory that is in your PATH so you can just run ``borg``). -Using a virtual environment is optional, but recommended except for the most -simple use cases. +Some Linux and BSD distributions might offer a ready-to-use ``borgbackup`` +package which can be installed with the package manager. As |project_name| is +still a young project, such a package might be not available for your system +yet. Please ask package maintainers to build a package or, if you can package / +submit it yourself, please help us with that! -The llfuse_ python package is also required if you wish to mount an -archive as a FUSE filesystem. Only FUSE >= 2.8.0 can support llfuse. +* On **Arch Linux**, there is a package available in the AUR_. -You only need **Cython** to compile the .pyx files to the respective .c files -when using |project_name| code from git. For |project_name| releases, the .c -files will be bundled, so you won't need Cython to install a release. +If a package is available, it might be interesting to check its version +and compare that to our latest release and review the :doc:`changes`. -Platform notes --------------- -FreeBSD: You may need to get a recent enough OpenSSL version from FreeBSD ports. - -Mac OS X: You may need to get a recent enough OpenSSL version from homebrew_. - -Mac OS X: You need OS X FUSE >= 3.0. +.. _AUR: https://aur.archlinux.org/packages/borgbackup/ -Installation (dist package) ---------------------------- -Some Linux, BSD and OS X distributions might offer a ready-to-use -`borgbackup` package (which can be easily installed in the usual way). - -As |project_name| is still relatively new, such a package might be not -available for your system yet. Please ask package maintainers to build a -package or, if you can package / submit it yourself, please help us with -that! - -If a package is available, it might be interesting for you to check its version -and compare that to our latest release and review the change log (see links on -our web site). - - -Installation (pyinstaller binary) +Installation (PyInstaller Binary) --------------------------------- -For some platforms we offer a ready-to-use standalone borg binary. -It is supposed to work without requiring installation or preparations. +The |project_name| binary is available on the releases_ page for the following +platforms: -Check https://github.com/borgbackup/borg/releases for available binaries. +* **Linux**: glibc >= 2.13 (ok for most supported Linux releases) +* **Mac OS X**: 10.10 (unknown whether it works for older releases) +* **FreeBSD**: 10.2 (unknown whether it works for older releases) +These binaries work without requiring specific installation steps. Just drop +them into a directory in your ``PATH`` and then you can run ``borg``. If a new +version is released, you will have to manually download it and replace the old +version. -Debian Jessie / Ubuntu 14.04 preparations (git/pypi) ----------------------------------------------------- +.. _releases: https://github.com/borgbackup/borg/releases -:: +Installing the Dependencies +--------------------------- - # Python 3.x (>= 3.2) + Headers, Py Package Installer, VirtualEnv - apt-get install python3 python3-dev python3-pip python-virtualenv +To install |project_name| from a source package, you have to install the +following dependencies first: - # we need OpenSSL + Headers for Crypto - apt-get install libssl-dev openssl +* `Python 3`_ >= 3.2.2. Even though Python 3 is not the default Python version on + most systems, it is usually available as an optional install. +* OpenSSL_ >= 1.0.0 +* libacl_ (that pulls in libattr_ also) +* liblz4_ +* some Python dependencies, pip will automatically install them for you +* optionally, the llfuse_ Python package is required if you wish to mount an + archive as a FUSE filesystem. FUSE >= 2.8.0 is required for llfuse. - # ACL support Headers + Library - apt-get install libacl1-dev libacl1 +In the following, the steps needed to install the dependencies are listed for a +selection of platforms. If your distribution is not covered by these +instructions, try to use your package manager to install the dependencies. On +FreeBSD, you may need to get a recent enough OpenSSL version from FreeBSD +ports. - # lz4 super fast compression support Headers + Library - apt-get install liblz4-dev liblz4-1 +After you have installed the dependencies, you can proceed with steps outlined +under :ref:`pip-installation`. - # if you do not have gcc / make / etc. yet - apt-get install build-essential +Debian / Ubuntu +~~~~~~~~~~~~~~~ - # optional: FUSE support - to mount backup archives - # in case you get complaints about permission denied on /etc/fuse.conf: - # on ubuntu this means your user is not in the "fuse" group. just add - # yourself there, log out and log in again. - apt-get install libfuse-dev fuse pkg-config +Install the dependencies with development headers:: - # optional: for unit testing - apt-get install fakeroot + sudo apt-get install python3 python3-dev python3-pip python-virtualenv + sudo apt-get install libssl-dev openssl + sudo apt-get install libacl1-dev libacl1 + sudo apt-get install liblz4-dev liblz4-1 + sudo apt-get install build-essential + sudo apt-get install libfuse-dev fuse pkg-config # optional, for FUSE support +In case you get complaints about permission denied on ``/etc/fuse.conf``: on +Ubuntu this means your user is not in the ``fuse`` group. Add yourself to that +group, log out and log in again. -Korora / Fedora 21 preparations (git/pypi) ------------------------------------------- +Fedora / Korora +~~~~~~~~~~~~~~~ -:: +Install the dependencies with development headers:: - # Python 3.x (>= 3.2) + Headers, Py Package Installer, VirtualEnv sudo dnf install python3 python3-devel python3-pip python3-virtualenv - - # we need OpenSSL + Headers for Crypto sudo dnf install openssl-devel openssl - - # ACL support Headers + Library sudo dnf install libacl-devel libacl - - # lz4 super fast compression support Headers + Library sudo dnf install lz4-devel - - # optional: FUSE support - to mount backup archives - sudo dnf install fuse-devel fuse pkgconfig - - # optional: for unit testing - sudo dnf install fakeroot + sudo dnf install fuse-devel fuse pkgconfig # optional, for FUSE support -Cygwin preparations (git/pypi) ------------------------------- +Mac OS X +~~~~~~~~ -Please note that running under cygwin is rather experimental, stuff has been -tested with CygWin (x86-64) v2.1.0. +Assuming you have installed homebrew_, the following steps will install all the +dependencies:: -You'll need at least (use the cygwin installer to fetch/install these): + brew install python3 lz4 openssl + pip3 install virtualenv -:: +For FUSE support to mount the backup archives, you need at least version 3.0 of +FUSE for OS X, which is available as a pre-release_. + +.. _pre-release: https://github.com/osxfuse/osxfuse/releases + +Cygwin +~~~~~~ + +.. note:: + Running under Cygwin is experimental and has only been tested with Cygwin + (x86-64) v2.1.0. + +Use the Cygwin installer to install the dependencies:: python3 python3-setuptools python3-cython # not needed for releases @@ -159,36 +132,45 @@ You'll need at least (use the cygwin installer to fetch/install these): liblz4_1 liblz4-devel # from cygwinports.org git make openssh -You can then install ``pip`` and ``virtualenv``: - -:: +You can then install ``pip`` and ``virtualenv``:: easy_install-3.4 pip pip install virtualenv -And now continue with the generic installation (see below). - -In case that creation of the virtual env fails, try deleting this file: - -:: +In case the creation of the virtual environment fails, try deleting this file:: /usr/lib/python3.4/__pycache__/platform.cpython-34.pyc -Installation (pypi) -------------------- +.. _pip-installation: -This uses the latest (source package) release from PyPi. :: +Installation (pip) +------------------ + +Virtualenv_ can be used to build and install |project_name| without affecting +the system Python or requiring root access. Using a virtual environment is +optional, but recommended except for the most simple use cases. + +.. note:: + If you install into a virtual environment, you need to **activate** it + first (``source borg-env/bin/activate``), before running ``borg``. + Alternatively, symlink ``borg-env/bin/borg`` into some directory that is in + your ``PATH`` so you can just run ``borg``. + +This will use ``pip`` to install the latest release from PyPi:: virtualenv --python=python3 borg-env - source borg-env/bin/activate # always before using! + source borg-env/bin/activate - # install borg + dependencies into virtualenv + # install Borg + Python dependencies into virtualenv pip install 'llfuse<0.41' # optional, for FUSE support # 0.41 and 0.41.1 have unicode issues at install time pip install borgbackup -.. note:: We install into a virtual environment here, but this is not a requirement. +To upgrade |project_name| to a new version later, run the following after +activating your virtual environment:: + + pip install -U borgbackup Installation (git) @@ -212,6 +194,7 @@ While we try not to break master, there are no guarantees on anything. :: pip install -e . # in-place editable mode # optional: run all the tests, on all supported Python versions + # requires fakeroot, available through your package manager fakeroot -u tox .. note:: As a developer or power user, you always want to use a virtual environment.