Skip to content

docs: update install doc #1426

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: master
Choose a base branch
from
Open

docs: update install doc #1426

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
127 changes: 72 additions & 55 deletions docs/install.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,10 +2,6 @@
Installation
**********************************************************************

.. |lq| unicode:: U+00AB
.. |rq| unicode:: U+00BB


.. contents:: Contents
:local:

Expand All @@ -17,8 +13,8 @@ Install pygit2:

.. code-block:: sh

$ pip install -U pip
$ pip install pygit2
pip install -U pip
pip install pygit2

The line above will install binary wheels if available in your platform.

Expand All @@ -33,12 +29,12 @@ If you get the error::
fatal error: git2.h: No such file or directory

It means that pip did not find a binary wheel for your platform, so it tried to
build from source, but it failed because it could not find the libgit2 headers.
build from source. It failed to build because it could not find the libgit2 headers.
Then:

- Verify pip is updated
- Verify there is a binary wheel of pygit2 for your platform
- Otherwise install from the source distribution
- Otherwise `install from the source distribution`_

Caveats:

Expand All @@ -58,12 +54,12 @@ Python requirements (these are specified in ``setup.py``):
- cffi 2.0 or later

Libgit2 **v1.9.x**; binary wheels already include libgit2, so you only need to
worry about this if you install the source package.
worry about this if you `install from the source distribution`_.

Optional libgit2 dependencies to support ssh and https:

- https: WinHTTP (Windows), SecureTransport (OS X) or OpenSSL.
- ssh: libssh2 1.9.0 or later, pkg-config
- ssh: libssh2 1.9.1 or later, pkg-config

To run the tests:

Expand All @@ -72,8 +68,9 @@ To run the tests:
Version numbers
===============

The version number of pygit2 is composed of three numbers separated by dots
|lq| *major.medium.minor* |rq|:
The version number of pygit2 is composed of three numbers separated by dots::

<major>.<medium>.<minor>

- *major* will always be 1 (until we release 2.0 in a far undefined future)
- *medium* will increase whenever we make breaking changes, or upgrade to new
Expand All @@ -86,6 +83,8 @@ of Python and the required libgit2 version.
+-------------+----------------+------------+
| pygit2 | Python | libgit2 |
+-------------+----------------+------------+
| 1.19 | 3.10+, 3.14t | 1.9 |
+-------------+----------------+------------+
Comment on lines +86 to +87
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This should only get merged once the next release is deployed. @jdavid Please let me know if the next release will not be tagged as v1.19.0

| 1.17 - 1.18 | 3.10 - 3.13 | 1.9 |
+-------------+----------------+------------+
| 1.16 | 3.10 - 3.13 | 1.8 |
Expand Down Expand Up @@ -139,33 +138,41 @@ lockstep with libgit2, e.g. pygit2 0.28.x worked with libgit2 0.28.x
Advanced
===========================

.. _install from the source distribution:

Install libgit2 from source
---------------------------

Installing from source requires

* a C compiler (such as gcc)
* the CPython API headers (typically in a ``apt`` package named ``python3-dev``)

To install the latest version of libgit2 system wide, in the ``/usr/local``
directory, do:

.. code-block:: sh
:caption: On Linux using bash

$ wget https://github.com/libgit2/libgit2/archive/refs/tags/v1.9.0.tar.gz -O libgit2-1.9.0.tar.gz
$ tar xzf libgit2-1.9.0.tar.gz
$ cd libgit2-1.9.0/
$ cmake .
$ make
$ sudo make install
wget https://github.com/libgit2/libgit2/archive/refs/tags/v1.9.1.tar.gz -O libgit2-1.9.1.tar.gz
tar -xzf libgit2-1.9.1.tar.gz
cd libgit2-1.9.1/
cmake .
make
sudo make install

.. seealso::

For detailed instructions on building libgit2 check
https://libgit2.github.com/docs/guides/build-and-link/
https://libgit2.org/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'
pip install pygit2
# ...
python -c 'import pygit2'


Troubleshooting
Expand All @@ -174,9 +181,9 @@ Troubleshooting
The verification step may fail if the dynamic linker does not find the libgit2
library:

.. code-block:: sh
.. code-block:: text

$ python -c 'import pygit2'
python -c 'import pygit2'
Traceback (most recent call last):
File "<string>", line 1, in <module>
File "pygit2/__init__.py", line 29, in <module>
Expand All @@ -188,9 +195,10 @@ the ``/usr/local/lib`` directory, but the linker does not look for it there. To
fix this call ``ldconfig``:

.. code-block:: sh
:caption: On Linux using bash

$ sudo ldconfig
$ python -c 'import pygit2'
sudo ldconfig
python -c 'import pygit2'

If it still does not work, please open an issue at
https://github.com/libgit2/pygit2/issues
Expand Down Expand Up @@ -222,29 +230,32 @@ Create the virtualenv, activate it, and set the ``LIBGIT2`` environment
variable:

.. code-block:: sh
:caption: On Linux using bash

$ virtualenv venv
$ source venv/bin/activate
$ export LIBGIT2=$VIRTUAL_ENV
virtualenv venv
source venv/bin/activate
export LIBGIT2=$VIRTUAL_ENV

Install libgit2 (see we define the installation prefix):

.. code-block:: sh
:caption: On Linux using bash

$ wget https://github.com/libgit2/libgit2/archive/refs/tags/v1.9.0.tar.gz -O libgit2-1.9.0.tar.gz
$ tar xzf libgit2-1.9.0.tar.gz
$ cd libgit2-1.9.0/
$ cmake . -DCMAKE_INSTALL_PREFIX=$LIBGIT2
$ cmake --build . --target install
wget https://github.com/libgit2/libgit2/archive/refs/tags/v1.9.1.tar.gz -O libgit2-1.9.1.tar.gz
tar xzf libgit2-1.9.1.tar.gz
cd libgit2-1.9.1/
cmake . -DCMAKE_INSTALL_PREFIX=$LIBGIT2
cmake --build . --target install

Install pygit2:

.. code-block:: sh
:caption: On Linux using bash

$ export LDFLAGS="-Wl,-rpath,'$LIBGIT2/lib',--enable-new-dtags $LDFLAGS"
export LDFLAGS="-Wl,-rpath,'$LIBGIT2/lib',--enable-new-dtags $LDFLAGS"
# on OSX: export LDFLAGS="-Wl,-rpath,'$LIBGIT2/lib' $LDFLAGS"
$ pip install pygit2
$ python -c 'import pygit2'
pip install pygit2
python -c 'import pygit2'


The run-path
Expand All @@ -258,43 +269,49 @@ this time.
So you need to either set ``LD_LIBRARY_PATH`` before using pygit2, like:

.. code-block:: sh
:caption: On Linux using bash

$ export LD_LIBRARY_PATH=$LIBGIT2/lib
$ python -c 'import pygit2'
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``
every time. Verify yourself if curious:

.. code-block:: sh
:caption: On Linux using bash

$ readelf --dynamic lib/python2.7/site-packages/pygit2-0.27.0-py2.7-linux-x86_64.egg/pygit2/_pygit2.so | grep PATH
readelf --dynamic lib/python2.7/site-packages/pygit2-0.27.0-py2.7-linux-x86_64.egg/pygit2/_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`:
``pygit2`` for Windows is packaged into wheels and can be easily installed with
``pip``:

.. code-block:: console

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. The following recipe shows you how to do it from a bash shell:
For development it is also possible to build ``pygit2`` with ``libgit2`` from
sources. ``libgit2`` location is specified by the ``LIBGIT2`` environment
variable. The following recipe shows you how to do it:

.. code-block:: sh
.. code-block:: pwsh
:caption: On Windows using PowerShell (and CMake v3.21 or newer)

git clone --depth=1 -b v1.9.1 https://github.com/libgit2/libgit2.git
$env:CMAKE_INSTALL_PREFIX = "C:/Dev/libgit2"
$env:CMAKE_GENERATOR = "Visual Studio 17 2022"
$env:CMAKE_GENERATOR_PLATFORM = "x64" # or "Win32" or "ARM64"
cmake -B libgit2/build -S libgit2
cmake --build libgit2/build --config release --target install

$ export LIBGIT2=C:/Dev/libgit2
$ git clone --depth=1 -b v1.9.0 https://github.com/libgit2/libgit2.git
$ cd libgit2
$ cmake . -DCMAKE_INSTALL_PREFIX=$LIBGIT2 -G "Visual Studio 14 Win64"
$ cmake --build . --config release --target install
$ ctest -v
# let pip know where to find libgit2 when building pygit2
$env:LIBGIT2 = "$env:CMAKE_INSTALL_PREFIX"

At this point, you're ready to execute the generic `pygit2` installation steps
described at the start of this page.
Expand All @@ -321,8 +338,8 @@ XCode and Homebrew are already installed.

.. code-block:: sh

$ brew update
$ brew install libgit2
$ pip3 install pygit2
brew update
brew install libgit2
pip3 install pygit2

To build from a non-Homebrew libgit2 follow the guide in `libgit2 within a virtual environment`_.
2 changes: 2 additions & 0 deletions docs/requirements.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,2 @@
sphinx
sphinx-rtd-theme