/usr/share/doc/python-pygit2-doc/html/_sources/install.rst.txt is in python-pygit2-doc 0.26.2-2.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 | **********************************************************************
Installation
**********************************************************************
.. |lq| unicode:: U+00AB
.. |rq| unicode:: U+00BB
.. contents:: Contents
:local:
Requirements
============
- Python 2.7, 3.3+ or PyPy 2.6+ (including the development headers)
- Libgit2 v0.26.x
- cffi 1.0+
- six
- tox (optional)
Optional libgit2 dependecies to support ssh and https:
- https: WinHTTP (Windows), SecureTransport (OS X) or OpenSSL.
- ssh: libssh2, pkg-config
It should work with older versions of cffi and PyPy, but using cffi 1.0+
(and PyPy 2.6+) is strongly encouraged.
.. warning::
One common mistake users do is to choose incompatible versions of libgit2
and pygit2. See below for a reference table of compatible versions. Double
check the versions do match before filing a bug report.
Version numbers
---------------
The version number 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.26.0 | 0.25.0, 0.25.1 | 0.24.0, 0.24.1, 0.24.2 |
+-----------+------------------------+----------------+------------------------+
|**pygit2** | 0.26.0, 0.26.1, 0.26.2 | 0.25.0, 0.25.1 | 0.24.0, 0.24.1, 0.24.2 |
+-----------+------------------------+----------------+------------------------+
.. 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
=============
To install the latest version of libgit2 system wide, in the ``/usr/local``
directory, do:
.. code-block:: sh
$ wget https://github.com/libgit2/libgit2/archive/v0.26.0.tar.gz
$ tar xzf v0.26.0.tar.gz
$ cd libgit2-0.26.0/
$ cmake .
$ make
$ sudo make install
.. seealso::
For detailed instructions on building libgit2 check
https://libgit2.github.com/docs/guides/build-and-link/
Now install pygit2, and then verify it is correctly installed:
.. code-block:: sh
$ pip install pygit2
...
$ python -c 'import pygit2'
Troubleshooting
---------------
The verification step may fail if the dynamic linker does not find the libgit2
library:
.. code-block:: sh
$ python -c 'import pygit2'
Traceback (most recent call last):
File "<string>", line 1, in <module>
File "pygit2/__init__.py", line 29, in <module>
from _pygit2 import *
ImportError: libgit2.so.0: cannot open shared object file: No such file or directory
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``:
.. code-block:: sh
$ sudo ldconfig
$ python -c 'import pygit2'
If it still does not work, please open an issue at
https://github.com/libgit2/pygit2/issues, I would like to know about it.
Build options
=============
``LIBGIT2`` -- If you install libgit2 in an unusual place, you will need to set
the ``LIBGIT2`` environment variable before installing pygit2. This variable
tells pygit2 where libgit2 is installed. We will see a concrete example later,
when explaining how to install libgit2 within a virtual environment.
``LIBGIT2_LIB`` -- This is a more rarely used build option, it allows to
override the library directory where libgit2 is installed, useful if different
from from ``$LIBGIT2/lib``.
libgit2 within a virtual environment
====================================
This is how to install both libgit2 and pygit2 within a virtual environment.
This is useful if you don't have root acces to install libgit2 system wide.
Or if you wish to have different versions of libgit2/pygit2 installed in
different virtual environments, isolated from each other.
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.26.0.tar.gz
$ tar xzf v0.26.0.tar.gz
$ cd libgit2-0.26.0/
$ cmake . -DCMAKE_INSTALL_PREFIX=$LIBGIT2
$ make
$ make install
Install pygit2:
.. code-block:: sh
$ export LDFLAGS="-Wl,-rpath='$LIBGIT2/lib',--enable-new-dtags $LDFLAGS"
$ pip install pygit2
$ python -c 'import pygit2'
The run-path
------------------------------------------
Did you notice we set the `rpath <http://en.wikipedia.org/wiki/Rpath>`_ before
installing pygit2? Since libgit2 is installed in a non standard location, the
dynamic linker will not find it at run-time, and ``lddconfig`` will not help
this time.
So you need to either set ``LD_LIBRARY_PATH`` before using pygit2, like:
.. code-block:: sh
$ export LD_LIBRARY_PATH=$LIBGIT2/lib
$ python -c 'import pygit2'
Or, like we have done in the instructions above, use the `rpath
<http://en.wikipedia.org/wiki/Rpath>`_, it hard-codes extra search paths within
the pygit2 extension modules, so you don't need to set ``LD_LIBRARY_PATH``
everytime. Verify yourself if curious:
.. code-block:: sh
$ readelf --dynamic lib/python2.7/site-packages/pygit2-0.26.0-py2.7-linux-x86_64.egg/_pygit2.so | grep PATH
0x000000000000001d (RUNPATH) Library runpath: [/tmp/venv/lib]
Installing on Windows
===================================
`pygit2` for Windows is packaged into wheels and can be easily
installed with `pip`:
pip install pygit2
For development it is also possible to build `pygit2` with `libgit2`
from sources. `libgit2` location is specified by the ``LIBGIT2``
environment variable. `libgit2` should be built in "__cdecl" mode.
The following recipe shows you how to do it from a bash shell:
.. code-block:: sh
$ export LIBGIT2=C:/Dev/libgit2
$ git clone --depth=1 -b maint/v0.26 https://github.com/libgit2/libgit2.git
$ cd libgit2
$ 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 at the start of this page.
Installing on OS X
===================================
.. note::
You will need the `XCode <https://developer.apple.com/xcode/>`_ Developer
Tools from Apple. This free download from the Mac App Store will provide the
clang compiler needed for the installation of pygit2.
This section was tested on OS X 10.9 Mavericks and OS X 10.10 Yosemite with
Python 3.3 in a virtual environment.
The easiest way is to first install libgit2 with the `Homebrew <http://brew.sh>`_
package manager and then use pip3 for pygit2. The following example assumes that
XCode and Hombrew are already installed.
.. code-block:: sh
$ brew update
$ brew install libgit2
$ pip3 install pygit2
|