python_packaging/README.md

   1 # Python package sources
   2
   3 This directory exists as a staging area supporting GROMACS enhancement
   4 [#2045](https://redmine.gromacs.org/issues/2045),
   5 which attempts to update the gmxapi efforts from GROMACS 2019,
   6 merge external repositories from
   7 https://github.com/kassonlab/gmxapi
   8 and
   9 https://github.com/kassonlab/sample_restraint,
  10 and build the new functionality proposed at
  11 https://github.com/kassonlab/gmxapi-scripts
  12
  13 ## Repository organization
  14
  15 **TODO: testing infrastructure and project management conventions to allow fully integrated development**
  16 **TODO: Consider long term homes of these directory contents.**
  17
  18 ## gmxapi
  19
  20 Python framework for gmxapi high-level interface.
  21
  22 The `src` directory provides the files that will be copied to the GROMACS installation location from which users may
  23 install Python packages.
  24 This allows C++ extension modules to be built against a user-chosen GROMACS installation,
  25 but for a Python interpreter that is very likely different from that used
  26 by the system administrator who installed GROMACS.
  27
  28 To build and install the Python package,
  29 first install GROMACS to `/path/to/gromacs`.
  30 Then, install the package in a Python virtualenv.
  31
  32     source /path/to/gromacs/bin/GMXRC
  33     python3 -m venv $HOME/somevirtualenv
  34     source $HOME/somevirtualenv/bin/activate
  35     (cd src && pip install -r requirements.txt && pip install .)
  36     python -c 'import gmxapi as gmx'
  37
  38 Use `pytest` to run unit tests and integration tests.
  39
  40     pip install -r requirements-test.txt
  41     pytest src/test
  42     pytest test
  43
  44 For additional discussion on packaging and distribution, see
  45 https://redmine.gromacs.org/issues/2896
  46
  47 ## Docker and Travis-CI testing
  48
  49 **TODO: Migrate to Jenkins-based CI as Docker infrastructure becomes available.**
  50 Infastructure described here is transitional and reflects our need to be able to see code work
  51 in order to review it satisfactorily in the period before GROMACS CI infrastructure
  52 is ready for the load. At some point the Docker aspects will change,
  53 or be removed as appropriate.
  54
  55 The Python packaging will be tested on Jenkins with Docker-based CI, but this
  56 infrastructure is a little way off. In the mean time, we are trying to submit
  57 changes that do not affect main line GROMACS development or building and to
  58 perform testing with Docker externally. Users may build and run Docker images
  59 from the `python_packaging/docker` directory. The `kassonlab` Travis-CI account
  60 will automatically build and run Docker-based tests for each outstanding
  61 feature branch.
  62
  63 The Dockerfiles
  64 * direct a few different Linux, Python, and GROMACS configurations,
  65 * build and install the `gmxapi` and `sample_restraint` packages, and
  66 * provide a few styles of testing through the `scripts` accessible through `entrypoint.sh`.
  67
  68 In successive build stages, Travis-CI is directed to use a series of Docker images,
  69 referred to here with their dockerhub repository, an explanation of tags,
  70 and the Dockerfiles from which they are built.
  71 The image naming scheme encodes a build matrix element in the repository name and
  72 a git branch or reference in the image tag (described below).
  73 Additional information in `python_packaging/docker/README.md`.
  74
  75 1. `gmxapi/gromacs-dependencies-<matrix>:<tag>` Ubuntu distribution with dependencies for
  76    various GROMACS build configurations. `<matrix>` encodes the build matrix dimensions
  77    for things like compiler and MPI flavor. Travis-CI will rebuild this for commits to
  78    `kassonLabFork`, but if the `<matrix>` string changes, a more privileged dockerhub
  79    account will have to push the new repository the first time and then grant access
  80    to the service account used by the Travis-CI configuration.
  81    `<tag>` is the (short) git revision hash
  82    of the `master` branch commit corresponding to the current state of the `kassonLabFork`
  83    branch.
  84 2. `gmxapi/gromacs-<matrix>:<tag>` Builds on `gromacs-dependencies-<matrix>`, where
  85    `<matrix>` has the same meaning as above. `<tag>` is the (short) git revision hash
  86    of the `master` branch commit corresponding to the current state of the `kassonLabFork`
  87    branch.
  88    This is recorded in the `kassonLabFork` `.travis.yml`.
  89 3. `gmxapi/ci-<matrix>:<tag>` starts with `gromacs-<matrix>` and merges in the
  90     `python_packaging` changes associated with the feature branch indicated by `<tag>`
  91
  92 Hint: the fork point from `master` and the current git ref can be set as environment variables:
  93
  94     FORKPOINT=$(git show -s --pretty=format:"%h" `git merge-base gerrit_master HEAD`)
  95     REF=`git show -s --pretty=format:"%h"`
  96
  97 ## External project code
  98
  99 Refer to `./src/external/README.md` for current details on the copied external
 100 sources.
 101
 102 # scikit-build
 103
 104 For the C++ extension module `_gmxapi`,
 105 [scikit-build](https://scikit-build.readthedocs.io/en/latest/)
 106 provides glue between Python package tools and CMake infrastructure in `./src`.
 107 Scikit-build is installed with Python packaging tools automatically with
 108 `pip install -r requirements.txt`, as above.
 109
 110 Note: scikit-build is only required for convenient management of the Python
 111 build environment and packaging. See https://redmine.gromacs.org/issues/2896
 112
 113 # pybind11
 114
 115 Python bindings are expressed in C++ using the
 116 [pybind11](https://pybind11.readthedocs.io/en/stable/)
 117 template library.
 118 The pybind11 repository is mirrored in GROMACS project sources and
 119 installed with GROMACS for convenience and reproducibility.
 120
 121 # Build and install
 122
 123 ## Cross compiling
 124
 125 On some systems, GROMACS will have been built and installed for a different
 126 architecture than the system on which the Python package will be compiled.
 127 We need to use CMake Tool-chains to support cross-compiling for the target architecture.
 128
 129 Note: scikit-build can use CMake Toolchains to properly handle `pip` builds.
 130
 131 ## Offline installation
 132
 133 The `pip install` options `--no-index` and `--find-links` allow for an offline stash of package archives so that
 134 satisfying dependencies for a new virtualenv does not require network access or lengthy build times.