Developing and debugging BlendLuxCore
Introduction
Goal and audience
This document explains the approach to install a development version of BlendLuxCore (BLC) in Blender, so that it's possible to test and debug it.
The targeted audience encompasses:
- BlendLuxCore development contributors
- BlendLuxCore advanced users/alpha testers who have been provided a dev version of BLC, in order to test a new feature.
Statement of problem
BlendLuxCore (BLC) is in two parts:
- Python module
- Underlying pyluxcore library, brought by a Python wheel
In normal life, Blender loads the BLC Python module that has been regularly installed, which in turn loads the wheel from PyPi.
However, when developing BLC, we typically need to:
- Make Blender load a development version of BLC
- And optionally make BLC load a development version of the wheel
Those goals can be achieved via 2 environment variables:
BLC_DEV_PATH: path to the development version of BlendLuxCoreBLC_WHEEL_PATH: path to a development version of the wheel
We'll see the use of those variables through several scenarios.
Prerequisites
In the next parts of the document, we shall assume:
You have set a development environment on your local computer with:
- a cloned repository of BlendLuxCore
- and optionally a cloned repository of LuxCore
You know how to "pack" BlendLuxCore, ie build an installable package of BLC:
cmake -S . -B out -DCMAKE_BUILD_TYPE=Release cmake --build out
You know how to build a test wheel from LuxCore:
make wheel-test
Scenario #1: Working on BLC, using standard pyluxcore
In the environment where you run Blender, set BLC_DEV_PATH to the path of your dev repository:
export BLC_DEV_PATH=/path/to/BlendLuxCore
Pack BLC, run Blender and install your packed version
Scenario #2: Working on pyluxcore
<WORK IN PROGRESS>
Tips & Tricks
Useful directories
The extension is installed in:
$HOME/.config/blender/<blender-version>/extensions/user_default
The wheel is installed in:
$HOME/.config/blender/<blender version>/extensions/.local/lib/python<python-version>/site-packages
Wheel - Python version mismatch between System and Blender
You may work in an environment where the version of the system-wide Python interpreter is different from Blender's embedded one. This is the case, for instance, if your OS is ArchLinux. System-wide Python will be the latest version available (say, 3.11), whereas Blender interpreter will be an older one (for instance, 3.11).
If you build a test wheel without precaution, the tag will be the one of your system-wide Python and, when you try to install it in Blender, the embedded interpreter will prevent you to do so.
The most simple workaround consists in using pyenv to set the right interpreter in your build session.
Another point to be cautious about, in the present case: if pyluxcore is already installed system-wide, for a different version of Python than Blender, then Blender will fail installing the wheel. In this case, you'll have to uninstall your system-wide pyluxcore (pip uninstall pyluxcore) if you want Blender to install correctly.
"skipping pyluxcore installation. Custom wheel matching hash already installed."
If you think this message is irrelevant, clean the following file: $HOME/.config/blender/4.2/extensions/.user/user_default/BlendLuxCore/pyluxcore_installation_info.txt