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:

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

For Linux:

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

  1. Build the project via Python:

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.

  1. Repair wheel via Python repair package:

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

For Windows:

# 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:

# 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

  1. Install repaired wheel into virtual environment

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

  1. Generate stubs from installed wheel using pybind11-stubgen:

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.

  1. 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:

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"),
)

  1. Unpack wheel

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.

  1. Copy patched stubs into unpacked wheel

For Windows:

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

For Linux:

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

  1. Pack back wheel

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

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