Skip to content

Commit

Permalink
Revise build instructions.
Browse files Browse the repository at this point in the history
  • Loading branch information
@joaander
joaander committed Jul 29, 2024
1 parent 9c76443 commit 3c199f5
Show file tree
Hide file tree
Showing 2 changed files with 56 additions and 77 deletions.
9 changes: 4 additions & 5 deletions .gitignore
View file
Original file line number Diff line number Diff line change
@@ -1,12 +1,11 @@
*.sublime-workspace
__pycache__
*.DS_Store
*.pyc
*.pyo
*.so
fl.c
build/*
build
devdoc
dist
gsd.egg-info
__pycache__
devdoc
build
html
124 changes: 52 additions & 72 deletions INSTALLING.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,7 @@ Conda package
^^^^^^^^^^^^^

**gsd** is available on conda-forge_ for the *linux-64*, *linux-aarch64*, *linux-ppc64le*, *osx-64*,
*osx-arm64* and *win-64* architectures. Install with:
*osx-arm64* and *win-64* architectures. Execute the following command to install **gsd**:

.. code-block:: bash
Expand All @@ -26,7 +26,7 @@ Conda package
PyPI
^^^^

Use **pip** to install **gsd** binaries:
Use **pip** to install **gsd** binaries from PyPI_:

.. code-block:: bash
Expand All @@ -39,37 +39,43 @@ To build the **gsd** Python package from source:

1. `Install prerequisites`_::

$ <package-manager> install cmake cython git numpy python pytest
$ {{ package-manager }} install cmake cython git ninja numpy python pytest

2. `Obtain the source`_::

$ git clone https://github.com/glotzerlab/gsd

3. `Install with setuptools`_::
3. Change to the repository directory::

$ python3 -m pip install -e gsd
$ cd gsd

4. `Install with pip`_::

$ python3 -m pip install .

**OR** `Build with CMake for development`_::

$ cmake -B build/gsd -S gsd
$ cmake --build build/gsd
$ cmake -B build -S . -GNinja
$ cd build
$ ninja

To run the tests (optional):
To run the tests:

1. `Run tests`_::

$ pytest --pyargs gsd
$ python3 -m pytest gsd

To build the documentation from source (optional):
To build the documentation from source:

1. `Install prerequisites`_::

$ <package-manager> install breathe doxygen sphinx furo ipython sphinx-copybutton
$ {{ package-manager }} install breathe doxygen sphinx furo ipython sphinx-copybutton

2. `Build the documentation`_::

$ cd gsd && doxygen && cd ..
$ sphinx-build -b html gsd/doc build/gsd-documentation
$ cd {{ path/to/gsd/repository }}
$ doxygen
$ sphinx-build -b html doc html

The sections below provide details on each of these steps.

Expand All @@ -82,28 +88,21 @@ Install prerequisites

.. note::

This documentation is generic. Replace ``<package-manager>`` with your package or module
This documentation is generic. Replace ``{{ package-manager }}`` with your package or module
manager. You may need to adjust package names and/or install additional packages, such as
``-dev`` packages that provide headers needed to build **gsd**.

.. tip::

Create or use an existing `virtual environment`_, one place where you can install dependencies
and **gsd**::

$ python3 -m venv gsd-venv

You will need to activate your environment before installing or configuring **gsd**::

$ source gsd-venv/bin/activate

**General requirements:**

* **C compiler** (tested with gcc 10-14, clang 10-18, Visual Studio 2019-2022)
* **Python** >= 3.9
* **numpy** >= 1.19.0
* **Cython** >= 0.22

**To execute unit tests:**

* **pytest** >= 3.9.0

**To build the documentation**:

* **breathe**
Expand All @@ -114,11 +113,6 @@ Install prerequisites
* **sphinx-copybutton**
* an internet connection

**To execute unit tests:**

* **pytest** >= 3.9.0

.. _virtual environment: https://docs.python.org/3/library/venv.html

.. _Obtain the source:

Expand All @@ -139,49 +133,40 @@ Release tarballs are also available on the `GitHub release pages`_.
.. _git book: https://git-scm.com/book
.. _Git: https://git-scm.com/

.. _Install with setuptools:
.. _Install with pip:

Install with setuptools
Install with pip
^^^^^^^^^^^^^^^^^^^^^^^

Use **pip** to install the Python module into your virtual environment:

.. code-block:: bash
$ python3 -m pip install -e gsd
$ cd {{ path/to/gsd/repository }}
$ python3 -m pip install .
.. Build with CMake for development:
Build with CMake for development
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

In addition to the setuptools build system. GSD also provides a `CMake`_ configuration for
development and testing. You can assemble a functional Python module in the given build directory.
First, configure the build with ``cmake``.
GSD also provides `CMake`_ scripts for development and testing that build a functional Python module
in the given build directory. First, configure the build with ``cmake``.

.. code-block:: bash
$ cmake -B build/gsd -S gsd
$ cd {{ path/to/gsd/repository }}
$ cmake -B build -S . -GNinja
Then, build the code:

.. code-block:: bash
$ cmake --build build/gsd
When modifying code, you only need to repeat the build step to update your build - it will
automatically reconfigure as needed.

.. tip::

Use Ninja_ to perform incremental builds in less time::

$ cmake -B build/gsd -S gsd -GNinja

.. tip::
$ cd build
$ ninja
Place your build directory in ``/tmp`` or ``/scratch`` for faster builds. CMake_ performs
out-of-source builds, so the build directory can be anywhere on the filesystem.
After you modify the code, execute ``ninja`` to rebuild. ``ninja`` will automatically reconfigure
as needed.

.. tip::

Expand All @@ -193,6 +178,13 @@ automatically reconfigure as needed.
When using a virtual environment, activate the environment and set the cmake prefix path
before running CMake_: ``$ export CMAKE_PREFIX_PATH=<path-to-environment>``.

.. warning::

When using a ``conda`` environment for development, make sure that the environment does not
contain ``clang``, ``gcc``, or any other compiler or linker. These interfere with the native
compilers on your system and will result in compiler errors when building, linker errors when
running, or unexplainable segmentation faults.

.. _CMake: https://cmake.org/
.. _Ninja: https://ninja-build.org/

Expand All @@ -205,20 +197,14 @@ Use `pytest`_ to execute unit tests:

.. code-block:: bash
$ python3 -m pytest --pyargs gsd
$ python3 -m pytest gsd
Add the ``--validate`` option to include longer-running validation tests:

.. code-block:: bash
$ python3 -m pytest --pyargs gsd -p gsd.pytest_plugin_validate --validate
.. tip::

When using CMake builds, change to the build directory before running ``pytest``::

$ cd build/gsd

.. _pytest: https://docs.pytest.org/

.. _Build the documentation:
Expand All @@ -230,32 +216,27 @@ Run `Doxygen`_ to generate the C documentation:

.. code-block:: bash
$ cd gsd
$ cd {{ path/to/gsd/repository }}
$ doxygen
$ cd ..
Run `Sphinx`_ to build the HTML documentation:

.. code-block:: bash
$ sphinx-build -b html gsd/doc build/gsd-documentation
$ sphinx-build -b html doc html
Open the file :file:`build/gsd-documentation/index.html` in your web browser to view the
documentation.
Open the file :file:`html/index.html` in your web browser to view the documentation.

.. tip::

When iteratively modifying the documentation, the sphinx options ``-a -n -W -T --keep-going``
are helpful to produce docs with consistent links in the side panel and to see more useful error
messages::

$ sphinx-build -a -n -W -T --keep-going -b html gsd/doc build/gsd-documentation
Add the sphinx options ``-a -n -W -T --keep-going`` to produce docs with consistent links in
the side panel and provide more useful error messages::

.. tip::

When using CMake builds, set PYTHONPATH to the build directory before running ``sphinx-build``::

$ PYTHONPATH=build/gsd sphinx-build -b html gsd/doc build/gsd-documentation
$ PYTHONPATH=build sphinx-build -b html doc html

.. _Sphinx: https://www.sphinx-doc.org/
.. _Doxygen: https://www.doxygen.nl/
Expand All @@ -271,6 +252,5 @@ Using the C library
Using the pure Python reader
^^^^^^^^^^^^^^^^^^^^^^^^^^^^

If you only need to read files, you can skip installing and just extract the module modules
``gsd/pygsd.py`` and ``gsd/hoomd.py``. Together, these implement a pure Python reader for **gsd**
and **HOOMD** files - no C compiler required.
The Python modules ``gsd/pygsd.py`` and ``gsd/hoomd.py`` implement a pure Python reader for **gsd**
and **HOOMD** files.

0 comments on commit 3c199f5

Please sign in to comment.