From 3c199f57b6c4b032224141b76715d14c3b0419e7 Mon Sep 17 00:00:00 2001 From: "Joshua A. Anderson" Date: Mon, 29 Jul 2024 08:22:21 -0400 Subject: [PATCH] Revise build instructions. --- .gitignore | 9 ++-- INSTALLING.rst | 124 +++++++++++++++++++++---------------------------- 2 files changed, 56 insertions(+), 77 deletions(-) diff --git a/.gitignore b/.gitignore index c5e0a140..42214950 100644 --- a/.gitignore +++ b/.gitignore @@ -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 diff --git a/INSTALLING.rst b/INSTALLING.rst index 5a8ac455..f247ee99 100644 --- a/INSTALLING.rst +++ b/INSTALLING.rst @@ -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 @@ -26,7 +26,7 @@ Conda package PyPI ^^^^ -Use **pip** to install **gsd** binaries: +Use **pip** to install **gsd** binaries from PyPI_: .. code-block:: bash @@ -39,37 +39,43 @@ To build the **gsd** Python package from source: 1. `Install prerequisites`_:: - $ 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`_:: - $ 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. @@ -82,21 +88,10 @@ Install prerequisites .. note:: - This documentation is generic. Replace ```` 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) @@ -104,6 +99,10 @@ Install prerequisites * **numpy** >= 1.19.0 * **Cython** >= 0.22 +**To execute unit tests:** + +* **pytest** >= 3.9.0 + **To build the documentation**: * **breathe** @@ -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: @@ -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:: @@ -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=``. +.. 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/ @@ -205,7 +197,7 @@ 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: @@ -213,12 +205,6 @@ Add the ``--validate`` option to include longer-running validation tests: $ 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: @@ -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/ @@ -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.