Developing and debugging BlendLuxCore

Introduction

Note: This article is work in progress for the development of BlendLuxCore v2.11. Instructions for v2.10 can be found in the article Developing and debugging BlendLuxCore v2.10

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.
• Use cases with non-standard requirements, e.g. the need to perform an offline installation.

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

In addition, there may be the need to handle some unusual cases, for example performing an offline-installation in restrictive company networks where dependencies cannot be downloaded via pip.

To facilitate the configuration of these scenarios, we provide a separate extension, BlendLuxHelper.

The setup and usage of BlendLuxCore together with BlendLuxHelper 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

You made yourself familiar with Blenders official Add-on Development Setup guide.

Installation of BlendLuxHelper and Setup of BlendLuxCore

Step 1:
Uninstall any previously installed version of BLC.

Step 2 (optional):
Add a new local extension repository for installation of the BLC/BLH development environment.

Step 3:
Download the latest release of BLH on GitHub, or - if necessary - build the extension from source.

Install BLH in Blender thorugh the extensions menu using the Install from Disk option.

Step 4:
Create a symbolic link to the local BLC git-repository, as outlined in Blenders Add-on Development Setup guide. In the Addon preferences menu of BLH, at the bottom, you can find a function to perform this step with a graphical interface.

Step 5:
Close and reopen Blender. Go to the addon-preferences menu and enable the BLC addon. The addon should now be installed, including the installation of pyluxcore and its dependencies.

Scenario #1: Working on BLC, using standard pyluxcore

If you followed the previous instructions and installed BLC via a symbolic link, BLC will always be loaded from your local git repository source at Blender startup.

if you make changes to BLC and want to reload the addon, you can use Blenders internal function "Reload Scripts".
Nota: This feature is WIP for BLC and may not yet be functional for all of its submodules.

Scenario #2: Working on pyluxcore

To use a custom wheel of pyluxcore, open the addon preferences of BLH. Set the option Wheel Source to Local Wheel. You can then enter a Path to Wheel file, which must point to the wheel itself, not the folder where it is located!

At each startup (or reload), BLC computes a hash of the linked wheel. This hash is compared against information stored in a local file, 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, and update accordingly if you change the selection of Wheel Source.

As a verification, check for the following lines in the console output of Blender at startup:
[BLC] Installing local version of pyluxcore [...] --> A local version will be used.
[BLC] installing pyluxcore version: [...] --> pyluxcore will be installed from PyPi. Replaces any previous installation.
[BLC] skipping pyluxcore installation. [...] --> BLC detected that the installed wheel matches the designated wheel, and installation is skipped.

(Note: Further error messages exist but they are out of the scope of this article.)

Scenario #3: Offline installation

When you need to perform an offline installation, you first need to download the dependencies of pyluxcore as wheel-files.
If you are unsure about the correct modules and versions, or where to get them, please ask on the support channels (Forum, Discord, ...).

In the BLH addon preferences, first configure to use a Local Wheel as described in the previous section.

Then, use the additional option Path to additional dependency folder (optional) to specify the path where the dependencies are located.
In this field enter a folder path that contains all the dependency wheels that you previously downloaded. (Not a wheel directly, as required in the previous section.)

At the next startup, Blender will install the local wheel including the local dependencies.

Tips & Tricks

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

THIS SECTION NEEDS AN UPDATE

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