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/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) ^^^^^^^^^^^^^^^^^^ diff --git a/INSTALLING.rst b/INSTALLING.rst index 5a8ac455..bd69ae0d 100644 --- a/INSTALLING.rst +++ b/INSTALLING.rst @@ -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`_:: - $ 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`_:: - $ 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 +91,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 +102,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 +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: @@ -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`_. @@ -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:: @@ -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=``. + 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 faults. .. _CMake: https://cmake.org/ .. _Ninja: https://ninja-build.org/ @@ -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/ @@ -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/ @@ -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.