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.
- LuxCore developers who want to use Blender as a tool to test changes to the core engine.
Statement of problem
BlendLuxCore (BLC) is composed of two parts:
- A Python module, essentially identical to the BlendLuxCore repository.
- Underlying pyluxcore library, compiled from the LuxCore repository. Typically distributed as a Python wheel.
The python module is distributed as a zip-file, which is installed in Blender as an extension. During the installation process, the pyluxcore-wheel is downloaded from PyPi. During subsequent startup of Blender, the python script verifies the presence of pyluxcore and an additional (time-consuming) download is not necessary.
However, when developing BLC, we typically need to:
- Make Blender load a development version of the python module
- And optionally make BLC load a development version of the pyluxcore-wheel
The first goal can be achieved via an environment variable:
BLC_DEV_PATH: path _folder containing_ the development repo of BlendLuxCore
For the second goal, two methods are available:
- Another environment variable,
BLC_WHEEL_PATH: path to a development version of the wheel - A subfolder
pyluxcore_custom/within the installed python module. A development version of the wheel can be copied into this folder.
These methods will be explained in detail in the sections below.
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
The first goal can be achieved via an environment variable:
BLC_DEV_PATH: path _folder containing_ the development repo of BlendLuxCore
In the environment where you run Blender, and BlendLuxCore has already been installed using the normal installation method, set BLC_DEV_PATH to the path of your dev repository:
export BLC_DEV_PATH=/path/to/folder/containing/BlendLuxCore
For clarification, set this folder like you would set the systems PATH or PYTHONPATH variable, i.e. so that python can import BlendLuxCore from this location!
When this variable is set, all python code from the development repo will be loaded, except the main __init__.py file. Changes to the latter may require a full reinstallation of BlendLuxCore, depending on what was changed.
As a verification of this working correctly, the console output of Blender at startup will show the following line:
[BLC] USING LOCAL DEV VERSION OF BlendLuxCore
Scenario #2: Working on pyluxcore
For the second goal, two methods are available:
- Another environment variable,
BLC_WHEEL_PATH: path to a development version of the wheel - A subfolder
pyluxcore_custom/within the installed python module. A development version of the wheel can be copied into this folder.
Note that the presence of a file inside pyluxcore_custom/ will take precendence over the BLC_WHEEL_PATH variable!
To simplify further explanations, all explanations are presented in terms of the BLC_WHEEL_PATH variable.
When this variable is set, BLC computes a hash of the linked wheel. This hash is compared against information stored in the file pyluxcore_installation_info.txt, located within the installed python module. If the information matches, installation is skipped. Else, if it does not match, the local pyluxcore-wheel will be installed, replacing the previous version.
The text file also stores information if the previous installation was from PyPi or from a local wheel. This means, when the environment variable is unset after testing, it will again be replaced with the regular version from PyPi.
As a verification, check for the following lines in the console output of Blender at startup:
[BLC] Installing local version of pyluxcore --> A new local version will be installed. Replaces any previous installation.
[BLC] skipping pyluxcore installation. Custom wheel matching hash already installed. --> A local version was previously installed and is used again.
[BLC] installing pyluxcore version: --> pyluxcore will be installed from PyPi. Replaces any previous installation.
[BLC] skipping pyluxcore installation. Specified version already installed. --> A PyPi version was previously installed and is used again.
(Note: Further error messages exist but they are out of the scope of this article.)
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
Utility shell script for launching Blender
The BlendLuxCore repository contains a shell script, called blendev (short for blender-development), located inside the debug-helpers subdirectory.
The purpose of this script is to easily launch Blender and switch between multiple versions of Blender, a regularly installed version of BlendLuxCore and pyluxcore, local development code of BlendLuxCore, and locally compiled versions of pyluxcore.
At the time of writing, this script is available only for linux/bash development.
Please see the Readme.md supplied alongside the script, and its internal help output blendev -h for detailed instructions on how to use it.
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