From 53f71d255df5427538454c68d9cca026aa66693e Mon Sep 17 00:00:00 2001 From: Henry Schreiner Date: Mon, 10 Aug 2020 12:59:24 -0400 Subject: [PATCH 1/6] docs: move helpers to .github where allowed --- CONTRIBUTING.md => .github/CONTRIBUTING.md | 0 ISSUE_TEMPLATE.md => .github/ISSUE_TEMPLATE.md | 0 LICENSE | 2 +- 3 files changed, 1 insertion(+), 1 deletion(-) rename CONTRIBUTING.md => .github/CONTRIBUTING.md (100%) rename ISSUE_TEMPLATE.md => .github/ISSUE_TEMPLATE.md (100%) diff --git a/CONTRIBUTING.md b/.github/CONTRIBUTING.md similarity index 100% rename from CONTRIBUTING.md rename to .github/CONTRIBUTING.md diff --git a/ISSUE_TEMPLATE.md b/.github/ISSUE_TEMPLATE.md similarity index 100% rename from ISSUE_TEMPLATE.md rename to .github/ISSUE_TEMPLATE.md diff --git a/LICENSE b/LICENSE index 6f15578cc4..e466b0dfda 100644 --- a/LICENSE +++ b/LICENSE @@ -25,5 +25,5 @@ CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. -Please also refer to the file CONTRIBUTING.md, which clarifies licensing of +Please also refer to the file .github/CONTRIBUTING.md, which clarifies licensing of external contributions to this project including patches, pull requests, etc. From a96854eb27e2a180b3dcb2ea3b80d5e0ef5989a4 Mon Sep 17 00:00:00 2001 From: Henry Schreiner Date: Mon, 10 Aug 2020 13:24:54 -0400 Subject: [PATCH 2/6] docs: more guidelines in CONTRIBUTING --- .github/CONTRIBUTING.md | 130 ++++++++++++++++++++++++++++++++++++---- 1 file changed, 120 insertions(+), 10 deletions(-) diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index 9dd3bd6f6c..007ce8b45b 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -3,11 +3,9 @@ sections on how to contribute code and bug reports. ### Reporting bugs -At the moment, this project is run in the spare time of a single person -([Wenzel Jakob](http://rgl.epfl.ch/people/wjakob)) with very limited resources -for issue tracker tickets. Thus, before submitting a question or bug report, -please take a moment of your time and ensure that your issue isn't already -discussed in the project documentation provided at +Before submitting a question or bug report, please take a moment of your time +and ensure that your issue isn't already discussed in the project documentation +provided at [http://pybind11.readthedocs.org/en/latest](http://pybind11.readthedocs.org/en/latest). Assuming that you have identified a previously unknown problem or an important @@ -17,7 +15,8 @@ isolate the function(s) that cause breakage, submit matched and complete C++ and Python snippets that can be easily compiled and run on my end. ## Pull requests -Contributions are submitted, reviewed, and accepted using Github pull requests. + +Contributions are submitted, reviewed, and accepted using GitHub pull requests. Please refer to [this article](https://help.github.com/articles/using-pull-requests) for details and adhere to the following rules to make the process as smooth as possible: @@ -25,10 +24,10 @@ adhere to the following rules to make the process as smooth as possible: * Make a new branch for every feature you're working on. * Make small and clean pull requests that are easy to review but make sure they do add value by themselves. -* Add tests for any new functionality and run the test suite (``make pytest``) - to ensure that no existing features break. -* Please run [``pre-commit``][pre-commit] to check your code matches the - project style. (Note that ``gawk`` is required.) Use `pre-commit run +* Add tests for any new functionality and run the test suite (`cmake --build + build --target pytest`) to ensure that no existing features break. +* Please run [`pre-commit`][pre-commit] to check your code matches the + project style. (Note that `gawk` is required.) Use `pre-commit run --all-files` before committing (or use installed-mode, check pre-commit docs) to verify your code passes before pushing to save time. * This project has a strong focus on providing general solutions using a @@ -51,3 +50,114 @@ hereby grant the following license: a non-exclusive, royalty-free perpetual license to install, use, modify, prepare derivative works, incorporate into other computer software, distribute, and sublicense such enhancements or derivative works thereof, in binary and source code form. + + +## Development of pybind11 + +To setup an ideal development environment, run the following commands on a +system with CMake 3.14+. + +```bash +python3 -m venv venv +source venv/bin/activate +pip install -r tests/requirements.txt +cmake -S . -B build -DPYTHON_EXECUTABLE=$(which python) -DDOWNLOAD_CATCH=ON -DDOWNLOAD_EIGEN=ON +cmake --build build -j4 +``` + +Tips: + +* You can use `virtualenv` (from PyPI) instead of `venv` (which is Python 3 + only). +* You can select any name for your environment folder. +* If you use a different shell, there are other activate scripts. +* If you don’t have CMake 3.14+, just add “cmake” to the pip install command. +* You can use `-DPYBIND11_FINDPYTHON=ON` instead of setting the + `PYTHON_EXECUTABLE` - the new search algorithm can find virtual environments, + Conda, and more. + +### Configuration options + +In CMake, configuration options are given with “-D”. Options are stored in the +build directory, in the `CMakeCache.txt` file, so they are remembered for each +build directory. Two selections are special - the generator, given with `-G`, +and the compiler, which is selected based on environment variables `CXX` and +similar, or `-DCMAKE_CXX_COMPILER=`. Unlike the others, these cannot be changed +after the initial run. + +The valid options are: + +* `-DCMAKE_BUILD_TYPE`: Release, Debug, MinSizeRel, RelWithDebInfo +* `-DPYBIND11_FINDPYTHON=ON`: Use CMake 3.12+’s FindPython instead of the + classic, deprecated, custom FindPythonLibs +* `-DPYBIND11_NOPYTHON=ON`: Disable all Python searching (disables tests) +* `-DBUILD_TESTING=ON`: Enable the tests +* `-DDOWNLOAD_CATCH=ON`: Download catch to build the C++ tests +* `-DOWNLOAD_EIGEN=ON`: Download Eigen for the NumPy tests +* `-DPYBIND11_INSTALL=ON/OFF`: Enable the install target (on by default for the + master project) +* `-DUSE_PYTHON_INSTALL_DIR=ON`: Try to install into the python dir + + +
A few standard CMake tricks: (click to expand)

+ +* Use `cmake --build build -v` to see the commands used to build the files. +* Use `cmake build -LH` to list the CMake options with help. +* Use `ccmake` if available to see a curses (terminal) gui, or `cmake-gui` for + a completely graphical interface (not present in the PyPI package). +* Use `-G` and the name of a generator to use something other than `make`, like + `Xcode` or `Ninja` (automatic multithread!). +* Open the `CMakeLists.txt` with QtCreator to generate for that IDE. +* Use `cmake --build build -j12` to build with 12 cores (for example). +* If you are using the `llvm` tool-suite, you can use + `-DCMAKE_EXPORT_COMPILE_COMMANDS=ON` to generate the .json file that the + `clang-*` commands expect. + +

+ + +To run the tests, you can "build" the check target: + +```bash +cmake --build build --target check +``` + +`--target` can be spelled `-t` in CMake 3.15+. You can also run individual tests with these targets: + +* `pytest`: Python tests only +* `cpptest`: C++ tests only +* `test_cmake_build`: Install / subdirectory tests + +If you want to build just a subset of tests, use +`-DPYBIND11_TEST_OVERRIDE="test_callbacks.cpp;test_picking.cpp"`. If this is +empty, all tests will be built. + +### Formatting + +All formatting is handled by pre-commit. You will need docker installed as well +for pre-commit to run the clang-format step in a consistent environment. + +Install with brew (macOS) or pip (any OS): + +```bash +# Any OS +python3 -m pip install pre-commit + +# OR macOS with homebrew: +brew install pre-commit +``` + +Then, you can run it on the items you've added to your staging area, or all files: + +```bash +pre-commit run +# OR +pre-commit run --all-files +``` + + +And, if you want to always use it, you can install it as a git hook (hence the name, pre-commit): + +```bash +pre-commit install +``` From e23dc6122a1281b6ada43b50c3be066b5a81d741 Mon Sep 17 00:00:00 2001 From: Henry Schreiner Date: Mon, 10 Aug 2020 13:40:09 -0400 Subject: [PATCH 3/6] chore: update issue templates --- .../bug-report.md} | 15 ++++++++++----- .github/ISSUE_TEMPLATE/config.yml | 5 +++++ .github/ISSUE_TEMPLATE/feature-request.md | 14 ++++++++++++++ .github/ISSUE_TEMPLATE/question.md | 15 +++++++++++++++ 4 files changed, 44 insertions(+), 5 deletions(-) rename .github/{ISSUE_TEMPLATE.md => ISSUE_TEMPLATE/bug-report.md} (53%) create mode 100644 .github/ISSUE_TEMPLATE/config.yml create mode 100644 .github/ISSUE_TEMPLATE/feature-request.md create mode 100644 .github/ISSUE_TEMPLATE/question.md diff --git a/.github/ISSUE_TEMPLATE.md b/.github/ISSUE_TEMPLATE/bug-report.md similarity index 53% rename from .github/ISSUE_TEMPLATE.md rename to .github/ISSUE_TEMPLATE/bug-report.md index 75df39981a..8a1c793011 100644 --- a/.github/ISSUE_TEMPLATE.md +++ b/.github/ISSUE_TEMPLATE/bug-report.md @@ -1,10 +1,15 @@ +--- +name: Bug Report +about: File an issue about a bug +title: "[BUG] " +--- + + Make sure you've completed the following steps before submitting your issue -- thank you! -1. Check if your question has already been answered in the [FAQ](http://pybind11.readthedocs.io/en/latest/faq.html) section. -2. Make sure you've read the [documentation](http://pybind11.readthedocs.io/en/latest/). Your issue may be addressed there. -3. If those resources didn't help and you only have a short question (not a bug report), consider asking in the [Gitter chat room](https://gitter.im/pybind/Lobby). -4. If you have a genuine bug report or a more complex question which is not answered in the previous items (or not suitable for chat), please fill in the details below. -5. Include a self-contained and minimal piece of code that reproduces the problem. If that's not possible, try to make the description as clear as possible. +1. Make sure you've read the [documentation](http://pybind11.readthedocs.io/en/latest/). Your issue may be addressed there. +2. Consider asking first in the [Gitter chat room](https://gitter.im/pybind/Lobby). +3. Include a self-contained and minimal piece of code that reproduces the problem. If that's not possible, try to make the description as clear as possible. *After reading, remove this checklist and the template text in parentheses below.* diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml new file mode 100644 index 0000000000..20e743136f --- /dev/null +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -0,0 +1,5 @@ +blank_issues_enabled: false +contact_links: + - name: Gitter room + url: https://gitter.im/pybind/Lobby + about: A room for discussing pybind11 with an active community diff --git a/.github/ISSUE_TEMPLATE/feature-request.md b/.github/ISSUE_TEMPLATE/feature-request.md new file mode 100644 index 0000000000..0171c813dd --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature-request.md @@ -0,0 +1,14 @@ +--- +name: Feature Request +about: File an issue about adding a feature +title: "[FEAT] " +--- + + +Make sure you've completed the following steps before submitting your issue -- thank you! + +1. Check if your feature has already been mentioned / rejected / planned in other issues. +2. If those resources didn't help, consider asking in the [Gitter chat room](https://gitter.im/pybind/Lobby) to see if this is interesting / useful to a larger audience and possible to implement reasonably, +4. If you have a useful feature that passes the previous items (or not suitable for chat), please fill in the details below. + +*After reading, remove this checklist.* diff --git a/.github/ISSUE_TEMPLATE/question.md b/.github/ISSUE_TEMPLATE/question.md new file mode 100644 index 0000000000..0862516f82 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/question.md @@ -0,0 +1,15 @@ +--- +name: Question +about: File an issue about unexplained behavior +title: "[QUESTION] " +--- + +If you have a question, please check the following first: + +1. Check if your question has already been answered in the [FAQ](http://pybind11.readthedocs.io/en/latest/faq.html) section. +2. Make sure you've read the [documentation](http://pybind11.readthedocs.io/en/latest/). Your issue may be addressed there. +3. If those resources didn't help and you only have a short question (not a bug report), consider asking in the [Gitter chat room](https://gitter.im/pybind/Lobby). +4. If you have a more complex question which is not answered in the previous items (or not suitable for chat), please fill in the details below. +5. Include a self-contained and minimal piece of code that illustrates your question. If that's not possible, try to make the description as clear as possible. + +*After reading, remove this checklist.* From fe92b54ecb7e27e8abaa51ae804512acd0c30bdd Mon Sep 17 00:00:00 2001 From: Henry Schreiner Date: Tue, 11 Aug 2020 13:34:40 -0400 Subject: [PATCH 4/6] fix: review from @bstaletic --- .github/CONTRIBUTING.md | 13 ++++++------- .github/ISSUE_TEMPLATE/bug-report.md | 11 ++++++++--- .github/ISSUE_TEMPLATE/feature-request.md | 4 +++- .github/ISSUE_TEMPLATE/question.md | 16 +++++++++++----- 4 files changed, 28 insertions(+), 16 deletions(-) diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index 007ce8b45b..b42daa34a9 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -69,8 +69,8 @@ Tips: * You can use `virtualenv` (from PyPI) instead of `venv` (which is Python 3 only). -* You can select any name for your environment folder. -* If you use a different shell, there are other activate scripts. +* You can select any name for your environment folder; if it contains "env" it + will be ignored by git. * If you don’t have CMake 3.14+, just add “cmake” to the pip install command. * You can use `-DPYBIND11_FINDPYTHON=ON` instead of setting the `PYTHON_EXECUTABLE` - the new search algorithm can find virtual environments, @@ -105,13 +105,12 @@ The valid options are: * Use `cmake build -LH` to list the CMake options with help. * Use `ccmake` if available to see a curses (terminal) gui, or `cmake-gui` for a completely graphical interface (not present in the PyPI package). -* Use `-G` and the name of a generator to use something other than `make`, like - `Xcode` or `Ninja` (automatic multithread!). +* Use `-G` and the name of a generator to use something different, like `Ninja` + (automatic multithreading!). `cmake --help` lists the generators available. * Open the `CMakeLists.txt` with QtCreator to generate for that IDE. * Use `cmake --build build -j12` to build with 12 cores (for example). -* If you are using the `llvm` tool-suite, you can use - `-DCMAKE_EXPORT_COMPILE_COMMANDS=ON` to generate the .json file that the - `clang-*` commands expect. +* You can use `-DCMAKE_EXPORT_COMPILE_COMMANDS=ON` to generate the `.json` file + that some tools expect.

diff --git a/.github/ISSUE_TEMPLATE/bug-report.md b/.github/ISSUE_TEMPLATE/bug-report.md index 8a1c793011..1c51997a96 100644 --- a/.github/ISSUE_TEMPLATE/bug-report.md +++ b/.github/ISSUE_TEMPLATE/bug-report.md @@ -7,9 +7,14 @@ title: "[BUG] " Make sure you've completed the following steps before submitting your issue -- thank you! -1. Make sure you've read the [documentation](http://pybind11.readthedocs.io/en/latest/). Your issue may be addressed there. -2. Consider asking first in the [Gitter chat room](https://gitter.im/pybind/Lobby). -3. Include a self-contained and minimal piece of code that reproduces the problem. If that's not possible, try to make the description as clear as possible. +1. Make sure you've read the [documentation][]. Your issue may be addressed there. +2. Search the [issue tracker][] to verify that this hasn't already been reported. +1 or comment there if it has. +3. Consider asking first in the [Gitter chat room][]. +4. Include a self-contained and minimal piece of code that reproduces the problem. If that's not possible, try to make the description as clear as possible. + +[documentation]: https://pybind11.readthedocs.io +[issue tracker]: https://github.com/pybind/pybind11/issues +[Gitter chat room]: https://gitter.im/pybind/Lobby *After reading, remove this checklist and the template text in parentheses below.* diff --git a/.github/ISSUE_TEMPLATE/feature-request.md b/.github/ISSUE_TEMPLATE/feature-request.md index 0171c813dd..5f6ec81ec9 100644 --- a/.github/ISSUE_TEMPLATE/feature-request.md +++ b/.github/ISSUE_TEMPLATE/feature-request.md @@ -8,7 +8,9 @@ title: "[FEAT] " Make sure you've completed the following steps before submitting your issue -- thank you! 1. Check if your feature has already been mentioned / rejected / planned in other issues. -2. If those resources didn't help, consider asking in the [Gitter chat room](https://gitter.im/pybind/Lobby) to see if this is interesting / useful to a larger audience and possible to implement reasonably, +2. If those resources didn't help, consider asking in the [Gitter chat room][] to see if this is interesting / useful to a larger audience and possible to implement reasonably, 4. If you have a useful feature that passes the previous items (or not suitable for chat), please fill in the details below. +[Gitter chat room]: https://gitter.im/pybind/Lobby + *After reading, remove this checklist.* diff --git a/.github/ISSUE_TEMPLATE/question.md b/.github/ISSUE_TEMPLATE/question.md index 0862516f82..b199b6ee8a 100644 --- a/.github/ISSUE_TEMPLATE/question.md +++ b/.github/ISSUE_TEMPLATE/question.md @@ -6,10 +6,16 @@ title: "[QUESTION] " If you have a question, please check the following first: -1. Check if your question has already been answered in the [FAQ](http://pybind11.readthedocs.io/en/latest/faq.html) section. -2. Make sure you've read the [documentation](http://pybind11.readthedocs.io/en/latest/). Your issue may be addressed there. -3. If those resources didn't help and you only have a short question (not a bug report), consider asking in the [Gitter chat room](https://gitter.im/pybind/Lobby). -4. If you have a more complex question which is not answered in the previous items (or not suitable for chat), please fill in the details below. -5. Include a self-contained and minimal piece of code that illustrates your question. If that's not possible, try to make the description as clear as possible. +1. Check if your question has already been answered in the [FAQ][] section. +2. Make sure you've read the [documentation][]. Your issue may be addressed there. +3. If those resources didn't help and you only have a short question (not a bug report), consider asking in the [Gitter chat room][] +4. Search the [issue tracker][], including the closed issues, to see if your question has already been asked/answered. +1 or comment if it has been asked but has no answer. +5. If you have a more complex question which is not answered in the previous items (or not suitable for chat), please fill in the details below. +6. Include a self-contained and minimal piece of code that illustrates your question. If that's not possible, try to make the description as clear as possible. + +[FAQ]: http://pybind11.readthedocs.io/en/latest/faq.html +[documentation]: https://pybind11.readthedocs.io +[issue tracker]: https://github.com/pybind/pybind11/issues +[Gitter chat room]: https://gitter.im/pybind/Lobby *After reading, remove this checklist.* From e79a5900f76e2903d4e3ba7460ca5a3a8b848bc0 Mon Sep 17 00:00:00 2001 From: Henry Schreiner Date: Sat, 15 Aug 2020 09:11:00 -0400 Subject: [PATCH 5/6] refactor: a few points from @rwgk --- .github/ISSUE_TEMPLATE/bug-report.md | 1 + .github/CONTRIBUTING.md => CONTRIBUTING.md | 2 +- tests/CMakeLists.txt | 2 +- 3 files changed, 3 insertions(+), 2 deletions(-) rename .github/CONTRIBUTING.md => CONTRIBUTING.md (98%) diff --git a/.github/ISSUE_TEMPLATE/bug-report.md b/.github/ISSUE_TEMPLATE/bug-report.md index 1c51997a96..ae36ea6508 100644 --- a/.github/ISSUE_TEMPLATE/bug-report.md +++ b/.github/ISSUE_TEMPLATE/bug-report.md @@ -11,6 +11,7 @@ Make sure you've completed the following steps before submitting your issue -- t 2. Search the [issue tracker][] to verify that this hasn't already been reported. +1 or comment there if it has. 3. Consider asking first in the [Gitter chat room][]. 4. Include a self-contained and minimal piece of code that reproduces the problem. If that's not possible, try to make the description as clear as possible. + a. If possible, make a PR with a new, failing test to give us a starting point to work on! [documentation]: https://pybind11.readthedocs.io [issue tracker]: https://github.com/pybind/pybind11/issues diff --git a/.github/CONTRIBUTING.md b/CONTRIBUTING.md similarity index 98% rename from .github/CONTRIBUTING.md rename to CONTRIBUTING.md index b42daa34a9..6907f901b3 100644 --- a/.github/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -128,7 +128,7 @@ cmake --build build --target check * `test_cmake_build`: Install / subdirectory tests If you want to build just a subset of tests, use -`-DPYBIND11_TEST_OVERRIDE="test_callbacks.cpp;test_picking.cpp"`. If this is +`-DPYBIND11_TEST_OVERRIDE="test_callbacks.cpp;test_pickling.cpp"`. If this is empty, all tests will be built. ### Formatting diff --git a/tests/CMakeLists.txt b/tests/CMakeLists.txt index 2a077c6eb5..9a97ec5bdc 100644 --- a/tests/CMakeLists.txt +++ b/tests/CMakeLists.txt @@ -84,7 +84,7 @@ set(PYBIND11_TEST_FILES test_virtual_functions.cpp) # Invoking cmake with something like: -# cmake -DPYBIND11_TEST_OVERRIDE="test_callbacks.cpp;test_picking.cpp" .. +# cmake -DPYBIND11_TEST_OVERRIDE="test_callbacks.cpp;test_pickling.cpp" .. # lets you override the tests that get compiled and run. You can restore to all tests with: # cmake -DPYBIND11_TEST_OVERRIDE= .. if(PYBIND11_TEST_OVERRIDE) From a26d5c063eba1cb9ee1d85f959a63fb2d1e212ee Mon Sep 17 00:00:00 2001 From: Henry Schreiner Date: Sat, 15 Aug 2020 18:39:52 -0400 Subject: [PATCH 6/6] docs: more touchup, review changes --- CONTRIBUTING.md | 36 +++++++++++++++++++++--------------- 1 file changed, 21 insertions(+), 15 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 6907f901b3..1ec1f1d532 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -5,21 +5,22 @@ sections on how to contribute code and bug reports. Before submitting a question or bug report, please take a moment of your time and ensure that your issue isn't already discussed in the project documentation -provided at -[http://pybind11.readthedocs.org/en/latest](http://pybind11.readthedocs.org/en/latest). +provided at [pybind11.readthedocs.org][] or in the [issue tracker][]. You can +also check [gitter][] to see if it came up before. Assuming that you have identified a previously unknown problem or an important question, it's essential that you submit a self-contained and minimal piece of code that reproduces the problem. In other words: no external dependencies, isolate the function(s) that cause breakage, submit matched and complete C++ -and Python snippets that can be easily compiled and run on my end. +and Python snippets that can be easily compiled and run in isolation; or +ideally make a small PR with a failing test case that can be used as a starting +point. ## Pull requests Contributions are submitted, reviewed, and accepted using GitHub pull requests. -Please refer to [this -article](https://help.github.com/articles/using-pull-requests) for details and -adhere to the following rules to make the process as smooth as possible: +Please refer to [this article][using pull requests] for details and adhere to +the following rules to make the process as smooth as possible: * Make a new branch for every feature you're working on. * Make small and clean pull requests that are easy to review but make sure they @@ -33,8 +34,6 @@ adhere to the following rules to make the process as smooth as possible: * This project has a strong focus on providing general solutions using a minimal amount of code, thus small pull requests are greatly preferred. -[pre-commit]: https://pre-commit.com - ### Licensing of contributions pybind11 is provided under a BSD-style license that can be found in the @@ -55,7 +54,7 @@ derivative works thereof, in binary and source code form. ## Development of pybind11 To setup an ideal development environment, run the following commands on a -system with CMake 3.14+. +system with CMake 3.14+: ```bash python3 -m venv venv @@ -121,7 +120,8 @@ To run the tests, you can "build" the check target: cmake --build build --target check ``` -`--target` can be spelled `-t` in CMake 3.15+. You can also run individual tests with these targets: +`--target` can be spelled `-t` in CMake 3.15+. You can also run individual +tests with these targets: * `pytest`: Python tests only * `cpptest`: C++ tests only @@ -133,8 +133,7 @@ empty, all tests will be built. ### Formatting -All formatting is handled by pre-commit. You will need docker installed as well -for pre-commit to run the clang-format step in a consistent environment. +All formatting is handled by pre-commit. Install with brew (macOS) or pip (any OS): @@ -146,7 +145,8 @@ python3 -m pip install pre-commit brew install pre-commit ``` -Then, you can run it on the items you've added to your staging area, or all files: +Then, you can run it on the items you've added to your staging area, or all +files: ```bash pre-commit run @@ -154,9 +154,15 @@ pre-commit run pre-commit run --all-files ``` - -And, if you want to always use it, you can install it as a git hook (hence the name, pre-commit): +And, if you want to always use it, you can install it as a git hook (hence the +name, pre-commit): ```bash pre-commit install ``` + +[pre-commit]: https://pre-commit.com +[pybind11.readthedocs.org]: http://pybind11.readthedocs.org/en/latest +[issue tracker]: https://github.com/pybind/pybind11/issues +[gitter]: https://gitter.im/pybind/Lobby +[using pull requests]: https://help.github.com/articles/using-pull-requests