Manual build
============

The previous build scripts might easily break.

The steps to reproduce them is however
not hard, though quite a pain to automate.

This subsection describes the general
steps from within the pyRat_ repository:

1. Create a UV_ virtual environment with the
   Python_ version to build for 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

-----

2. Build the project via Python_:

.. code-block::

    python -m pip install build
    python -m build --wheel --installer=uv --outdir=wheelhouse

This will use CMake_ and the available
toolchain to compile the C++ project.

.. important::

    Ensure that the toolchain is complete and can see all
    dependencies and tools to build the C++ project:

        - MSVC shell for Windows
        - CUDA libraries and compiler
        - etc

The build directory will be located at ``./build``.

3. Repair wheel via Python_ repair package:

Each package has its own API and needs different
flags to point to installation to ship.

-----

For Windows:

.. code-block:: powershell

    # Install repair package
    python -m pip install delvewheel

    # delvewheel requires to pass the path to
    # the directory containing all DLLs.

    # If using vcpkg manifest mode with Rat-vcpkg
    $VCPKG_BIN_DIR="./build/vcpkg_installed/x64-windows-release/bin"
    # If using vcpkg classic mode with Rat-vcpkg
    $VCPKG_BIN_DIR="$env:VCPKG_ROOT/installed/x64-windows-release/bin"

    # Repair wheel
    python -m delvewheel repair ./wheelhouse/pyrat-....whl --add-path $VCPKG_BIN_DIR


For Linux:

.. code-block:: bash

    # Install repair package
    python -m pip install auditwheel

    # auditwheel requires to update the PATH and
    # LD_LIBRARY_PATH variables to find dependencies.

    # Update LD_LIBRARY_PATH to include:
    #   - Rat libraries
    #   - CUDA libraries
    #   - all other dependencies
    export LD_LIBRARY_PATH="/usr/local/lib64:/usr/local/lib64/rat:$LD_LIBRARY_PATH"

    # Repair wheel
    python -m auditwheel repair ./wheelhouse/pyrat-....whl

-----

4. Install repaired wheel into virtual environment

.. code-block::

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

5. Generate stubs from installed wheel using pybind11-stubgen_:

.. code-block::

    python -m pip install pybind11-stubgen
    pybind11-stubgen pyrat --output-dir=stubhouse --enum-class-locations LogoType:pyrat.rat.cmn.Log --enum-class-locations Direction:pyrat.rat.mat --enum-class-locations FieldAngleType:pyrat.rat.mdl.MeshData --print-invalid-expressions-as-is

This will create a ``./stubhouse/pyrat``
directory containing stubs_ for pyRat_.

The generator needs to be pointed to specific enum classes.

Invalid expressions should be patched after.

6. Patch stubs

This is done in order to replace C++ types
relicates by their Python counterparts that
could not be directly generated for various reasons.

This optional but nice to do since invlid
expressions might break the Python_ LSP trying
to read the ``.pyi`` files with C++ types.

It consists of simple text replacement for
invalid types found by the previous command.

Replacements should be something like:

.. code-block:: python

    pyi_files = (
    latest_stubs / "rat" / f"{name}.pyi"
        for name in ("cmn", "dm", "fmm", "mat", "mdl")
    )
    pyi_changes = (
        ("import typing", "import os\nimport typing"),
        (
            "lg: pyrat.rat.cmn.Log = ...",
            "lg: pyrat.rat.cmn.Log = pyrat.rat.cmn.NullLog()",
        ),
        ("current_drive: Drive = ...", "current_drive: Drive = DriveDC(0.0)"),
        ("stngs: MeshSettings = ...", "stngs: MeshSettings = MeshSettings()"),
        ("hb_curve: HBCurve = ...", "hb_curve: HBCurve = HBCurveVLV()"),
        ("rat::mdl::MeshData", "MeshData"),
        ("rat::mdl::Serializer", "Serializer"),
    )

7. Unpack wheel

.. code-block::

    python -m pip install wheel
    python -m wheel unpack ./wheelhouse/pyrat-....whl --dest ./wheelhouse

This will extract the ``.whl`` file into
a directory at ``./wheelhouse/pyrat-x.x.x``
depending on the pyRat_ version.

Anything can now be added into it before packing it back.

8. Copy patched stubs into unpacked wheel

-----

For Windows:

.. code-block:: powershell

    Copy-Item -Path ".\stubhouse\pyrat\*" -Destination ".\wheelhouse\pyrat-x.x.x\pyrat"

For Linux:

.. code-block:: bash

    cp -r ./stubhouse/pyrat/* ./wheelhouse/pyrat-x.x.x/pyrat

------

9. Pack back wheel

.. code-block::

    python -m wheel pack ./wheelhouse/pyrat-x.x.x --dest-dir ./wheelhouse

This will overwrite the
``./wheelhouse/pyrat-....whl``
file to contain patched stubs.

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