mirror of https://github.com/borgbackup/borg.git
Merge pull request #295 from yagebu/master
docs: restructure installation.rst + add OS X install instructions
This commit is contained in:
TW
commit
b0f66e84a9
4
AUTHORS
4
AUTHORS
|
|
@ -1,5 +1,5 @@
|
|||
Borg Contributors ("The Borg Collective")
|
||||
=========================================
|
||||
Contributors ("The Borg Collective")
|
||||
====================================
|
||||
|
||||
- Thomas Waldmann <tw@waldmann-edv.de>
|
||||
- Antoine Beaupré
|
||||
|
|
|
|||
|
|
@ -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/
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
Loading…
Reference in New Issue