openstack/deb-python-pygit2
Code Issues Proposed changes

docs: review the installation documentation

Browse Source
This commit is contained in:
J. David Ibáñez
2014-07-18 20:01:20 +02:00
parent 794e82c799
commit fdfda17121
3 changed files with 170 additions and 76 deletions
Download Patch File Download Diff File Expand all files Collapse all files

14
docs/development.rst Normal file
View File

@@ -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

4
docs/index.rst
View File

@@ -6,9 +6,6 @@
Welcome to pygit2's documentation! 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 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 implements the core of Git. Pygit2 works with Python 2.7, 3.2, 3.3, 3.4 and
pypy. pypy.
@@ -28,6 +25,7 @@ Start:
:maxdepth: 1 :maxdepth: 1
install install
development
recipes recipes
Usage guide: Usage guide:

194
docs/install.rst
View File

@@ -1,50 +1,80 @@
********************************************************************** **********************************************************************
How to Install Installation
********************************************************************** **********************************************************************
.. |lq| unicode:: U+00AB
.. contents:: .. |rq| unicode:: U+00BB
First you need to install the latest release of libgit2. If you clone .. contents:: Contents
the repository, make sure to use the ``master`` branch. You can find :local:
platform-specific instructions to build the library in the libgit2
website:
http://libgit2.github.com
Also, make sure you have Python 2.7 or 3.2+ installed together with the Python Requirements
development headers. ============
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 .. code-block:: sh
$ git clone git://github.com/libgit2/pygit2.git $ wget https://github.com/libgit2/libgit2/archive/v0.21.0.tar.gz
$ cd pygit2 $ tar xzf v0.21.0.tar.gz
$ python setup.py install $ cd libgit2-0.21.0/
$ python setup.py test $ cmake .
$ make
$ sudo make install
.. note:: A minor version of pygit2 must be used with the corresponding minor If this does not work for you, check the detailed instructions on building
version of libgit2. For example, pygit2 v0.21.x must be used with libgit2 libgit2 in various platforms, see
v0.21.0 https://libgit2.github.com/docs/guides/build-and-link/
Building on \*nix (including OS X) Once libgit2 is instaleld, deploying pygit2 should be a snap:
===================================
If you installed libgit2 and pygit2 in one of the usual places, you .. code-block:: sh
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 $ pìp install cffi
``/usr/lib``. To keep manually installed libraries separate, they are $ pip install pygit2
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 Troobleshooting
``/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: You may get an error like this one:
.. code-block:: sh .. code-block:: sh
@@ -55,38 +85,44 @@ using the default installation procedure (e.g. without specifying
from _pygit2 import * from _pygit2 import *
ImportError: libgit2.so.0: cannot open shared object file: No such file or directory ImportError: libgit2.so.0: cannot open shared object file: No such file or directory
The following recipe shows how to install libgit2 and pygit2 on these It means the linker is not able to find the libgit2 library.
systems. First, download and install libgit2 (following the
instructions in the libgit2 ``README.md``): 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 .. code-block:: sh
$ git clone -b master git://github.com/libgit2/libgit2.git ...
$ mkdir libgit2/build $ cmake .
$ cd libgit2/build $ make
$ cmake .. $ sudo make install
$ cmake --build . ...
$ sudo cmake --build . --target install $ sudo ldconfig
$ cd ../.. ...
$ pip install cffi
$ pip install pygit2
Now, download and install pygit2. You will probably have to set the Now it should work. If it does not...
``LIBGIT2`` environment variable so the compiler can find the libgit2
headers and libraries: 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 .. code-block:: sh
$ git clone git://github.com/libgit2/pygit2.git
$ cd pygit2
$ export LIBGIT2="/usr/local" $ export LIBGIT2="/usr/local"
$ export LDFLAGS="-Wl,-rpath='$LIBGIT2/lib',--enable-new-dtags $LDFLAGS" $ export LDFLAGS="-Wl,-rpath='$LIBGIT2/lib',--enable-new-dtags $LDFLAGS"
$ python setup.py build $ pip install pygit2
$ sudo python setup.py install
This compiles the pygit2 libraries with a ``RUNPATH``, which bakes This compiles the pygit2 libraries with a ``RUNPATH``, which bakes extra
extra library search paths directly into the binaries (see the `ld man library search paths directly into the binaries (see the `ld man page`_ for
page`_ for details). With ``RUNPATH`` compiled in, you won't have to details). With ``RUNPATH`` compiled in, you won't have to use
use ``LD_LIBRARY_PATH``. You can check to ensure ``RUNPATH`` was set ``LD_LIBRARY_PATH``. You can check to ensure ``RUNPATH`` was set with
with readelf_: readelf_:
.. code-block:: sh .. code-block:: sh
@@ -98,6 +134,51 @@ with readelf_:
.. _ld man page: http://linux.die.net/man/1/ld .. _ld man page: http://linux.die.net/man/1/ld
.. _readelf: http://www.gnu.org/software/binutils/ .. _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 Building on Windows
=================================== ===================================
@@ -111,8 +192,9 @@ from a bash shell:
.. code-block:: sh .. code-block:: sh
$ export LIBGIT2=C:/Dev/libgit2 $ export LIBGIT2=C:/Dev/libgit2
$ git clone -b master git://github.com/libgit2/libgit2.git $ wget https://github.com/libgit2/libgit2/archive/v0.21.0.tar.gz
$ cd libgit2 $ tar xzf v0.21.0.tar.gz
$ cd libgit2-0.21.0/
$ mkdir build $ mkdir build
$ cd build $ cd build
$ cmake .. -DSTDCALL=OFF -DCMAKE_INSTALL_PREFIX=$LIBGIT2 -G "Visual Studio 9 2008" $ cmake .. -DSTDCALL=OFF -DCMAKE_INSTALL_PREFIX=$LIBGIT2 -G "Visual Studio 9 2008"