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 _folder containing_ the development repo 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/folder/containing/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 not loading - 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 that of Blender's embedded interpreter. This can happen, for instance, if your OS is ArchLinux. System-wide Python will be the latest version available (say, 3.13), 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 (or will prevent you to import the lib)_.
The most simple workaround consists in using pyenv to set the right interpreter in your build session. Be careful to clear and reconfigure the whole project, afterwards:
make clear && make deps
Once rebuilt, please check the version of pyluxcore in the build log:
LuxCore/out/install/Debug/pyluxcore/pyluxcore.cpython-<version>-x86_64-linux-gnu.so
<version> should match with the embedded interpreter.
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.
Message "[BLC] 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
Debugging the wheel executing in Blender (Linux)
It is possible to debug the wheel when it is executed in Blender. To do so, follow the procedure below:
- Build the wheel in debug mode:
export LUX_BUILD_TYPE=Debug make wheel-test
- Run Blender with gdb
gdb --args blender
(nota bene: check that the latest wheel is correctly installed by BlendLuxCore)
gdb should allow you to debug any call to LuxCore