Build
=====

This section focuses and the build of the
pyRat_ Python_ module and its wheels.

The result of building pyRat_ is a `Python wheel`_.
`Python wheels`_ are the modern way of distributing
Python_ packages in a more controlled and isolated
manner than the previous Python_ eggs.

The idea is to allow users to very easily transport
wheels by simply moving a file around and using
``pip`` to install the package into any environment:

.. code-block:: bash

    python -m pip install ./pyrat-....whl

``numpy`` being the only external Python_ dependency
of the ``pyrat`` Python_ module installing it is
very straightforward once a wheel is acquired.

For simpler user experience pyRat_ wheels directly ships CUDA
libraries used by Rat, avoiding the need for the user to
install the whole toolkit on the machine at hand.
This however comes at the cost of **a quite beefy 430MB wheel**
file whereas simpler wheels can be just a few MB in size.

Build can of course be modified to suit specific
needs if required by modifying sources accordingly.

The following subsections describe build
steps in order to end up with the coveted
``pyrat-1.0.0-cp314-cp314-win_amd64.whl``
wheel file, in that case:

- on Windows
- with CPython ``v3.14``
- with pyRat_ ``v1.0.0``

.. pyRat: Build table of contents
.. toctree::
   :maxdepth: 2
   :caption: PYRAT BUILD CONTENTS

   overview
   scripts
   manual

.. Links
.. _CMake: https://cmake.org
.. _Project-Rat: https://gitlab.com/project-rat
.. _pybind11: https://github.com/pybind/pybind11
.. _pybind11-stubgen: https://github.com/pybind/pybind11-stubgen
.. _pyRat: https://gitlab.com/project-rat-extras/pyrat
.. _pyrat/scripts/py/make_wheel.py: https://gitlab.com/project-rat-extras/pyrat/-/blob/main/scripts/py/make_wheel.py?ref_type=heads
.. _pyrat/scripts/py/make_wheel_vcpkg.py: https://gitlab.com/project-rat-extras/pyrat/-/blob/main/scripts/py/make_wheel_vcpkg.py?ref_type=heads
.. _Python: https://www.python.org/
.. _Python wheel: https://pythonwheels.com/
.. _Python wheels: https://pythonwheels.com/
.. _Rat-Containers: https://gitlab.com/project-rat-extras/rat-containers
.. _Rat-Models: https://gitlab.com/project-rat/rat-models
.. _Rat-vcpkg: https://gitlab.com/project-rat-extras/rat-vcpkg
.. _scikit-build-core: https://github.com/scikit-build/scikit-build-core
.. _stubs: https://typing.python.org/en/latest/guides/writing_stubs.html
.. _UV: https://github.com/astral-sh/uv
.. _vcpkg: https://vcpkg.io/en/