@@ -53,6 +53,33 @@ derivative works thereof, in binary and source code form.
53
53
54
54
## Development of pybind11
55
55
56
+ ### Quick setup
57
+
58
+ To setup a quick development environment, use [ ` nox ` ] ( https://nox.thea.codes ) .
59
+ This will allow you to do some common tasks with minimal setup effort, but will
60
+ take more time to run and be less flexible than a full development environment.
61
+ If you use [ ` pipx run nox ` ] ( https://pipx.pypa.io ) , you don't even need to
62
+ install ` nox ` . Examples:
63
+
64
+ ``` bash
65
+ # List all available sessions
66
+ nox -l
67
+
68
+ # Run linters
69
+ nox -s lint
70
+
71
+ # Run tests on Python 3.9
72
+ nox -s tests-3.9
73
+
74
+ # Build and preview docs
75
+ nox -s docs -- serve
76
+
77
+ # Build SDists and wheels
78
+ nox -s build
79
+ ```
80
+
81
+ ### Full setup
82
+
56
83
To setup an ideal development environment, run the following commands on a
57
84
system with CMake 3.14+:
58
85
@@ -66,19 +93,18 @@ cmake --build build -j4
66
93
67
94
Tips:
68
95
69
- * You can use ` virtualenv ` (from PyPI) instead of ` venv ` (which is Python 3
70
- only).
96
+ * You can use ` virtualenv ` (faster, from PyPI) instead of ` venv ` .
71
97
* You can select any name for your environment folder; if it contains "env" it
72
98
will be ignored by git.
73
- * If you don’ t have CMake 3.14+, just add “ cmake” to the pip install command.
99
+ * If you don' t have CMake 3.14+, just add " cmake" to the pip install command.
74
100
* You can use ` -DPYBIND11_FINDPYTHON=ON ` to use FindPython on CMake 3.12+
75
101
* In classic mode, you may need to set ` -DPYTHON_EXECUTABLE=/path/to/python ` .
76
102
FindPython uses ` -DPython_ROOT_DIR=/path/to ` or
77
103
` -DPython_EXECUTABLE=/path/to/python ` .
78
104
79
105
### Configuration options
80
106
81
- In CMake, configuration options are given with “-D” . Options are stored in the
107
+ In CMake, configuration options are given with "-D" . Options are stored in the
82
108
build directory, in the ` CMakeCache.txt ` file, so they are remembered for each
83
109
build directory. Two selections are special - the generator, given with ` -G ` ,
84
110
and the compiler, which is selected based on environment variables ` CXX ` and
@@ -88,12 +114,12 @@ after the initial run.
88
114
The valid options are:
89
115
90
116
* ` -DCMAKE_BUILD_TYPE ` : Release, Debug, MinSizeRel, RelWithDebInfo
91
- * ` -DPYBIND11_FINDPYTHON=ON ` : Use CMake 3.12+’ s FindPython instead of the
117
+ * ` -DPYBIND11_FINDPYTHON=ON ` : Use CMake 3.12+' s FindPython instead of the
92
118
classic, deprecated, custom FindPythonLibs
93
119
* ` -DPYBIND11_NOPYTHON=ON ` : Disable all Python searching (disables tests)
94
120
* ` -DBUILD_TESTING=ON ` : Enable the tests
95
121
* ` -DDOWNLOAD_CATCH=ON ` : Download catch to build the C++ tests
96
- * ` -DOWNLOAD_EIGEN =ON ` : Download Eigen for the NumPy tests
122
+ * ` -DDOWNLOAD_EIGEN =ON ` : Download Eigen for the NumPy tests
97
123
* ` -DPYBIND11_INSTALL=ON/OFF ` : Enable the install target (on by default for the
98
124
master project)
99
125
* ` -DUSE_PYTHON_INSTALL_DIR=ON ` : Try to install into the python dir
@@ -109,7 +135,7 @@ The valid options are:
109
135
* Use ` -G ` and the name of a generator to use something different. `cmake
110
136
--help` lists the generators available.
111
137
- On Unix, setting ` CMAKE_GENERATER=Ninja ` in your environment will give
112
- you automatic mulithreading on all your CMake projects!
138
+ you automatic multithreading on all your CMake projects!
113
139
* Open the ` CMakeLists.txt ` with QtCreator to generate for that IDE.
114
140
* You can use ` -DCMAKE_EXPORT_COMPILE_COMMANDS=ON ` to generate the ` .json ` file
115
141
that some tools expect.
@@ -126,13 +152,26 @@ cmake --build build --target check
126
152
` --target ` can be spelled ` -t ` in CMake 3.15+. You can also run individual
127
153
tests with these targets:
128
154
129
- * ` pytest ` : Python tests only
155
+ * ` pytest ` : Python tests only, using the
156
+ [ pytest] ( https://docs.pytest.org/en/stable/ ) framework
130
157
* ` cpptest ` : C++ tests only
131
158
* ` test_cmake_build ` : Install / subdirectory tests
132
159
133
160
If you want to build just a subset of tests, use
134
- ` -DPYBIND11_TEST_OVERRIDE="test_callbacks.cpp;test_pickling.cpp" ` . If this is
135
- empty, all tests will be built.
161
+ ` -DPYBIND11_TEST_OVERRIDE="test_callbacks;test_pickling" ` . If this is
162
+ empty, all tests will be built. Tests are specified without an extension if they need both a .py and
163
+ .cpp file.
164
+
165
+ You may also pass flags to the ` pytest ` target by editing ` tests/pytest.ini ` or
166
+ by using the ` PYTEST_ADDOPTS ` environment variable
167
+ (see [ ` pytest ` docs] ( https://docs.pytest.org/en/2.7.3/customize.html#adding-default-options ) ). As an example:
168
+
169
+ ``` bash
170
+ env PYTEST_ADDOPTS=" --capture=no --exitfirst" \
171
+ cmake --build build --target pytest
172
+ # Or using abbreviated flags
173
+ env PYTEST_ADDOPTS=" -s -x" cmake --build build --target pytest
174
+ ```
136
175
137
176
### Formatting
138
177
@@ -164,18 +203,46 @@ name, pre-commit):
164
203
pre-commit install
165
204
```
166
205
206
+ ### Clang-Format
207
+
208
+ As of v2.6.2, pybind11 ships with a [ ` clang-format ` ] [ clang-format ]
209
+ configuration file at the top level of the repo (the filename is
210
+ ` .clang-format ` ). Currently, formatting is NOT applied automatically, but
211
+ manually using ` clang-format ` for newly developed files is highly encouraged.
212
+ To check if a file needs formatting:
213
+
214
+ ``` bash
215
+ clang-format -style=file --dry-run some.cpp
216
+ ```
217
+
218
+ The output will show things to be fixed, if any. To actually format the file:
219
+
220
+ ``` bash
221
+ clang-format -style=file -i some.cpp
222
+ ```
223
+
224
+ Note that the ` -style-file ` option searches the parent directories for the
225
+ ` .clang-format ` file, i.e. the commands above can be run in any subdirectory
226
+ of the pybind11 repo.
227
+
167
228
### Clang-Tidy
168
229
169
- To run Clang tidy, the following recipe should work. Files will be modified in
170
- place, so you can use git to monitor the changes.
230
+ [ ` clang-tidy ` ] [ clang-tidy ] performs deeper static code analyses and is
231
+ more complex to run, compared to ` clang-format ` , but support for ` clang-tidy `
232
+ is built into the pybind11 CMake configuration. To run ` clang-tidy ` , the
233
+ following recipe should work. Run the ` docker ` command from the top-level
234
+ directory inside your pybind11 git clone. Files will be modified in place,
235
+ so you can use git to monitor the changes.
171
236
172
237
``` bash
173
- docker run --rm -v $PWD :/pybind11 -it silkeh/clang:10
174
- apt-get update && apt-get install python3-dev python3-pytest
175
- cmake -S pybind11/ -B build -DCMAKE_CXX_CLANG_TIDY=" $( which clang-tidy) ;-fix "
176
- cmake --build build
238
+ docker run --rm -v $PWD :/mounted_pybind11 -it silkeh/clang:15-bullseye
239
+ apt-get update && apt-get install -y git python3-dev python3-pytest
240
+ cmake -S /mounted_pybind11/ -B build -DCMAKE_CXX_CLANG_TIDY=" $( which clang-tidy) ;--use-color " -DDOWNLOAD_EIGEN=ON -DDOWNLOAD_CATCH=ON -DCMAKE_CXX_STANDARD=17
241
+ cmake --build build -j 2
177
242
```
178
243
244
+ You can add ` --fix ` to the options list if you want.
245
+
179
246
### Include what you use
180
247
181
248
To run include what you use, install (` brew install include-what-you-use ` on
@@ -186,12 +253,12 @@ cmake -S . -B build-iwyu -DCMAKE_CXX_INCLUDE_WHAT_YOU_USE=$(which include-what-y
186
253
cmake --build build
187
254
```
188
255
189
- The report is sent to stderr; you can pip it into a file if you wish.
256
+ The report is sent to stderr; you can pipe it into a file if you wish.
190
257
191
258
### Build recipes
192
259
193
260
This builds with the Intel compiler (assuming it is in your path, along with a
194
- recent CMake and Python 3 ):
261
+ recent CMake and Python):
195
262
196
263
``` bash
197
264
python3 -m venv venv
@@ -313,6 +380,8 @@ if you really want to.
313
380
314
381
315
382
[ pre-commit ] : https://pre-commit.com
383
+ [ clang-format ] : https://clang.llvm.org/docs/ClangFormat.html
384
+ [ clang-tidy ] : https://clang.llvm.org/extra/clang-tidy/
316
385
[ pybind11.readthedocs.org ] : http://pybind11.readthedocs.org/en/latest
317
386
[ issue tracker ] : https://github.com/pybind/pybind11/issues
318
387
[ gitter ] : https://gitter.im/pybind/Lobby
0 commit comments