mirror/borg
1
0
Fork 0
mirror of https://github.com/borgbackup/borg.git synced 2025-02-20 13:17:27 +00:00
Code Issues Releases Wiki Activity

Merge pull request #295 from yagebu/master

Browse source 
docs: restructure installation.rst + add OS X install instructions
This commit is contained in:
TW 2015-10-17 20:05:36 +02:00
commit b0f66e84a9
3 changed files with 111 additions and 128 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

4
AUTHORS
View file

@ -1,5 +1,5 @@
Borg Contributors ("The Borg Collective") Contributors ("The Borg Collective")
========================================= ====================================
- Thomas Waldmann <tw@waldmann-edv.de> - Thomas Waldmann <tw@waldmann-edv.de>
- Antoine Beaupré - Antoine Beaupré

4
docs/global.rst.inc
View file

@ -16,12 +16,12 @@
.. _libattr: http://savannah.nongnu.org/projects/attr/ .. _libattr: http://savannah.nongnu.org/projects/attr/
.. _liblz4: https://github.com/Cyan4973/lz4 .. _liblz4: https://github.com/Cyan4973/lz4
.. _OpenSSL: https://www.openssl.org/ .. _OpenSSL: https://www.openssl.org/
.. _Python: http://www.python.org/ .. _`Python 3`: http://www.python.org/
.. _Buzhash: https://en.wikipedia.org/wiki/Buzhash .. _Buzhash: https://en.wikipedia.org/wiki/Buzhash
.. _msgpack: http://msgpack.org/ .. _msgpack: http://msgpack.org/
.. _`msgpack-python`: https://pypi.python.org/pypi/msgpack-python/ .. _`msgpack-python`: https://pypi.python.org/pypi/msgpack-python/
.. _llfuse: https://pypi.python.org/pypi/llfuse/ .. _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 .. _userspace filesystems: https://en.wikipedia.org/wiki/Filesystem_in_Userspace
.. _librelist: http://librelist.com/ .. _librelist: http://librelist.com/
.. _Cython: http://cython.org/ .. _Cython: http://cython.org/

231
docs/installation.rst
View file

@ -4,153 +4,126 @@
Installation 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) - **distribution package** - easy and fast if a package is available for your
* MacOS X: 10.10 (unknown whether it works for older releases) Linux/BSD distribution.
* FreeBSD: 10.2 (unknown whether it works for older releases) - **PyInstaller binary** - easy and fast, we provide a ready-to-use binary file
that comes bundled with all dependencies.
|project_name| non-binary installation requires: - **pip** - installing a source package with pip needs more installation steps
and requires all dependencies with development headers and a compiler.
* 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..
- **git** - for developers and power users who want to have the latest code or - **git** - for developers and power users who want to have the latest code or
use revision control (each release is tagged). 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 Installation (Distribution Package)
the system Python or requiring root access. -----------------------------------
Important: Some Linux and BSD distributions might offer a ready-to-use ``borgbackup``
If you install into a virtual environment, you need to **activate** package which can be installed with the package manager. As |project_name| is
the virtual env first (``source borg-env/bin/activate``). still a young project, such a package might be not available for your system
Alternatively, directly run ``borg-env/bin/borg`` (or symlink that into some yet. Please ask package maintainers to build a package or, if you can package /
directory that is in your PATH so you can just run ``borg``). submit it yourself, please help us with that!
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 * On **Arch Linux**, there is a package available in the AUR_.
archive as a FUSE filesystem. Only FUSE >= 2.8.0 can support llfuse.
You only need **Cython** to compile the .pyx files to the respective .c files If a package is available, it might be interesting to check its version
when using |project_name| code from git. For |project_name| releases, the .c and compare that to our latest release and review the :doc:`changes`.
files will be bundled, so you won't need Cython to install a release.
Platform notes .. _AUR: https://aur.archlinux.org/packages/borgbackup/
--------------
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.
Installation (dist package) Installation (PyInstaller Binary)
---------------------------
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)
--------------------------------- ---------------------------------
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 To install |project_name| from a source package, you have to install the
apt-get install python3 python3-dev python3-pip python-virtualenv following dependencies first:
# we need OpenSSL + Headers for Crypto * `Python 3`_ >= 3.2.2. Even though Python 3 is not the default Python version on
apt-get install libssl-dev openssl 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 In the following, the steps needed to install the dependencies are listed for a
apt-get install libacl1-dev libacl1 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 After you have installed the dependencies, you can proceed with steps outlined
apt-get install liblz4-dev liblz4-1 under :ref:`pip-installation`.
# if you do not have gcc / make / etc. yet Debian / Ubuntu
apt-get install build-essential ~~~~~~~~~~~~~~~
# optional: FUSE support - to mount backup archives Install the dependencies with development headers::
# 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
# optional: for unit testing sudo apt-get install python3 python3-dev python3-pip python-virtualenv
apt-get install fakeroot 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 sudo dnf install python3 python3-devel python3-pip python3-virtualenv
# we need OpenSSL + Headers for Crypto
sudo dnf install openssl-devel openssl sudo dnf install openssl-devel openssl
# ACL support Headers + Library
sudo dnf install libacl-devel libacl sudo dnf install libacl-devel libacl
# lz4 super fast compression support Headers + Library
sudo dnf install lz4-devel sudo dnf install lz4-devel
sudo dnf install fuse-devel fuse pkgconfig # optional, for FUSE support
# optional: FUSE support - to mount backup archives
sudo dnf install fuse-devel fuse pkgconfig
# optional: for unit testing
sudo dnf install fakeroot
Cygwin preparations (git/pypi) Mac OS X
------------------------------ ~~~~~~~~
Please note that running under cygwin is rather experimental, stuff has been Assuming you have installed homebrew_, the following steps will install all the
tested with CygWin (x86-64) v2.1.0. 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 python3-setuptools
python3-cython # not needed for releases 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 liblz4_1 liblz4-devel # from cygwinports.org
git make openssh git make openssh
You can then install ``pip`` and ``virtualenv``: You can then install ``pip`` and ``virtualenv``::
::
easy_install-3.4 pip easy_install-3.4 pip
pip install virtualenv 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
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 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 pip install 'llfuse<0.41' # optional, for FUSE support
# 0.41 and 0.41.1 have unicode issues at install time # 0.41 and 0.41.1 have unicode issues at install time
pip install borgbackup 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) 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 pip install -e . # in-place editable mode
# optional: run all the tests, on all supported Python versions # optional: run all the tests, on all supported Python versions
# requires fakeroot, available through your package manager
fakeroot -u tox fakeroot -u tox
.. note:: As a developer or power user, you always want to use a virtual environment. .. note:: As a developer or power user, you always want to use a virtual environment.