|
|
@@ -4,153 +4,126 @@
|
|
|
Installation
|
|
|
============
|
|
|
|
|
|
-|project_name| pyinstaller binary installation requires:
|
|
|
-
|
|
|
-* 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..
|
|
|
+There are different ways to install |project_name|:
|
|
|
+
|
|
|
+- **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.
|
|
|
-
|
|
|
-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.
|
|
|
-
|
|
|
-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.
|
|
|
+Installation (Distribution Package)
|
|
|
+-----------------------------------
|
|
|
|
|
|
-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.
|
|
|
+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!
|
|
|
|
|
|
-Platform notes
|
|
|
---------------
|
|
|
-FreeBSD: You may need to get a recent enough OpenSSL version from FreeBSD ports.
|
|
|
+* On **Arch Linux**, there is a package available in the AUR_.
|
|
|
|
|
|
-Mac OS X: You may need to get a recent enough OpenSSL version from homebrew_.
|
|
|
+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`.
|
|
|
|
|
|
-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
|
|
|
+ sudo dnf install fuse-devel fuse pkgconfig # optional, for FUSE support
|
|
|
+
|
|
|
+
|
|
|
+Mac OS X
|
|
|
+~~~~~~~~
|
|
|
+
|
|
|
+Assuming you have installed homebrew_, the following steps will install all the
|
|
|
+dependencies::
|
|
|
|
|
|
- # optional: FUSE support - to mount backup archives
|
|
|
- sudo dnf install fuse-devel fuse pkgconfig
|
|
|
-
|
|
|
- # optional: for unit testing
|
|
|
- sudo dnf install fakeroot
|
|
|
+ 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_.
|
|
|
|
|
|
-Cygwin preparations (git/pypi)
|
|
|
-------------------------------
|
|
|
+.. _pre-release: https://github.com/osxfuse/osxfuse/releases
|
|
|
|
|
|
-Please note that running under cygwin is rather experimental, stuff has been
|
|
|
-tested with CygWin (x86-64) v2.1.0.
|
|
|
+Cygwin
|
|
|
+~~~~~~
|
|
|
|
|
|
-You'll need at least (use the cygwin installer to fetch/install these):
|
|
|
+.. 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 the creation of the virtual environment fails, try deleting this file::
|
|
|
|
|
|
-In case that creation of the virtual env fails, try deleting this file:
|
|
|
+ /usr/lib/python3.4/__pycache__/platform.cpython-34.pyc
|
|
|
|
|
|
-::
|
|
|
|
|
|
- /usr/lib/python3.4/__pycache__/platform.cpython-34.pyc
|
|
|
+.. _pip-installation:
|
|
|
|
|
|
+Installation (pip)
|
|
|
+------------------
|
|
|
|
|
|
-Installation (pypi)
|
|
|
--------------------
|
|
|
+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.
|
|
|
|
|
|
-This uses the latest (source package) release from PyPi. ::
|
|
|
+.. 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.
|
TW