X-Git-Url: http://biod.pnpi.spb.ru/gitweb/?a=blobdiff_plain;f=docs%2Fgmxapi%2Fuserguide%2Finstall.rst;h=e1994e9c74b343f80ed9c496eafad0eb6a494693;hb=8073360f849809b7ce4fa5b5f14ae16209ca087f;hp=8588156a48b3d85140459260e93457ec49e99d3f;hpb=2f224c7322e2e2e948590e1e73c82ff2b3ed568f;p=alexxy%2Fgromacs.git diff --git a/docs/gmxapi/userguide/install.rst b/docs/gmxapi/userguide/install.rst index 8588156a48..e1994e9c74 100644 --- a/docs/gmxapi/userguide/install.rst +++ b/docs/gmxapi/userguide/install.rst @@ -65,8 +65,7 @@ Set up a Python virtual environment python3 -m venv $HOME/myvenv . $HOME/myvenv/bin/activate python -m ensurepip --default-pip - pip install --upgrade pip setuptools - pip install --upgrade cmake scikit-build + pip install --upgrade pip setuptools wheel .. seealso:: :ref:`gmxapi venv` @@ -86,7 +85,7 @@ Background *gmxapi* comes in three parts: * GROMACS gmxapi library for C++. -* This Python package, supporting Python 3.6 and higher +* This Python package, supporting Python 3.7 and higher * MD restraint plugins and sample gmxapi client code GROMACS requirements @@ -112,9 +111,9 @@ to the build configuration. Build system requirements ------------------------- -gmxapi can be built for Python 3.6 and higher. +gmxapi can be built for Python 3.7 and higher. -You will need a C++ 14 compatible compiler and a reasonably up-to-date version +You will need a C++ 17 compatible compiler and a reasonably up-to-date version of CMake. Full gmxapi functionality may also require an MPI compiler (e.g. :command:`mpicc`). @@ -144,7 +143,7 @@ that works. Python environment requirements ------------------------------- -gmxapi requires Python 3.6 or higher. Check your version with +gmxapi requires Python 3.7 or higher. Check your version with :command:`python3 --version` or :command:`python --version`. .. note:: @@ -156,7 +155,7 @@ gmxapi requires Python 3.6 or higher. Check your version with :command:`python3 --version` or :command:`python --version` and :command:`pip --version`. To build and install, you need the Python packages for -cmake_, networkx_, scikit-build_, and setuptools_ +cmake_, networkx_, and setuptools_ (all available from `PyPI with pip `_). For full functionality, you should also have mpi4py_ and numpy_. @@ -340,7 +339,7 @@ the remaining examples assume the virtual environment is still active. Install dependencies ^^^^^^^^^^^^^^^^^^^^ -It is always a good idea to update pip_ and setuptools_ before installing +It is always a good idea to update pip_, setuptools_, and wheel_ before installing new Python packages:: pip install --upgrade pip setuptools @@ -350,7 +349,7 @@ they are installed and up to date before proceeding. :: - pip install --upgrade cmake scikit-build + pip install --upgrade cmake pybind11 For MPI, we use mpi4py_. Make sure it is using the same MPI installation that we are building @@ -432,7 +431,7 @@ without internet access, either from the source directory or from a source archi For example, the last line of the previous example could be replaced with:: - pip install --no-cache-dir --no-deps --no-index --no-build-isolation . + pip install --no-cache-dir --no-deps --no-index . Refer to pip_ documentation for descriptions of these options. @@ -449,11 +448,11 @@ Building a source archive ------------------------- A source archive for the gmxapi python package can be built from the GROMACS -source repository using Python ``setuptools`` and ``scikit-build``. +source repository using Python ``setuptools``. Example:: - pip install --upgrade setuptools scikit-build + pip install --upgrade setuptools cd python_packaging/src python setup.py sdist @@ -462,6 +461,13 @@ archive file. The file name has the form *gmxapi-.*, where ** is the version from the ``setup.py`` file, and ** is determined by the local environment or by additional arguments to ``setup.py``. +The new `build `__ module is somewhat tidier. +It automatically manages a temporary venv with the necessary dependencies:: + + pip install --upgrade build + cd python_packaging/src + python -m build --sdist . + .. seealso:: Python documentation for @@ -496,6 +502,19 @@ This will first build the *gmxapi* Python package and install it to a temporary location in the build tree. Sphinx can then import the package to automatically extract Python docstrings. +Note that this is an entirely CMake-driven installation and Python dependencies +will not be installed automatically. You can update your Python environment +(before configuring with CMake) using the :file:`requirements.txt` files provided +in the :file:`python_packaging/` directory of the repository. Example:: + + pip install -r python_packaging/requirements-docs.txt + +or + +:: + + pip install -r python_packaging/requirements-test.txt + Sometimes the build environment can choose a different Python interpreter than the one you intended. You can set the ``Python3_ROOT_DIR`` or ``CMAKE_PREFIX_PATH`` CMake variable to @@ -551,6 +570,27 @@ and see if that fixes the problem. If not, try a fresh virtual environment (see above) to help narrow down the problem before you `open an issue `_. +Errors regarding pybind11 +------------------------- + +An error may occur in ``setup.py`` with output that contains something like the following:: + + ModuleNotFoundError: No module named 'pybind11' + Building wheel for gmxapi (pyproject.toml): finished with status 'error' + ERROR: Failed building wheel for gmxapi + Failed to build gmxapi + ERROR: Could not build wheels for gmxapi, which is required to install pyproject.toml-based projects + +The important information here is that ``pybind11`` was not found. + +Build dependencies aren't always automatically installed. +Even if you are using ``pip``, you may have disabled automatic dependency fulfillment with an option like ``--no-build-isolation`` or ``--no-deps``. + +In any case, the problem should be resolved by explicitly installing the ``pybind11`` +Python package before attempting to build ``gmxapi``:: + + pip install --upgrade pybind11 + Couldn't find the ``gmxapi`` support library? --------------------------------------------- @@ -669,3 +709,5 @@ rebase your feature branches for the new development cycle. .. _scikit-build: https://pypi.org/project/scikit-build/ .. _setuptools: https://pypi.org/project/setuptools/ + +.. _wheel: https://pypi.org/project/wheel/