Skip to content

Commit

Permalink
Merge pull request #376 from glotzerlab/revise-build-docs
Browse files Browse the repository at this point in the history 
Revise build instructions.
  • Loading branch information
@joaander
joaander authored Aug 12, 2024
2 parents 6174650 + d7c0295 commit 06a1ee7
Show file tree
Hide file tree
Showing 3 changed files with 79 additions and 89 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
8 changes: 8 additions & 0 deletions CHANGELOG.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,14 @@ Change Log
3.x
---

3.3.1 (not yet released)
^^^^^^^^^^^^^^^^^^^^^^^^

*Changed:*

* Improved build instructions
(`#376 <https://github.com/glotzerlab/gsd/pull/376>`__).

3.3.0 (2024-05-29)
^^^^^^^^^^^^^^^^^^

Expand Down
151 changes: 67 additions & 84 deletions INSTALLING.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -17,59 +17,68 @@ 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
$ mamba install gsd
mamba install gsd
PyPI
^^^^

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

.. code-block:: bash
$ python3 -m pip install gsd
uv pip install gsd
**OR**

.. code-block:: bash
python3 -m pip install gsd
Compile from source
-------------------

To build the **gsd** Python package from source:

1. `Install prerequisites`_::
1. `Obtain the source`_::

$ <package-manager> install cmake cython git numpy python pytest
git clone https://github.com/glotzerlab/gsd

2. `Obtain the source`_::
2. Change to the repository directory::

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

3. `Install with setuptools`_::
3. `Install with uv`_::

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

**OR** `Build with CMake for development`_::
4. **OR** `Install prerequisites`_ and `Build with CMake for development`_::

$ cmake -B build/gsd -S gsd
$ cmake --build build/gsd
{{ package-manager }} install cmake cython ninja numpy python pytest
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 +91,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 +116,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 @@ -127,7 +124,7 @@ Obtain the source

Clone using Git_::

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

Release tarballs are also available on the `GitHub release pages`_.

Expand All @@ -139,49 +136,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 uv:

Install with setuptools
^^^^^^^^^^^^^^^^^^^^^^^
Install with uv
^^^^^^^^^^^^^^^^

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

.. code-block:: bash
$ python3 -m pip install -e gsd
cd {{ path/to/gsd/repository }}
uv 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
cd build
ninja
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::

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.
Execute ``ninja`` to rebuild after you modify the code. ``ninja`` will automatically reconfigure
as needed.

.. tip::

Expand All @@ -191,7 +179,14 @@ automatically reconfigure as needed.
.. important::

When using a virtual environment, activate the environment and set the cmake prefix path
before running CMake_: ``$ export CMAKE_PREFIX_PATH=<path-to-environment>``.
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 faults.

.. _CMake: https://cmake.org/
.. _Ninja: https://ninja-build.org/
Expand All @@ -205,19 +200,13 @@ 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
python3 -m pytest --pyargs gsd -p gsd.pytest_plugin_validate --validate
.. _pytest: https://docs.pytest.org/

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

.. code-block:: bash
$ cd gsd
$ doxygen
$ cd ..
cd {{ path/to/gsd/repository }}
doxygen
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 +255,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 06a1ee7

Please sign in to comment.