From 3c199f57b6c4b032224141b76715d14c3b0419e7 Mon Sep 17 00:00:00 2001 From: "Joshua A. Anderson" Date: Mon, 29 Jul 2024 08:22:21 -0400 Subject: [PATCH 1/7] 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. From a2eb777a35a37704fa8b31577e8246fb752bdf3c Mon Sep 17 00:00:00 2001 From: "Joshua A. Anderson" Date: Mon, 29 Jul 2024 08:25:49 -0400 Subject: [PATCH 2/7] Update change log. --- CHANGELOG.rst | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/CHANGELOG.rst b/CHANGELOG.rst index 3e2b3ae5..8d438f36 100644 --- a/CHANGELOG.rst +++ b/CHANGELOG.rst @@ -10,6 +10,14 @@ Change Log 3.x --- +3.3.1 (not yet released) +^^^^^^^^^^^^^^^^^^^^^^^^ + +*Changed:* + +* Improved build instructions + (`#376 `__). + 3.3.0 (2024-05-29) ^^^^^^^^^^^^^^^^^^ From 366e0baad0a5b1bf0e84e2250b7fabcb356a9e9e Mon Sep 17 00:00:00 2001 From: "Joshua A. Anderson" Date: Mon, 29 Jul 2024 08:30:16 -0400 Subject: [PATCH 3/7] Fix build error. --- INSTALLING.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/INSTALLING.rst b/INSTALLING.rst index f247ee99..7b7fcc37 100644 --- a/INSTALLING.rst +++ b/INSTALLING.rst @@ -230,7 +230,7 @@ Open the file :file:`html/index.html` in your web browser to view the documentat .. tip:: 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:: + the side panel and provide more useful error messages. .. tip:: From 3abf865ba0171a60353b0957b12cb74fbe9299ed Mon Sep 17 00:00:00 2001 From: "Joshua A. Anderson" Date: Mon, 29 Jul 2024 09:01:24 -0400 Subject: [PATCH 4/7] Recommend uv. --- INSTALLING.rst | 18 +++++++++++------- 1 file changed, 11 insertions(+), 7 deletions(-) diff --git a/INSTALLING.rst b/INSTALLING.rst index 7b7fcc37..9577a2f7 100644 --- a/INSTALLING.rst +++ b/INSTALLING.rst @@ -26,12 +26,16 @@ Conda package PyPI ^^^^ -Use **pip** to install **gsd** binaries from PyPI_: +Use **pip** or **uv** to install **gsd** binaries from PyPI_: .. code-block:: bash $ python3 -m pip install gsd +.. code-block:: bash + + $ uv pip install gsd + Compile from source ------------------- @@ -49,7 +53,7 @@ To build the **gsd** Python package from source: $ cd gsd -4. `Install with pip`_:: +4. `Install with uv`_:: $ python3 -m pip install . @@ -133,17 +137,17 @@ Release tarballs are also available on the `GitHub release pages`_. .. _git book: https://git-scm.com/book .. _Git: https://git-scm.com/ -.. _Install with pip: +.. _Install with uv: -Install with pip -^^^^^^^^^^^^^^^^^^^^^^^ +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 $ cd {{ path/to/gsd/repository }} - $ python3 -m pip install . + $ uv pip install . .. Build with CMake for development: From e220dd2bba1e8a3d125187a80da362e5cecaaa3a Mon Sep 17 00:00:00 2001 From: "Joshua A. Anderson" Date: Mon, 29 Jul 2024 09:13:18 -0400 Subject: [PATCH 5/7] Remove unnecessary steps from uv source installation. --- INSTALLING.rst | 21 ++++++++++----------- 1 file changed, 10 insertions(+), 11 deletions(-) diff --git a/INSTALLING.rst b/INSTALLING.rst index 9577a2f7..7c3eb6dc 100644 --- a/INSTALLING.rst +++ b/INSTALLING.rst @@ -26,39 +26,38 @@ Conda package PyPI ^^^^ -Use **pip** or **uv** to install **gsd** binaries from PyPI_: +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 - $ uv pip install gsd + $ python3 -m pip install gsd Compile from source ------------------- To build the **gsd** Python package from source: -1. `Install prerequisites`_:: - - $ {{ package-manager }} install cmake cython git ninja numpy python pytest - -2. `Obtain the source`_:: +1. `Obtain the source`_:: $ git clone https://github.com/glotzerlab/gsd -3. Change to the repository directory:: +2. Change to the repository directory:: $ cd gsd -4. `Install with uv`_:: +3. `Install with uv`_:: $ python3 -m pip install . - **OR** `Build with CMake for development`_:: +4. **OR** `Install prerequisites`_ and `Build with CMake for development`_:: + $ {{ package-manager }} install cmake cython ninja numpy python pytest $ cmake -B build -S . -GNinja $ cd build $ ninja From fc4c3c65126c2db0d74cfdbedfc6ecaba5f6dc73 Mon Sep 17 00:00:00 2001 From: "Joshua A. Anderson" Date: Mon, 29 Jul 2024 09:21:32 -0400 Subject: [PATCH 6/7] Remove shell prompts. --- INSTALLING.rst | 62 +++++++++++++++++++++++++------------------------- 1 file changed, 31 insertions(+), 31 deletions(-) diff --git a/INSTALLING.rst b/INSTALLING.rst index 7c3eb6dc..d23d5630 100644 --- a/INSTALLING.rst +++ b/INSTALLING.rst @@ -21,7 +21,7 @@ Conda package .. code-block:: bash - $ mamba install gsd + mamba install gsd PyPI ^^^^ @@ -30,13 +30,13 @@ Use **uv** or **pip** to install **gsd** binaries from PyPI_: .. code-block:: bash - $ uv pip install gsd + uv pip install gsd **OR** .. code-block:: bash - $ python3 -m pip install gsd + python3 -m pip install gsd Compile from source ------------------- @@ -45,40 +45,40 @@ To build the **gsd** Python package from source: 1. `Obtain the source`_:: - $ git clone https://github.com/glotzerlab/gsd + git clone https://github.com/glotzerlab/gsd 2. Change to the repository directory:: - $ cd gsd + cd gsd 3. `Install with uv`_:: - $ python3 -m pip install . + python3 -m pip install . 4. **OR** `Install prerequisites`_ and `Build with CMake for development`_:: - $ {{ package-manager }} install cmake cython ninja numpy python pytest - $ cmake -B build -S . -GNinja - $ cd build - $ ninja + {{ package-manager }} install cmake cython ninja numpy python pytest + cmake -B build -S . -GNinja + cd build + ninja To run the tests: 1. `Run tests`_:: - $ python3 -m pytest gsd + python3 -m pytest gsd 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 {{ path/to/gsd/repository }} - $ doxygen - $ sphinx-build -b html doc html + cd {{ path/to/gsd/repository }} + doxygen + sphinx-build -b html doc html The sections below provide details on each of these steps. @@ -124,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`_. @@ -145,8 +145,8 @@ Use **uv** to install the Python module into your virtual environment: .. code-block:: bash - $ cd {{ path/to/gsd/repository }} - $ uv pip install . + cd {{ path/to/gsd/repository }} + uv pip install . .. Build with CMake for development: @@ -154,21 +154,21 @@ Build with CMake for development ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 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``. +in the given build directory. First, configure the build with ``cmake``: .. code-block:: bash - $ cd {{ path/to/gsd/repository }} - $ cmake -B build -S . -GNinja + cd {{ path/to/gsd/repository }} + cmake -B build -S . -GNinja Then, build the code: .. code-block:: bash - $ cd build - $ ninja + cd build + ninja -After you modify the code, execute ``ninja`` to rebuild. ``ninja`` will automatically reconfigure +Execute ``ninja`` to rebuild after you modify the code. ``ninja`` will automatically reconfigure as needed. .. tip:: @@ -179,7 +179,7 @@ as needed. .. important:: When using a virtual environment, activate the environment and set the cmake prefix path - before running CMake_: ``$ export CMAKE_PREFIX_PATH=``. + before running CMake_: ``export CMAKE_PREFIX_PATH=``. .. warning:: @@ -200,13 +200,13 @@ Use `pytest`_ to execute unit tests: .. code-block:: bash - $ python3 -m pytest 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 + python3 -m pytest --pyargs gsd -p gsd.pytest_plugin_validate --validate .. _pytest: https://docs.pytest.org/ @@ -219,14 +219,14 @@ Run `Doxygen`_ to generate the C documentation: .. code-block:: bash - $ cd {{ path/to/gsd/repository }} - $ doxygen + cd {{ path/to/gsd/repository }} + doxygen Run `Sphinx`_ to build the HTML documentation: .. code-block:: bash - $ sphinx-build -b html doc html + sphinx-build -b html doc html Open the file :file:`html/index.html` in your web browser to view the documentation. @@ -239,7 +239,7 @@ Open the file :file:`html/index.html` in your web browser to view the documentat When using CMake builds, set PYTHONPATH to the build directory before running ``sphinx-build``:: - $ PYTHONPATH=build sphinx-build -b html doc html + PYTHONPATH=build sphinx-build -b html doc html .. _Sphinx: https://www.sphinx-doc.org/ .. _Doxygen: https://www.doxygen.nl/ From d7c02958cbfb3fda75c710d6e59fc618aa50bd06 Mon Sep 17 00:00:00 2001 From: "Joshua A. Anderson" Date: Mon, 29 Jul 2024 09:45:32 -0400 Subject: [PATCH 7/7] Revise installation docs. --- INSTALLING.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/INSTALLING.rst b/INSTALLING.rst index d23d5630..bd69ae0d 100644 --- a/INSTALLING.rst +++ b/INSTALLING.rst @@ -186,7 +186,7 @@ as needed. 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. + running, or unexplainable faults. .. _CMake: https://cmake.org/ .. _Ninja: https://ninja-build.org/