Scripts
=======

.. caution::

    The following scripts do not appear to be very general
    and have only been tested using installations from Rat-vcpkg_
    and Rat-Containers_, and they might break on different machine.

    If so one can skip this section and build
    the wheel by hand, mimicing all steps.

All the build steps are implemented within
*(very hacky)* Python_ build scripts:

- `pyrat/scripts/py/make_wheel.py`_ for general case
- `pyrat/scripts/py/make_wheel_vcpkg.py`_ if using vcpkg_ toolchain

which desperately try to fight questionnable workflows.

These scripts expects several things:

- ``uv`` command available or the ``UV_ROOT`` environment variable
- ``vcpkg`` command available or the ``VCPKG_ROOT`` environment
  variable pointing to local vcpkg for ``make_wheel_vcpkg.py``
- ``ninja`` command available or the ``NINJA_ROOT`` environment
  variable for ``make_wheel_vcpkg.py`` 

In order to run them:

- Create a UV_ virtual environment to
  have access to Python and activate it:

-----

For Windows:

.. code-block:: powershell

    uv venv venv --python=3.12
    .\venv\Scripts\activate

For Linux:

.. code-block:: bash

    uv venv venv --python=3.12
    source ./venv/bin/activate

-----

.. note::

    The Python version of this environment is not important.

    The later Python build scripts will create another
    virtual environment depending on the Python version
    requested to build the wheel for regardless.

- Clone the pyRat_ repository and navigate into it:

.. code-block:: bash

    git clone https://gitlab.com/project-rat-extras/pyrat.git
    cd pyrat

- Run the Python build script:

-----

For Windows, with vcpkg_:

.. code-block:: powershell

    # Set the VCPKG_ROOT env var to point
    # to local vcpkg repository installation
    $env:VCPKG_ROOT="C:\path\to\vcpkg"

    # wheel for Python 3.14, with stubs
    .\scripts\py\make_wheel_vcpkg.py -p 3.14 -s

For Linux:

.. code-block:: bash

    # wheel for Python 3.14, with stubs
    ./scripts/py/make_wheel.py -p 3.14 -s

-----

This will result in a wheel stored
at ``./wheelhouse/pyrat-....whl`` .

.. note::

    Building wheels will generate virtual environments
    for each requested Python_ version.

    The ``pyrat`` Python_ module should
    be installed in all of them at the end.

    Feel free to try it out.

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