openstack/deb-python-pygit2
Code Issues Proposed changes

README.rst: document non-standard linking on *nix

Browse Source 
There have been a few comments on pygit2's issue tracker about linking
problems on Unix/Linux [1].  David suggested that a README comment
might be in order, so here it is.

I think that people new to *nix linking should probably just stick to
installing to standard locations, since a short README blurb is never
going to do justice to a subject that probably deserves it's own
chapter.  Instead of explaining what's going on, I just give a quick
recipe for building and installing libgit2 under /usr/local (the
default location), and then building pygit2 against that libgit2
(using RUNPATH).

[1]: https://github.com/libgit2/pygit2/issues/134
This commit is contained in:
W. Trevor King 2012-12-13 08:43:18 -05:00
parent 0acb7df564
commit 1e8b84a5b5
1 changed files with 61 additions and 0 deletions

61
README.rst

@ -28,6 +28,67 @@ When those are installed, you can install pygit2::
$ python setup.py install
$ python setup.py test
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:
$ 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
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``)::
$ git clone git://github.com/libgit2/libgit2.git
$ mkdir libgit2/build
$ cd libgit2/build
$ cmake ..
$ cmake --build .
$ sudo cmake --build . --target install
$ cd ../..
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.
$ 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
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_::
$ 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]
.. _Shared libraries: http://tldp.org/HOWTO/Program-Library-HOWTO/shared-libraries.html
.. _ld man page: http://linux.die.net/man/1/ld
.. _readelf: http://www.gnu.org/software/binutils/
Building on Windows
-------------------