.. highlight:: bash
-This document provides detailed documentation about building and installing
-the gmxapi Python package.
-
-GROMACS is a high performance computational science tool that is optimized for
-a variety of specialized hardware and parallel computing environments.
-To make the best use of a computing environment, GROMACS is usually built from
-source code.
-
-Users of Python based molecular science tools may have various requirements and
-use a variety of Python distributions,
-so gmxapi extension code is most useful when built from source code for a specific
-GROMACS installation and Python environment.
-
-This document has a lot of detail.
-If you don't need a lot of reference material, you may just jump ahead to the :ref:`installation`.
+Installation instructions for the :py:mod:`gmxapi` Python package,
+built on GROMACS.
Command line examples assume the `bash <https://www.gnu.org/software/bash/>`_ shell.
.. note:: Regarding multiple GROMACS installations:
Many GROMACS users switch between multiple GROMACS installations on the same
- computer using an HPC module system and/or a GMXRC configuration script.
- For the equivalent sort of environment switching with the ``gmxapi`` Python package,
+ computer using an HPC module system and/or a :ref:`GMXRC <getting access to |Gromacs|>` configuration script.
+ For the equivalent sort of environment switching with the :py:mod:`gmxapi` Python package,
we recommend installing it in a different
`Python virtual environment <https://www.google.com/search?q=python+virtual+environment>`_
for each GROMACS installation.
- Once built, a particular copy of the ``gmxapi`` Python package always refers to the
+ Once built, a particular copy of the :py:mod:`gmxapi` Python package always refers to the
same GROMACS installation.
.. contents:: Contents
.. note::
- The following documentation contains frequent references to the ``pip`` tool
+ The following documentation contains frequent references to the pip_ tool
for installing Python packages. In some cases, an unprivileged user should
- use the ``--user`` command line flag to tell ``pip`` to install packages
+ use the ``--user`` command line flag to tell pip_ to install packages
into the user site-packages directory rather than the default site-packages
directory for the Python installation. This flag is not appropriate when
- running ``pip`` in a virtual environment (as recommended) and is omitted in
+ running :command:`pip` in a virtual environment (as recommended) and is omitted in
this documentation. If you need the ``--user`` flag, you should modify the
- example commands to look something like ``pip install --upgrade somepackage --user``
+ example commands to look something like :command:`pip install --upgrade somepackage --user`
.. note::
- These instructions use the executable names ``python`` and ``pip``
- instead of ``python3`` or ``pip3``. Some Python installations require the ``3``
+ These instructions use the executable names :command:`python` and :command:`pip`
+ instead of :command:`python3` or :command:`pip3`. Some Python installations require the ``3``
suffix, but it is usually not necessary if you have already activated a Python
virtual environment (recommended).
+Overview
+========
+
+Typically, setting up the *gmxapi* Python package follows these three steps.
+If this overview is sufficient for your computing environment,
+you may disregard the rest of this document.
+
+Install GROMACS
+---------------
+
+Locate your GROMACS installation, or build and install GROMACS 2020 or higher.
+
+.. seealso:: `GROMACS installation <http://manual.gromacs.org/documentation/current/install-guide/index.html>`_
+
+The following assumes GROMACS is installed to :file:`/path/to/gromacs`
+
+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
+
+.. seealso:: :ref:`gmxapi venv`
+
+Install the gmxapi Python package
+---------------------------------
+
+::
+
+ . /path/to/gromacs/bin/GMXRC
+ pip install gmxapi
-Requirements
-============
+.. seealso:: :ref:`installation`
-``gmxapi`` comes in three parts:
+Background
+==========
+
+*gmxapi* comes in three parts:
* GROMACS gmxapi library for C++.
-* This Python package, supporting Python 3.5 and higher
+* This Python package, supporting Python 3.6 and higher
* MD restraint plugins and sample gmxapi client code
-Build system requirements
--------------------------
+GROMACS requirements
+--------------------
-gmxapi can be built for Python 3.5 and higher.
+The Python package requires a GROMACS installation.
+Locate an existing GROMACS installation, or
+`build and install GROMACS <http://manual.gromacs.org/documentation/current/install-guide/index.html>`_
+before proceeding.
-You will need a C++ 14 compatible compiler and a reasonably up-to-date version
-of CMake.
-Full gmxapi functionality may also require an MPI compiler (e.g. ``mpicc``).
+.. note::
-The Python package requires a GROMACS installation.
-Build and install
-`GROMACS <http://manual.gromacs.org/documentation/current/install-guide/index.html>`_
-before proceeding. Be sure to configure CMake with the ``GMXAPI=ON`` option.
+ Note that gmxapi requires that GROMACS is configured with ``GMXAPI=ON`` and ``BUILD_SHARED_LIBS=ON``.
+ These are enabled by default in most cases. If these options were overridden
+ for your GROMACS installation, you will see CMake errors when trying to build
+ and install the gmxapi Python package or other client software.
-Then, "source" the GMXRC file from the GROMACS installation as you normally would
+Then, "source" the :file:`GMXRC` file from the GROMACS installation
+:ref:`as you normally would <getting access to |Gromacs|>`
before using GROMACS, or note its installation location so that you can pass it
to the build configuration.
-.. note::
+Build system requirements
+-------------------------
- If you are using a managed computing resource, such as a research HPC cluster,
- GROMACS may already be installed, but you will need GROMACS 2020 or later, and
- it must be configured with ``GMXAPI=ON``.
+gmxapi can be built for Python 3.6 and higher.
+
+You will need a C++ 14 compatible compiler and a reasonably up-to-date version
+of CMake.
+Full gmxapi functionality may also require an MPI compiler (e.g. :command:`mpicc`).
Important: To build a module that can be imported by Python, you need a Python
installation that includes the Python headers. Unfortunately, it is not always
On a Linux system, this may require installing packages such as ``python-dev``
and/or ``python3-dev``.
If you are building Python, either from scratch or with a tool like
-``pyenv install`` (see
+:command:`pyenv install` (see
`wiki entry <https://github.com/pyenv/pyenv/wiki#how-to-build-cpython-with---enable-shared>`_
),
be sure to enable installation of the Python C library with the
home directory. (Some examples below.)
If you are using an HPC system with software available through modules you may
-be able to just ``module load`` a different Python installation and find one
+be able to just :command:`module load` a different Python installation and find one
that works.
Python environment requirements
-------------------------------
-gmxapi requires Python 3.5 or higher. Check your version with
-``python3 --version`` or ``python --version``.
+gmxapi requires Python 3.6 or higher. Check your version with
+:command:`python3 --version` or :command:`python --version`.
.. note::
The following documentation assumes you do not need to use a trailing '3' to
access a Python 3 interpreter on your system.
- The default Python interpreter on your system may use ``python3`` and ``pip3``
- instead of ``python`` and ``pip``. You can check the version with
- ``python3 --version`` or ``python --version`` and ``pip --version``.
+ The default Python interpreter on your system may use :command:`python3` and :command:`pip3`
+ instead of :command:`python` and :command:`pip`. You can check the version with
+ :command:`python3 --version` or :command:`python --version` and :command:`pip --version`.
-To build and install, you also need the packages ``cmake``,
-``setuptools``, ``networkx``, and ``scikit-build``.
+To build and install, you need the Python packages for
+cmake_, networkx_, scikit-build_, and setuptools_
+(all available from `PyPI with pip <https://pip.pypa.io/en/stable/>`_).
-For full functionality, you should also have ``mpi4py`` and ``numpy``.
-These requirements and version numbers are listed in ``requirements.txt``.
+For full functionality, you should also have mpi4py_ and numpy_.
+These requirements and version numbers are listed in :file:`requirements.txt`.
The easiest way to make sure you have the requirements installed, first update
-``pip``, then use the ``requirements.txt`` file provided with the repository.
+pip_, then use the :file:`requirements.txt` file provided with the repository.
File paths in this section are relative to the root directory of your local copy
of the GROMACS source.
-Confirm that ``pip`` is available, install ``pip`` if it is missing, or get
-instructions on how to install ``pip``::
+Confirm that pip_ is available, install pip_ if it is missing, or get
+instructions on how to install pip_::
python -m ensurepip --default-pip
If you are building from source code in a local copy of the GROMACS source
repository, some helpful files allow you to preinstall the Python requirements
-before installing the ``gmxapi`` package.
+before installing the :py:mod:`gmxapi` package.
pip install -r python_packaging/src/requirements.txt
If building documentation or running tests,
-``pip install -r python_packaging/requirements-docs.txt`` or
-``pip install -r python_packaging/requirements-test.txt``,
+:command:`pip install -r python_packaging/requirements-docs.txt` or
+:command:`pip install -r python_packaging/requirements-test.txt`,
respectively, or see below.
Documentation build requirements
See :ref:`gmxapi_package_documentation`
-.. _testing_requirements:
+.. _testing requirements:
Testing requirements
--------------------
+Note that the test suite is only available in the GROMACS source tree.
+(It is not part of the installed package.)
+Acquire the GROMACS sources with :command:`git` or by downloading an archive, as documented elsewhere.
+
Testing is performed with `pytest <https://docs.pytest.org/en/latest/>`_.
-Tests also require ``numpy``.
-You can probably install both with ``pip``::
- pip install pytest numpy
+:file:`python_packaging/requirements-test.txt` lists additional requirements for testing.
+With pip_::
+
+ pip install -r python_packaging/requirements-test.txt
To test the full functionality also requires an MPI parallel environment.
-You will need the ``mpi4py`` Python package and an MPI launcher
-(such as ``mpiexec``, ``mpirun``, a launcher provided by your HPC queuing system,
+You will need the mpi4py_ Python package and an MPI launcher
+(such as :command:`mpiexec`, :command:`mpirun`, a launcher provided by your HPC queuing system,
or whatever is provided by your favorite MPI package for your operating system).
.. _mpi_requirements:
MPI requirements
----------------
-For the ensemble simulations features, you will need an MPI installation. On an HPC system, this means you will
-probably have to use ``module load`` to load a compatible set of MPI tools and compilers. Check your HPC
-documentation or try ``module avail`` to look for an ``openmpi``, ``mpich``, or ``mvapich`` module and matching compiler
-module. This may be as simple as
-::
+For the ensemble simulations features, you will need an MPI installation.
+On an HPC system, this means you will probably have to use :command:`module load`
+to load a compatible set of MPI tools and compilers.
+Check your HPC documentation or try :command:`module avail` to look for an
+``openmpi``, ``mpich``, or ``mvapich`` module and matching compiler module.
+This may be as simple as::
module load gcc
module load mpicc
-Note that the compilers loaded might not be the first compilers discovered automatically by the build tools we will use
-below, so you may have to specify compilers on the command line for consistency. It may be necessary to require that
-GROMACS, gmxapi, and the sample code are built with the same compiler(s).
+Note that the compilers loaded might not be the first compilers discovered
+automatically by the build tools we will use below,
+so you may have to specify compilers on the command line for consistency.
+It may be necessary to require that GROMACS, gmxapi,
+and the sample code are built with the same compiler(s).
-Note that strange errors have been known to occur when ``mpi4py`` is built with
+Note that strange errors have been known to occur when mpi4py_ is built with
different a different tool set than has been used to build Python and gmxapi.
If the default compilers on your system are not sufficient for GROMACS or gmxapi,
-you may need to build, e.g., OpenMPI or MPICH, and/or build ``mpi4py`` with a
+you may need to build, e.g., OpenMPI or MPICH, and/or build mpi4py_ with a
specific MPI compiler wrapper. This can complicate building in environments such
-as Conda.
+as Conda_.
Set the MPICC environment variable to the MPI compiler wrapper and forcibly
-reinstall ``mpi4py``.
-::
+reinstall mpi4py_::
export MPICC=`which mpicc`
- pip install --no-cache-dir --upgrade --no-binary \":all:\" --force-reinstall mpi4py
-
-Installing the Python package
-=============================
-
-We recommend you install the gmxapi package in a Python virtual environment
-(``virtualenv`` or ``venv``). There are several ways to do this, and it is also
-possible to install without a virtual environment. If installing without a
-virtual environment as an un-privileged user, you may need to set the CMake
-variable ``GMXAPI_USER_INSTALL`` (``-DGMXAPI_USER_INSTALL=ON`` on the ``cmake``
-command line) and / or use the ``--user`` option with ``pip install``.
+ pip install --no-cache-dir --upgrade --no-binary ":all:" --force-reinstall mpi4py
-Sometimes the build environment can choose a different Python interpreter than
-the one you intended.
-You can set the ``PYTHON_EXECUTABLE`` CMake variable to explicitly choose the
-Python interpreter for your chosen installation.
-For example: ``-DPYTHON_EXECUTABLE=\`which python\```
+If you have a different MPI C compiler wrapper, substitute it for :command:`mpicc` above.
.. _installation:
-Recommended installation
-------------------------
+Installing the Python package
+=============================
We recommend using Python's `pip <https://pip.pypa.io/en/stable/>`_
package installer to automatically download, build, and install the latest
version of the gmxapi package into a Python
-`virtual environment <https://docs.python.org/3/tutorial/venv.html>`_.
-gmxapi requires an existing GROMACS installation.
+`virtual environment <https://docs.python.org/3/tutorial/venv.html>`_,
+though it is also possible to install without a virtual environment.
+If installing without a virtual environment as an un-privileged user,
+you may need to set the CMake variable ``GMXAPI_USER_INSTALL``
+(``-DGMXAPI_USER_INSTALL=ON`` on the :command:`cmake` command line)
+and / or use the ``--user`` option with :command:`pip install`.
+
+Recommended installation
+------------------------
The instructions in this section assume that *pip* is able to download files
-from the internet.
+from the internet. Alternatively, refer to :ref:`gmxapi offline install`.
Locate or install GROMACS
^^^^^^^^^^^^^^^^^^^^^^^^^
You need a GROMACS installation that includes the gmxapi headers and library.
If GROMACS 2020 or higher is already installed,
*and* was configured with ``GMXAPI=ON`` at build time,
-you can just source the GMXRC
+you can just source the :ref:`GMXRC <getting access to |Gromacs|>`
(so that the Python package knows where to find GROMACS)
and skip to the next section.
Set the environment variables for the GROMACS installation so that the gmxapi
headers and library can be found when building the Python package.
-If you installed to a ``gromacs-gmxapi`` directory in your home directory as
-above and you use the ``bash`` shell, do::
+If you installed to a :file:`gromacs-gmxapi` directory in your home directory as
+above and you use the :command:`bash` shell, do::
source $HOME/gromacs-gmxapi/bin/GMXRC
+.. _gmxapi venv:
+
Set up a Python virtual environment
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
If not installing in a virtual environment, you may not be able to install
necessary prerequisites (e.g. if you are not an administrator of the system you are on).
-Create a Python 3 virtual environment.
+The following instructions use the :py:mod:`venv` module.
+Alternative virtual environments, such as Conda_,
+should work fine, but are beyond the scope of this document.
+(We welcome contributed recipes!)
-For Python 3, use the ``venv`` module.
Depending on your computing environment, the Python 3 interpreter may be accessed
-with the command ``python`` or ``python3``. Use ``python --version`` and
-``python3 --version`` to figure out which you need to use. The following assumes
-the Python 3 interpreter is accessed with ``python3``.
-
-.. note::
+with the command :command:`python` or :command:`python3`. Use :command:`python --version` and
+:command:`python3 --version` to figure out which you need to use. The following assumes
+the Python 3 interpreter is accessed with :command:`python3`.
- After activating the venv, ``python`` and ``pip`` are sufficient. (The '3'
- suffix will no longer be necessary and will be omitted in the rest of this
- document.)
-
-::
+Create a Python 3 virtual environment::
python3 -m venv $HOME/myvenv
$ source $HOME/myvenv/bin/activate
(myvenv)$
-Activating the virtual environment changes your shell prompt to indicate the
-environment is active. The prompt is omitted from the remainging examples, but
-the remaining examples assume the virtualenv is still active.
-(Don't do it now, but you can deactivate the environment by running ``deactivate``.)
+.. note::
+
+ After activating the *venv*, :command:`python` and :command:`pip` are sufficient.
+ (The '3' suffix will no longer be necessary and will be omitted in the rest
+ of this document.)
+
+Activating the virtual environment may change your shell prompt to indicate the
+environment is active. The prompt is omitted from the remaining examples, but
+the remaining examples assume the virtual environment is still active.
+(Don't do it now, but you can deactivate the environment by running :command:`deactivate`.)
Install dependencies
^^^^^^^^^^^^^^^^^^^^
-It is always a good idea to update ``pip`` and ``setuptools`` before installing
+It is always a good idea to update pip_ and setuptools_ before installing
new Python packages::
pip install --upgrade pip setuptools
pip install --upgrade cmake scikit-build
-For MPI, we use mpi4py.
+For MPI, we use mpi4py_.
Make sure it is using the same MPI installation that we are building
GROMACS against and building with compatible compilers.
python -m pip install --upgrade pip setuptools
MPICC=`which mpicc` pip install --upgrade mpi4py
+.. seealso:: :ref:`mpi_requirements`
+
Install the latest version of gmxapi
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-Fetch and install the latest version of gmxapi from the Python Packaging Index::
+Fetch and install the latest official version of gmxapi from the Python Packaging Index::
+ # Get the latest official release.
pip install gmxapi
-If ``pip`` does not find your GROMACS installation, use one of the following
+The `PyPI repository <https://pypi.org/project/gmxapi/#history>`_
+may include pre-release versions,
+but :command:`pip` will ignore them unless you use the ``--pre`` flag::
+
+ # Get the latest version, including pre-release versions.
+ pip install --pre gmxapi
+
+If :command:`pip` does not find your GROMACS installation, use one of the following
environment variables to provide a hint.
gmxapi_DIR
~~~~~~~~~~
-If you have a single GROMACS installation at ``/path/to/gromacs``, it is usually
-sufficient to provide this location to ``pip`` through the ``gmxapi_DIR``
+If you have a single GROMACS installation at :file:`/path/to/gromacs`, it is usually
+sufficient to provide this location to :command:`pip` through the :envvar:`gmxapi_DIR`
environment variable.
Example::
~~~~~~~~~~~~~~~
If you have multiple builds of GROMACS distinguished by suffixes
-(e.g. *_d*, *_mpi*, etcetera), or if you need to provide extra hints to ``pip``
+(e.g. *_d*, *_mpi*, etcetera), or if you need to provide extra hints to :command:`pip`
about the software tools that were used to build GROMACS, you can specify a
directory in which the installer can find a CMake "tool chain".
Install from source
-------------------
-You can also install the ``gmxapi`` Python package from within a local copy of
+You can also install the :py:mod:`gmxapi` Python package from within a local copy of
the GROMACS source repository. Assuming you have already obtained the GROMACS
source code and you are in the root directory of the source tree, you will find
-the ``gmxapi`` Python package sources in the ``python_packaging/src`` directory.
+the :py:mod:`gmxapi` Python package sources in the :file:`python_packaging/src` directory.
::
pip install -r requirements.txt
pip install .
+.. _gmxapi offline install:
+
Offline install
---------------
pip install --no-cache-dir --no-deps --no-index --no-build-isolation .
-Refer to ``pip`` documentation for descriptions of these options.
+Refer to pip_ documentation for descriptions of these options.
If you have built or downloaded a source distribution archive, you can provide
-the archive file to ``pip`` instead of the ``.`` argument::
+the archive file to :command:`pip` instead of the ``.`` argument::
pip install gmxapi-0.1.0.tar.gz
``help()`` in an interactive Python session.
The complete documentation (which you are currently reading)
-can be browsed `online <http://gmxapi.org/>`__
+can be browsed `online <http://manual.gromacs.org/current/gmxapi/>`__
or built from a copy of the GROMACS source repository.
-.. todo:: :issue:`2985` Replace reference URL with http://manual.gromacs.org/current/gmxapi/
-
Documentation is built from a combination of Python module documentation and
static content, and requires a local copy of the GROMACS source repository.
To build the full gmxapi documentation with GROMACS, configure GROMACS with
``-DGMX_PYTHON_PACKAGE=ON`` and build the GROMACS documentation normally.
+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.
+
+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
+explicitly choose the Python installation or *venv* directory.
+
+If you use pyenv or pyenv-virtualenv to dynamically manage your Python version,
+you can help identify a particular version with ``pyenv version-name`` and the
+directory with ``pyenv prefix {version}``. For example::
+
+ -DPython3_ROOT_DIR=$(pyenv prefix $(pyenv version-name))
Docker web server
-----------------
.. todo::
Document sample_restraint package. Reference issue
- `3027 <https://redmine.gromacs.org/issues/3027>`_
+ `3027 <https://gitlab.com/gromacs/gromacs/-/issues/3027>`_
+
+Testing
+=======
+
+Note `testing requirements`_ above.
+
+After installing the :py:mod:`gmxapi` Python package,
+you can run the Python test suite from the GROMACS source tree.
+Example::
+
+ # Assuming you are in the root directory of the repository:
+ pytest python_packaging/src/test/
+
+Refer to :file:`python_packaging/README.md` for more detailed information.
+
+.. _gmxapi install troubleshooting:
Troubleshooting
===============
+AttributeError: module 'enum' has no attribute 'IntFlag'
+--------------------------------------------------------
+
+If you had older versions of some of the dependencies installed,
+you might have picked up a transitive dependency on the ``enum34`` package.
+Try::
+
+ pip uninstall -y enum34
+
+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 <https://gitlab.com/gromacs/gromacs/-/issues/>`_.
+
Couldn't find the ``gmxapi`` support library?
-If you don't want to "source" your ``GMXRC`` file, you
+---------------------------------------------
+
+If you don't want to "source" your :ref:`GMXRC <getting access to |Gromacs|>` file, you
can tell the package where to find a gmxapi compatible GROMACS installation with
``gmxapi_DIR``. E.g. ``gmxapi_DIR=/path/to/gromacs pip install .``
like ``bin`` and ``share``.
If you are not a system administrator you are encouraged to install in a Python
-virtual environment, created with virtualenv or Conda.
+virtual environment, created with virtualenv or Conda_.
Otherwise, you will need to specify the ``--user`` flag to ``pip``.
Two of the easiest problems to run into are incompatible compilers and
incompatible Python. Try to make sure that you use the same C and C++
compilers for GROMACS, for the Python package, and for the sample
-plugin. These compilers should also correspond to the ``mpicc`` compiler
-wrapper used to compile ``mpi4py``. In order to build the Python
+plugin. These compilers should also correspond to the :command:`mpicc` compiler
+wrapper used to compile mpi4py_. In order to build the Python
package, you will need the Python headers or development installation,
which might not already be installed on the machine you are using. (If
-not, then you will get an error about missing ``Python.h`` at some
+not, then you will get an error about missing :file:`Python.h` at some
point.) If you have multiple Python installations (or modules available
on an HPC system), you could try one of the other Python installations,
or you or a system administrator could install an appropriate Python dev
Pip and related Python package management tools can be a little too
flexible and ambiguous sometimes. If things get really messed up, try
-explicitly uninstalling the ``gmxapi`` module and its dependencies, then do
-it again and repeat until ``pip`` can no longer find any version of any
+explicitly uninstalling the :py:mod:`gmxapi` module and its dependencies, then do
+it again and repeat until :command:`pip` can no longer find any version of any
of the packages.
::
# ...
Successfully running the test suite is not essential to having a working
-``gmxapi`` package. We are working to make the testing more robust, but
+:py:mod:`gmxapi` package. We are working to make the testing more robust, but
right now the test suite is a bit delicate and may not work right, even
-though you have a successfully built ``gmxapi`` package. If you want to
+though you have a successfully built the :py:mod:`gmxapi` package. If you want to
troubleshoot, though, the main problems seem to be that automatic
installation of required python packages may not work (requiring manual
-installations, such as with ``pip install somepackage``) and ambiguities
+installations, such as with :command:`pip install somepackage`) and ambiguities
between python versions.
If you are working in a development branch of the repository, note that
the upstream branch may be reset to ``master`` after a new release is
tagged. In general, but particularly on the ``devel`` branch, when you
-do a ``git pull``, you should use the ``--rebase`` flag.
+do a :command:`git pull`, you should use the ``--rebase`` flag.
If you fetch this repository and then see a git status like this::
Your branch and 'origin/devel' have diverged,
and have 31 and 29 different commits each, respectively.
-then ``gmxapi`` has probably entered a new development cycle. You can
-do ``git pull --rebase`` to update to the latest development branch.
+then :py:mod:`gmxapi` has probably entered a new development cycle. You can
+do :command:`git pull --rebase` to update to the latest development branch.
-If you do a ``git pull`` while in ``devel`` and get a bunch of unexpected
-merge conflicts, do ``git merge --abort; git pull --rebase`` and you should
+If you do a :command:`git pull` while in ``devel`` and get a bunch of unexpected
+merge conflicts, do :command:`git merge --abort; git pull --rebase` and you should
be back on track.
If you are developing code for gmxapi, this should be an indication to
rebase your feature branches for the new development cycle.
+
+.. _cmake: https://pypi.org/project/cmake/
+
+.. _Conda: https://docs.conda.io/en/latest/
+
+.. _mpi4py: https://pypi.org/project/mpi4py/
+
+.. _networkx: https://pypi.org/project/networkx/
+
+.. _numpy: https://www.numpy.org/
+
+.. _pip: https://pip.pypa.io/en/stable/
+
+.. _scikit-build: https://pypi.org/project/scikit-build/
+
+.. _setuptools: https://pypi.org/project/setuptools/
biod.pnpi.spb.ru / alexxy / gromacs.git / blobdiff