Skip to content

Commit dec33c2

Browse files
henryiiihenryiii
authored
docs: installing section (#2494)
* docs: installing section * docs: feedback from @wjakob
1 parent d3c999c commit dec33c2

File tree

3 files changed

+109
-15
lines changed

3 files changed

+109
-15
lines changed

‎docs/compiling.rst

Lines changed: 3 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -523,23 +523,11 @@ build system that works on all platforms including Windows.
523523
contains one (which will lead to a segfault).
524524

525525

526-
Building with vcpkg
526+
Building with Bazel
527527
===================
528-
You can download and install pybind11 using the Microsoft `vcpkg
529-
<https://github.com/Microsoft/vcpkg/>`_ dependency manager:
530528

531-
.. code-block:: bash
532-
533-
git clone https://github.com/Microsoft/vcpkg.git
534-
cd vcpkg
535-
./bootstrap-vcpkg.sh
536-
./vcpkg integrate install
537-
vcpkg install pybind11
538-
539-
The pybind11 port in vcpkg is kept up to date by Microsoft team members and
540-
community contributors. If the version is out of date, please `create an issue
541-
or pull request <https://github.com/Microsoft/vcpkg/>`_ on the vcpkg
542-
repository.
529+
You can build with the Bazel build system using the `pybind11_bazel
530+
<https://github.com/pybind/pybind11_bazel>`_ repository.
543531

544532
Generating binding code automatically
545533
=====================================

‎docs/index.rst

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,8 @@
55
pybind11 --- Seamless operability between C++11 and Python
66
==========================================================
77

8+
Source code available at `github.com/pybind/pybind11 <https://github.com/pybind/pybind11>`_.
9+
810
.. only: not latex
911
1012
Contents:
@@ -20,6 +22,7 @@ pybind11 --- Seamless operability between C++11 and Python
2022
:caption: The Basics
2123
:maxdepth: 2
2224

25+
installing
2326
basics
2427
classes
2528
compiling

‎docs/installing.rst

Lines changed: 103 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,103 @@
1+
.. _installing:
2+
3+
Installing the library
4+
######################
5+
6+
There are several ways to get the pybind11 source, which lives at
7+
`pybind/pybind11 on GitHub <https://github.com/pybind/pybind11>`_. The pybind11
8+
developers recommend one of the first three ways listed here, submodule, PyPI,
9+
or conda-forge, for obtaining pybind11.
10+
11+
Include as a submodule
12+
======================
13+
14+
When you are working on a project in Git, you can use the pybind11 repository
15+
as a submodule. From your git repository, use:
16+
17+
.. code-block:: bash
18+
19+
git submodule add ../../pybind/pybind11 extern/pybind11 -b stable
20+
git submodule update --init
21+
22+
This assumes you are placing your dependencies in ``extern/``, and that you are
23+
using GitHub; if you are not using GitHub, use the full https or ssh URL
24+
instead of the relative URL ``../../pybind/pybind11`` above. Some other servers
25+
also require the ``.git`` extension (GitHub does not).
26+
27+
From here, you can now include ``extern/pybind11/include``, or you can use
28+
the various integration tools (see :ref:`compiling`) pybind11 provides directly
29+
from the local folder.
30+
31+
Include with PyPI
32+
=================
33+
34+
You can download the sources and CMake files as a Python package from PyPI
35+
using Pip. Just use:
36+
37+
.. code-block:: bash
38+
39+
pip install pybind11
40+
41+
This will provide pybind11 in a standard Python package format. If you want
42+
pybind11 available directly in your environment root, you can use:
43+
44+
.. code-block:: bash
45+
46+
pip install "pybind11[global]"
47+
48+
This is not recommended if you are installing with your system Python, as it
49+
will add files to ``/usr/local/include/pybind11`` and
50+
``/usr/local/share/cmake/pybind11``, so unless that is what you want, it is
51+
recommended only for use in virtual environments or your ``pyproject.toml``
52+
file (see :ref:`compiling`).
53+
54+
Include with conda-forge
55+
========================
56+
57+
You can use pybind11 with conda packaging via `conda-forge
58+
<https://github.com/conda-forge/pybind11-feedstock>`_:
59+
60+
.. code-block:: bash
61+
62+
conda install -c conda-forge pybind11
63+
64+
65+
Include with vcpkg
66+
==================
67+
You can download and install pybind11 using the Microsoft `vcpkg
68+
<https://github.com/Microsoft/vcpkg/>`_ dependency manager:
69+
70+
.. code-block:: bash
71+
72+
git clone https://github.com/Microsoft/vcpkg.git
73+
cd vcpkg
74+
./bootstrap-vcpkg.sh
75+
./vcpkg integrate install
76+
vcpkg install pybind11
77+
78+
The pybind11 port in vcpkg is kept up to date by Microsoft team members and
79+
community contributors. If the version is out of date, please `create an issue
80+
or pull request <https://github.com/Microsoft/vcpkg/>`_ on the vcpkg
81+
repository.
82+
83+
Global install with brew
84+
========================
85+
86+
The brew package manager (Homebrew on macOS, or Linuxbrew on Linux) has a
87+
`pybind11 package
88+
<https://github.com/Homebrew/homebrew-core/blob/master/Formula/pybind11.rb>`_.
89+
To install:
90+
91+
.. code-block:: bash
92+
93+
brew install pybind11
94+
95+
.. We should list Conan, and possibly a few other C++ package managers (hunter,
96+
.. perhaps). Conan has a very clean CMake integration that would be good to show.
97+
98+
Other options
99+
=============
100+
101+
Other locations you can find pybind11 are `listed here
102+
<https://repology.org/project/python:pybind11/versions>`_; these are maintained
103+
by various packagers and the community.

0 commit comments

Comments
 (0)