From fdfda1712115db8d29576af176111348b110a0f8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=2E=20David=20Ib=C3=A1=C3=B1ez?= Date: Fri, 18 Jul 2014 20:01:20 +0200 Subject: [PATCH] docs: review the installation documentation --- docs/development.rst | 14 +++ docs/index.rst | 4 +- docs/install.rst | 228 +++++++++++++++++++++++++++++-------------- 3 files changed, 170 insertions(+), 76 deletions(-) create mode 100644 docs/development.rst diff --git a/docs/development.rst b/docs/development.rst new file mode 100644 index 0000000..f44a425 --- /dev/null +++ b/docs/development.rst @@ -0,0 +1,14 @@ +********************************************************************** +The development version +********************************************************************** + +.. image:: https://secure.travis-ci.org/libgit2/pygit2.png + :target: http://travis-ci.org/libgit2/pygit2 + +.. code-block:: sh + + $ git clone git://github.com/libgit2/pygit2.git + $ cd pygit2 + $ python setup.py install + $ python setup.py test + diff --git a/docs/index.rst b/docs/index.rst index 62f112f..fbdfd40 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -6,9 +6,6 @@ Welcome to pygit2's documentation! ================================== -.. image:: https://secure.travis-ci.org/libgit2/pygit2.png - :target: http://travis-ci.org/libgit2/pygit2 - Pygit2 is a set of Python bindings to the libgit2 shared library, libgit2 implements the core of Git. Pygit2 works with Python 2.7, 3.2, 3.3, 3.4 and pypy. @@ -28,6 +25,7 @@ Start: :maxdepth: 1 install + development recipes Usage guide: diff --git a/docs/install.rst b/docs/install.rst index fcc6877..d6e7b33 100644 --- a/docs/install.rst +++ b/docs/install.rst @@ -1,96 +1,132 @@ ********************************************************************** -How to Install +Installation ********************************************************************** - -.. contents:: +.. |lq| unicode:: U+00AB +.. |rq| unicode:: U+00BB -First you need to install the latest release of libgit2. If you clone -the repository, make sure to use the ``master`` branch. You can find -platform-specific instructions to build the library in the libgit2 -website: +.. contents:: Contents + :local: - http://libgit2.github.com -Also, make sure you have Python 2.7 or 3.2+ installed together with the Python -development headers. +Requirements +============ -When those are installed, you can install pygit2: +- Python 2.7, 3.2, 3.3, 3.4 or pypy. + Including the development headers. + +- Libgit2 v0.21.0 + +- cffi 0.8.1+ + + +One common mistake users do is to choose incompatible versions of libgit2 and +pygit2. Be sure to use the latest release of both, double check the versions do +match before filling un bug report. + +.. note:: + + The version of pygit2 is composed of three numbers separated by dots + |lq| *major.minor.micro* |rq|, where the first two numbers + |lq| *major.minor* |rq| match the first two numbers of the libgit2 version, + while the last number |lq| *.micro* |rq| auto-increments independently. + + As illustration see this table of compatible releases: + + +-----------+------+------------------------------+--------------+--------------+ + |**libgit2**|0.21.0|0.20.0 |0.19.0 |0.18.0 | + +-----------+------+------------------------------+--------------+--------------+ + |**pygit2** |0.21.0|0.20.0, 0.20.1, 0.20.2, 0.20.3|0.19.0, 0.19.1|0.18.0, 0.18.1| + +-----------+------+------------------------------+--------------+--------------+ + + **Warning!** Backwards compatibility is not guaranteed even between micro + releases. Please check the release notes for incompatible changes before + upgrading to a new release. + + +Quick install +============= + +This works for me, it may work for you: .. code-block:: sh - $ git clone git://github.com/libgit2/pygit2.git - $ cd pygit2 - $ python setup.py install - $ python setup.py test + $ wget https://github.com/libgit2/libgit2/archive/v0.21.0.tar.gz + $ tar xzf v0.21.0.tar.gz + $ cd libgit2-0.21.0/ + $ cmake . + $ make + $ sudo make install -.. note:: A minor version of pygit2 must be used with the corresponding minor - version of libgit2. For example, pygit2 v0.21.x must be used with libgit2 - v0.21.0 +If this does not work for you, check the detailed instructions on building +libgit2 in various platforms, see +https://libgit2.github.com/docs/guides/build-and-link/ -Building on \*nix (including OS X) -=================================== - -If you installed libgit2 and pygit2 in one of the usual places, you -should be able to skip this section and just use the generic pygit2 -installation steps described above. This is the recommended -procedure. - -`Shared libraries`_ packaged by your distribution are usually in -``/usr/lib``. To keep manually installed libraries separate, they are -usually installed in ``/usr/local/lib``. If you installed libgit2 -using the default installation procedure (e.g. without specifying -``CMAKE_INSTALL_PREFIX``), you probably installed it under -``/usr/local/lib``. On some distributions (e.g. Ubuntu), -``/usr/local/lib`` is not in the linker's default search path (see the -`ld man page`_ for details), and you will get errors like: +Once libgit2 is instaleld, deploying pygit2 should be a snap: .. code-block:: sh - $ python -c 'import pygit2' - Traceback (most recent call last): - File "", line 1, in - File "pygit2/__init__.py", line 29, in - from _pygit2 import * - ImportError: libgit2.so.0: cannot open shared object file: No such file or directory + $ pìp install cffi + $ pip install pygit2 -The following recipe shows how to install libgit2 and pygit2 on these -systems. First, download and install libgit2 (following the -instructions in the libgit2 ``README.md``): + +Troobleshooting +=============== + +You may get an error like this one: .. code-block:: sh - $ git clone -b master git://github.com/libgit2/libgit2.git - $ mkdir libgit2/build - $ cd libgit2/build - $ cmake .. - $ cmake --build . - $ sudo cmake --build . --target install - $ cd ../.. + $ python -c 'import pygit2' + Traceback (most recent call last): + File "", line 1, in + File "pygit2/__init__.py", line 29, in + from _pygit2 import * + ImportError: libgit2.so.0: cannot open shared object file: No such file or directory -Now, download and install pygit2. You will probably have to set the -``LIBGIT2`` environment variable so the compiler can find the libgit2 -headers and libraries: +It means the linker is not able to find the libgit2 library. + +This happens for instance in Ubuntu: the libgit2 library is installed within +the ``/usr/local/lib`` directory, but the linker does not look for it there. To +fix this call ``ldconfig`` between the installation of libgit2 and the +installation of pygit2: .. code-block:: sh - $ git clone git://github.com/libgit2/pygit2.git - $ cd pygit2 - $ export LIBGIT2="/usr/local" - $ export LDFLAGS="-Wl,-rpath='$LIBGIT2/lib',--enable-new-dtags $LDFLAGS" - $ python setup.py build - $ sudo python setup.py install + ... + $ cmake . + $ make + $ sudo make install + ... + $ sudo ldconfig + ... + $ pip install cffi + $ pip install pygit2 -This compiles the pygit2 libraries with a ``RUNPATH``, which bakes -extra library search paths directly into the binaries (see the `ld man -page`_ for details). With ``RUNPATH`` compiled in, you won't have to -use ``LD_LIBRARY_PATH``. You can check to ensure ``RUNPATH`` was set -with readelf_: +Now it should work. If it does not... + +Advanced: the runpath +--------------------- + +If it does not work yet, you can always instruct pygit2 to search for libraries +in some extra paths: .. code-block:: sh - $ readelf --dynamic build/lib.linux-x86_64-3.2/_pygit2.cpython-32.so | grep PATH + $ export LIBGIT2="/usr/local" + $ export LDFLAGS="-Wl,-rpath='$LIBGIT2/lib',--enable-new-dtags $LDFLAGS" + $ pip install pygit2 + +This compiles the pygit2 libraries with a ``RUNPATH``, which bakes extra +library search paths directly into the binaries (see the `ld man page`_ for +details). With ``RUNPATH`` compiled in, you won't have to use +``LD_LIBRARY_PATH``. You can check to ensure ``RUNPATH`` was set with +readelf_: + +.. code-block:: sh + + $ readelf --dynamic build/lib.linux-x86_64-3.2/_pygit2.cpython-32.so | grep PATH 0x000000000000000f (RPATH) Library rpath: [/usr/local/lib] 0x000000000000001d (RUNPATH) Library runpath: [/usr/local/lib] @@ -98,6 +134,51 @@ with readelf_: .. _ld man page: http://linux.die.net/man/1/ld .. _readelf: http://www.gnu.org/software/binutils/ + +The LIBGIT2 environment variable +================================ + +If libgit2 is installed in some non standard location, you will have to set the +``LIBGIT2`` environment variable before installing pygit2. This variables tells +pygit2 where libgit2 is installed. + + +Use case: libgit2 within a Virtualenv +------------------------------------- + +A use case for this is if you want to install libgit2 inside a virtualenv, so +you may have several virtualenvs with different versions of libgit2/pygit2, +isolated from each other. Or maybe you just don't have root access to install +libgit2 in the system. + +Create the virtualenv, activate it, and set the ``LIBGIT2`` environment +variable: + +.. code-block:: sh + + $ virtualenv venv + $ source venv/bin/activate + $ export LIBGIT2=$VIRTUAL_ENV + +Install libgit2 (see we define the installation prefix): + +.. code-block:: sh + + $ wget https://github.com/libgit2/libgit2/archive/v0.21.0.tar.gz + $ tar xzf v0.21.0.tar.gz + $ cd libgit2-0.21.0/ + $ cmake . -DCMAKE_INSTALL_PREFIX=$LIBGIT2 + $ make + $ make install + +Install pygit2: + +.. code-block:: sh + + $ pìp install cffi + $ pip install pygit2 + + Building on Windows =================================== @@ -110,14 +191,15 @@ from a bash shell: .. code-block:: sh - $ export LIBGIT2=C:/Dev/libgit2 - $ git clone -b master git://github.com/libgit2/libgit2.git - $ cd libgit2 - $ mkdir build - $ cd build - $ cmake .. -DSTDCALL=OFF -DCMAKE_INSTALL_PREFIX=$LIBGIT2 -G "Visual Studio 9 2008" - $ cmake --build . --config release --target install - $ ctest -v + $ export LIBGIT2=C:/Dev/libgit2 + $ wget https://github.com/libgit2/libgit2/archive/v0.21.0.tar.gz + $ tar xzf v0.21.0.tar.gz + $ cd libgit2-0.21.0/ + $ mkdir build + $ cd build + $ cmake .. -DSTDCALL=OFF -DCMAKE_INSTALL_PREFIX=$LIBGIT2 -G "Visual Studio 9 2008" + $ cmake --build . --config release --target install + $ ctest -v At this point, you're ready to execute the generic pygit2 installation steps described above.