CodeHD: Add note about deprecation

2025-10-07T17:53:05Z

Add note about deprecation

← Older revision		Revision as of 19:53, 7 October 2025
Line 1:		Line 1:

			<b>Note: This page is documenting the development process used in v2.10.x of BlendLuxCore. The content is no longer under active development. See the main article [[Developing and debugging BlendLuxCore]] for the latest instructions.</b>

	= Introduction =		= Introduction =

CodeHD: Created page with "= 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 eng..."

2025-10-07T17:45:53Z

Created page with "= 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 eng..."

New page

= 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 [https://github.com/LuxCoreRender/BlendLuxCore BlendLuxCore] repository.
* Underlying pyluxcore library, compiled from the [https://github.com/LuxCoreRender/LuxCore 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:
* <code>BLC_DEV_PATH</code>: path _folder containing_ the development repo of BlendLuxCore

For the second goal, two methods are available:
* Another environment variable, <code>BLC_WHEEL_PATH</code>: path to a development version of the wheel
* A subfolder <code>pyluxcore_custom/</code> 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:
<pre>
cmake -S . -B out -DCMAKE_BUILD_TYPE=Release
cmake --build out
</pre>

You know how to build a test wheel from LuxCore:
<pre>
make wheel-test
</pre>

= Scenario #1: Working on BLC, using standard pyluxcore =

The first goal can be achieved via an environment variable:
* <code>BLC_DEV_PATH</code>: 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 <code>BLC_DEV_PATH</code> to the path of your dev repository:
<pre>export BLC_DEV_PATH=/path/to/folder/containing/BlendLuxCore</pre>
For clarification, set this folder like you would set the systems <code>PATH</code> or <code>PYTHONPATH</code> variable, i.e. so that Python can <code>import BlendLuxCore</code> from this location!

When this variable is set, all Python code from the development repo will be loaded, except the main <code>__init__.py</code> 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: 
<code>[BLC] USING LOCAL DEV VERSION OF BlendLuxCore</code>

= Scenario #2: Working on pyluxcore =

For the second goal, two methods are available:
* Another environment variable, <code>BLC_WHEEL_PATH</code>: path to a development version of the wheel
* A subfolder <code>pyluxcore_custom/</code> 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 <code>pyluxcore_custom/</code> will take precedence over the <code>BLC_WHEEL_PATH</code> variable!
To simplify further explanations, all explanations are presented in terms of the <code>BLC_WHEEL_PATH</code> variable.

When this variable is set, BLC computes a hash of the linked wheel. This hash is compared against information stored in the file <code>pyluxcore_installation_info.txt</code>, 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: 
<code>[BLC] Installing local version of pyluxcore</code> --> A new local version will be installed. Replaces any previous installation. 
<code>[BLC] skipping pyluxcore installation. Custom wheel matching hash already installed.</code> --> A local version was previously installed and is used again. 
<code>[BLC] installing pyluxcore version:</code> --> pyluxcore will be installed from PyPi. Replaces any previous installation. 
<code>[BLC] skipping pyluxcore installation. Specified version already installed.</code> --> 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: 
<code>$HOME/.config/blender/<blender-version>/extensions/user_default</code>

The wheel is installed in: 
<code>$HOME/.config/blender/<blender version>/extensions/.local/lib/python<python-version>/site-packages</code>

== Utility shell script for launching Blender ==

The BlendLuxCore repository contains a shell script, called <code>blendev</code> (short for blender-development), located inside the <code>debug-helpers</code> 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 <code>Readme.md</code> supplied alongside the script, and its internal help output <code>blendev -h</code> 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 <code>pyenv</code> to set the right interpreter in your build session. Be careful to clear and reconfigure the whole project, afterwards: <pre>make clear && make deps</pre>

Once rebuilt, please check the version of pyluxcore in the build log:
<code>LuxCore/out/install/Debug/pyluxcore/pyluxcore.cpython-<version>-x86_64-linux-gnu.so</code>

<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 (<code>pip uninstall pyluxcore</code>) 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: <code>$HOME/.config/blender/4.2/extensions/.user/user_default/BlendLuxCore/pyluxcore_installation_info.txt</code>

== 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:
<pre>export LUX_BUILD_TYPE=Debug
make wheel-test</pre>

* Run Blender with gdb
<pre>gdb --args blender</pre>

(nota bene: check that the latest wheel is correctly installed by BlendLuxCore)

gdb should allow you to debug any call to LuxCore

Developing and debugging BlendLuxCore v2.10 - Revision history

CodeHD: Add note about deprecation