diff --git a/docs/index.rst b/docs/index.rst index 97a374a..d9188c8 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -19,6 +19,7 @@ It aims to be for CalDAV and CardDAV what `OfflineIMAP :maxdepth: 1 when + installation tutorial ssl-tutorial keyring diff --git a/docs/installation.rst b/docs/installation.rst new file mode 100644 index 0000000..9e76426 --- /dev/null +++ b/docs/installation.rst @@ -0,0 +1,109 @@ +.. _installation: + +===================== +Installing vdirsyncer +===================== + +OS/distro packages +------------------ + +Unless you want to contribute to vdirsyncer, you should use the packages from +your distribution: + +- `ArchLinux (AUR) `_ +- `pkgsrc `_ +- `Fedora `_ +- `nixpkg `_ +- `GNU Guix `_ +- `homebrew `_ +- `Gentoo `_ +- `Debian Sid `_. +- Debian stable and Ubuntu don't have packages, but make a manual installation + especially hard. See :ref:`debian-urllib3`. + +If there is no package for your distribution, you'll need to :ref:`install +vdirsyncer manually `. There is an easy command to +copy-and-paste for this as well, but you should be aware of its consequences. + + +.. _manual-installation: + +Manual installation +------------------- + +If your distribution doesn't provide a package for vdirsyncer, you still can +use Python's package manager "pip". First, you'll have to check that the +following things are installed: + +- A compatible version of Python (2.7+ or 3.3+) and the corresponding pip package +- ``libxml`` and ``libxslt`` +- ``zlib`` + +On Linux systems, using the distro's package manager is the best +way to do this, for example, using Ubuntu:: + + sudo apt-get install libxml2 libxslt1.1 zlib1g python + +Then you have several options. The following text applies for most Python +software by the way. + +The dirty, easy way +~~~~~~~~~~~~~~~~~~~ + +The easiest way to install vdirsyncer at this point would be to run:: + + pip install --user --ignore-installed vdirsyncer + +- ``--user`` is to install without root rights (into your home directory) +- ``--ignore-installed`` is to work around Debian's potentially broken packages + (see :ref:`debian-urllib3`). + +This method has a major flaw though: Pip doesn't keep track of the files it +installs. Vdirsyncer's files would be located somewhere in +``~/.local/lib/python*``, but you can't possibly know which packages were +installed as dependencies of vdirsyncer and which ones were not, should you +decide to uninstall it. In other words, using pip that way would pollute your +home directory. + +The clean but hard way +~~~~~~~~~~~~~~~~~~~~~~ + +There is a way to install Python software without scattering stuff across +your filesystem: virtualenv_. There are a lot of resources on how to use it, +the simplest possible way would look something like:: + + virtualenv ~/vdirsyncer_env + ~/vdirsyncer_env/bin/pip install vdirsyncer + alias vdirsyncer="~/vdirsyncer_env/bin/vdirsyncer + +You'll have to put the last line into your ``.bashrc`` or ``.bash_profile``. + +This method has two advantages: + +- It separately installs all Python packages into ``~/vdirsyncer_env/``, + without relying on the system packages. This works around OS- or + distro-specific issues. +- You can delete ``~/vdirsyncer_env/`` to uninstall vdirsyncer entirely. + +The new, perfect way +~~~~~~~~~~~~~~~~~~~~ + +pipsi_ is a new package manager for Python-based software that automatically +sets up a virtualenv for each program you install. Assuming you have it +installed on your operating system, you can do:: + + pipsi install --python python3 vdirsyncer + +and ``.local/bin/vdirsyncer`` will be your new vdirsyncer installation. To +update vdirsyncer to the latest version:: + + pipsi upgrade vdirsyncer + +If you're done with vdirsyncer, you can do:: + + pipsi uninstall vdirsyncer + +and vdirsyncer will be uninstalled, including its dependencies. + +.. _virtualenv: https://virtualenv.readthedocs.io/ +.. _pipsi: https://github.com/mitsuhiko/pipsi diff --git a/docs/problems.rst b/docs/problems.rst index 21f0139..179c411 100644 --- a/docs/problems.rst +++ b/docs/problems.rst @@ -24,86 +24,3 @@ Debian has had its problems in the past with the Python requests package, see - If this doesn't help, install vdirsyncer in a virtualenv, see :ref:`manual-installation`. - - -.. _manual-installation: - -Manual installation -------------------- - -If your distribution doesn't provide a package for vdirsyncer, you still can -use Python's package manager "pip". First, you'll have to check that the -following things are installed: - -- A compatible version of Python (2.7+ or 3.3+) and the corresponding pip package -- ``libxml`` and ``libxslt`` -- ``zlib`` - -On Linux systems, using the distro's package manager is the best -way to do this, for example, using Ubuntu:: - - sudo apt-get install libxml2 libxslt1.1 zlib1g python - -Then you have several options. The following text applies for most Python -software by the way. - -The dirty, easy way -~~~~~~~~~~~~~~~~~~~ - -The easiest way to install vdirsyncer at this point would be to run:: - - pip install --user --ignore-installed vdirsyncer - -- ``--user`` is to install without root rights (into your home directory) -- ``--ignore-installed`` is to work around Debian's potentially broken packages - (see :ref:`debian-urllib3`). - -This method has a major flaw though: Pip doesn't keep track of the files it -installs. Vdirsyncer's files would be located somewhere in -``~/.local/lib/python*``, but you can't possibly know which packages were -installed as dependencies of vdirsyncer and which ones were not, should you -decide to uninstall it. In other words, using pip that way would pollute your -home directory. - -The clean but hard way -~~~~~~~~~~~~~~~~~~~~~~ - -There is a way to install Python software without scattering stuff across -your filesystem: virtualenv_. There are a lot of resources on how to use it, -the simplest possible way would look something like:: - - virtualenv ~/vdirsyncer_env - ~/vdirsyncer_env/bin/pip install vdirsyncer - alias vdirsyncer="~/vdirsyncer_env/bin/vdirsyncer - -You'll have to put the last line into your ``.bashrc`` or ``.bash_profile``. - -This method has two advantages: - -- It separately installs all Python packages into ``~/vdirsyncer_env/``, - without relying on the system packages. This works around OS- or - distro-specific issues. -- You can delete ``~/vdirsyncer_env/`` to uninstall vdirsyncer entirely. - -The new, perfect way -~~~~~~~~~~~~~~~~~~~~ - -pipsi_ is a new package manager for Python-based software that automatically -sets up a virtualenv for each program you install. Assuming you have it -installed on your operating system, you can do:: - - pipsi install --python python3 vdirsyncer - -and ``.local/bin/vdirsyncer`` will be your new vdirsyncer installation. To -update vdirsyncer to the latest version:: - - pipsi upgrade vdirsyncer - -If you're done with vdirsyncer, you can do:: - - pipsi uninstall vdirsyncer - -and vdirsyncer will be uninstalled, including its dependencies. - -.. _virtualenv: https://virtualenv.readthedocs.io/ -.. _pipsi: https://github.com/mitsuhiko/pipsi diff --git a/docs/tutorial.rst b/docs/tutorial.rst index f699cef..865b9de 100644 --- a/docs/tutorial.rst +++ b/docs/tutorial.rst @@ -8,23 +8,7 @@ are better alternatives available for particular usecases. Installation ============ -Unless you want to contribute to vdirsyncer, you should use the packages from -your distribution: - -- `ArchLinux (AUR) `_ -- `pkgsrc `_ -- `Fedora `_ -- `nixpkg `_ -- `GNU Guix `_ -- `homebrew `_ -- `Gentoo `_ -- `Debian Sid `_. -- Debian stable and Ubuntu don't have packages, but make a manual installation - especially hard. See :ref:`debian-urllib3`. - -If there is no package for your distribution, you'll need to :ref:`install -vdirsyncer manually `. There is an easy command to -copy-and-paste for this as well, but you should be aware of its consequences. +See :ref:`installation`. Configuration =============