Overview
========

Building pyRat_ wheels consists in several *(fragmented)*
steps in order to ship standalone wheels with stubs_:

1. Building Python_ module and base wheel
2. Making wheels self-contained
3. Generating stubs_ for wheels
4. Patching stubs_
5. Adding final stubs into wheels

**1.** is mostly handled by the
`scikit-build-core`_ framework using CMake_ to:

- Generate an isolated Python_ virtual environment
- Run CMake_ configuration and build the project
- Generate a `Python wheel`_ ``.whl`` file from built project

The resulting base wheel will however not be portable since its
only C++ related component will be the ``pyrat.rat`` module
without any dependencies.

**2.** repairs wheels in order to make them self-contained
and portable, shipping dependencies alongside pyRat_.
This step uses Python_ modules depending on the host platform.

**3.**, **4.**, and **5.** are mostly hacks hacks to generate stubs_
(``.pyi`` type hint files for class descriptions, function
signatures and more), patch them if needed and pack them back into
the wheel to ship a Python_ module with decent user experience.

.. note::

    Full names of the resulting ``.whl`` will depend on the Python_
    version used for compilation, pyRat_ version and host platform.

    For instance ``pyrat-1.0.0-cp314-cp314-win_amd64.whl`` is built:

        - with pyRat_ ``v1.0.0``
        - with and for Python_ ``v3.14``
        - on Windows AMD64.
    
    The default name used will be ``pyrat-....whl`` for this page.

.. 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/