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 d22f8fed9f97e0b6aaa6e884be037d2b45ad3c8b..f7b25e742780ccbf2da2c8df5bea8bf52de7ac26 100644 (file)
--- a/python_packaging/README.md
+++ b/python_packaging/README.md
@@ -1,7 +1,7 @@
 # Python package sources
 
 This directory exists as a staging area supporting GROMACS enhancement
-[#2045](https://redmine.gromacs.org/issues/2045),
+[#2045](https://gitlab.com/gromacs/gromacs/-/issues/2045),
 which attempts to update the gmxapi efforts from GROMACS 2019,
 merge external repositories from
 https://github.com/kassonlab/gmxapi
@@ -42,7 +42,23 @@ Use `pytest` to run unit tests and integration tests.
     pytest test
 
 For additional discussion on packaging and distribution, see
-https://redmine.gromacs.org/issues/2896
+https://gitlab.com/gromacs/gromacs/-/issues/2896
+
+## Sample MD extension code
+
+`sample_restraint` is a subtree containing a complete CMake project for building
+pluggable GROMACS MD extensions for execution through gmxapi. Up to and
+including version 0.0.7 of the sample code, the sub-project lived at
+https://github.com/kassonlab/sample_restraint/ and was supported by GROMACS 2019.
+
+The GROMACS repository becomes the upstream source for the sample code for
+GROMACS releases 2020 and higher. Refer to [README.md](sample_restraint/README.md)
+in `python_packaging/sample_restraint` for more information.
+
+To use a plugin based on the sample restraint, you will need to build and install
+the gmxapi Python package (above).
+
+**todo** CookieCutter repo for easy forking.
 
 ## Docker and Travis-CI testing
 
@@ -91,7 +107,7 @@ Additional information in `python_packaging/docker/README.md`.
 
 Hint: the fork point from `master` and the current git ref can be set as environment variables:
 
-    FORKPOINT=$(git show -s --pretty=format:"%h" `git merge-base gerrit_master HEAD`)
+    FORKPOINT=$(git show -s --pretty=format:"%h" `git merge-base master HEAD`)
     REF=`git show -s --pretty=format:"%h"`
 
 ## External project code
@@ -99,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://redmine.gromacs.org/issues/2896
-
 # pybind11
 
 Python bindings are expressed in C++ using the
@@ -126,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
@@ -138,4 +141,43 @@ satisfying dependencies for a new virtualenv does not require network access or
 ## OS X
 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
\ No newline at end of file
+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*).