Require pybind 2.6 from environment for gmxapi Python package extension module.

[alexxy/gromacs.git] / python_packaging / README.md

diff --git a/python_packaging/README.md b/python_packaging/README.md
index faa48c6a165ee33aa48809accd37b07ad768b597..f7b25e742780ccbf2da2c8df5bea8bf52de7ac26 100644 (file)
--- a/python_packaging/README.md
+++ b/python_packaging/README.md
@@ -115,17 +115,6 @@ Hint: the fork point from `master` and the current git ref can be set as environ
 Refer to `./src/external/README.md` for current details on the copied external
 sources.
 
-# scikit-build
-
-For the C++ extension module `_gmxapi`, 
-[scikit-build](https://scikit-build.readthedocs.io/en/latest/)
-provides glue between Python package tools and CMake infrastructure in `./src`.
-Scikit-build is installed with Python packaging tools automatically with
-`pip install -r requirements.txt`, as above.
-
-Note: scikit-build is only required for convenient management of the Python
-build environment and packaging. See https://gitlab.com/gromacs/gromacs/-/issues/2896
-
 # pybind11
 
 Python bindings are expressed in C++ using the
@@ -142,8 +131,6 @@ On some systems, GROMACS will have been built and installed for a different
 architecture than the system on which the Python package will be compiled.
 We need to use CMake Tool-chains to support cross-compiling for the target architecture.
 
-Note: scikit-build can use CMake Toolchains to properly handle `pip` builds.
-
 ## Offline installation
 
 The `pip install` options `--no-index` and `--find-links` allow for an offline stash of package archives so that
@@ -155,3 +142,42 @@ satisfying dependencies for a new virtualenv does not require network access or
 Some dependencies (notably, a Python installation itself) may require some fiddling
 with the XCode SDK.
 https://developer.apple.com/documentation/xcode_release_notes/xcode_10_release_notes#3035624
+
+# Tests for gmxapi Python packages distributed with GROMACS
+
+## Requirements
+
+Python tests use the `unittest` standard library module and the `unittest.mock`
+submodule, included in Python 3.3+.
+
+The additional `pytest` package allows tests to be written more easily and
+concisely, with easier test fixtures (through decorators), log handling, and
+other output handling.
+
+## Files
+
+Python files beginning with `test_` are collected by the Python testing
+framework during automatic test discovery.
+
+`conftest.py` and `pytest.ini` provide configuration for `pytest`.
+
+## Usage
+
+For basic tests, install the Python package(s) (presumably into a virtualenv),
+then use the `pytest` executable to run these tests against the installed
+package(s).
+
+`pytest $LOCAL_REPO_DIR/python_packaging/src/test`
+
+where `$LOCAL_REPO_DIR` is the path to the local copy of the GROMACS source repository.
+
+For multi-process tests, run with an MPI execution wrapper and the `mpi4py` module.
+
+`mpiexec -n 2 python -m mpi4py -m pytest $LOCAL_REPO_DIR/python_packaging/test`
+
+## Controlling output
+
+Refer to pytest documentation for command line options to control the type and detail of output.
+Some high level overview and basic tasks are online at https://docs.pytest.org/en/3.9.3/usage.html
+but you should run `pytest -h` in a terminal to get the complete set of available options
+(in particular, note *log_cli* and *log_level*).