LuxCoreRender Wiki - User contributions [en]

Building LuxCoreRender - FAQ

2026-07-24T17:24:02Z

Howetuft: /* Can I contribute with AI-generated content? */

== Is it possible to set-up a local-only, end-to-end, build chain? ==

Yes it is, but for Linux only, at the moment, and starting with v2.11.
Also, important caveat: this kind of build is solely intended for development and tests. Do not use in production.

Here are the steps to do so:
# Build dependencies locally: Use [[Building_LuxCoreRender#Local_Plain_Build|local plain build]] or [[Building_LuxCoreRender#Local_Continuous_Integration | local CI build]] of LuxCoreDeps
# Inject local dependencies in LuxCore build: <pre>python -m build-system.luxmake.deps --local <path/to/deps> --release test</pre>
# Build a testing wheel: <pre>make wheel-test</pre>
# Inject testing wheel in Blender: Use [[Developing_and_debugging_BlendLuxCore | BlendLuxHelper]]

Comments for step#2:
* You may want to get a clean situation before injecting local deps: <code>make clear</code>
* On Linux, <path/to/depth> should likely be <code>/tmp/conan-cache/luxcoredeps.zip</code> (plain) or <code>/tmp/luxcoredeps/artifact/1/luxcore-deps-ubuntu-latest/luxcore-deps-ubuntu-latest.zip</code> (CI).
* Be careful about build type.If the build type of the deps is <code>Debug</code> and the build type of <code>pyluxcore</code> is <code>Release</code>, or vice-versa, then the build system will recompile all dependencies.
* Release build is faster than Debug build so, if you are just testing compilation, we would recommend you to use Release.

Comments for #3 & #4
For a debugging with luxcoreui only, one can also replace steps #3 & #4 by:
* Step#3bis: Build luxcoreui: <pre>make luxcoreui</pre>

A good practice we recommend:
* Secure plain local build
** Ensure you can build LuxCoreDeps with plain local build
** Ensure you can build and run LuxCore with your local plain built package.
* Secure CI local build
** Ensure you can build LuxCoreDeps with CI local build
** Ensure you can build and run LuxCore with your CI local built package.
* Secure CI server build - private repo
** Commit your work above
** Push your work to one of your repos (not LuxCore, at this stage). This should trigger CI: ensure build is ok.
** Build LuxCore against it (set LuxCore settings beforehands)
* Secure CI server build - main repo
** Merge your work and check CI
** Try compiling LuxCore

== Can I use <code>git bisect</code>? ==

Yes, if you need to find a faulty commit in <code>LuxCore</code>, you can use <code>git bisect</code>.

In that case, please note the correct verb to build LuxCoreRender at each step is
<pre>make clear && make deps && make</pre>

Caveat: this method only works for version >= v2.10.0

Example for Linux (please adapt to other contexts):

<pre>
# For bisecting, we recommend to build in Release type (shorter build time)
export LUX_BUILD_TYPE=Release

# Start git bisecting
git bisect start

# Define bounds
git bisect good samples-v2.10.0 # For instance
git bisect bad HEAD

# Build the app, test it and report status to git bisect
make clear && make deps && make # Build at this stage
./out/install/Release/bin/luxcoreui mytestscene/render.cfg
git bisect <good|bad|skip> # Depending on above test...

# Bisection loop
...

# At a certain point, the bisection stops and points at the faulty commit
# You can reset bisection
git bisect reset
</pre>

== Can I generate debug information for dependencies (LuxCoreDeps)? ==
Yes, it's possible, but only for local build.

In this context, the build type is controlled by <code>DEPS_BUILD_TYPE</code> environment variable, so set it to your target build type before building:

<pre>export DEPS_BUILD_TYPE=Debug</pre>

Then you will build the deps with [[Building_LuxCoreRender#Local_Plain_Build|local plain build]].

After having built dependencies in local, you may want to inject them in LuxCore build. This can be done with the following:

<pre>python -m build-system.luxmake.deps --local <path/to/deps> --release test --build-type=Debug</pre>

(this replaces <code>make deps</code>)

At this stage, you will be able to build LuxCore artifacts, embedding the debug information of dependencies, for instance:
<pre>
export LUX_BUILD_TYPE=Debug
make wheel-test # If the previous steps have been completed, the testing wheel will contain deps' debug info
</pre>

Remark: in this scenario, do not build the dependencies with CI local build, as the deps source files should be inaccessible at the end of the build, what should make the deps debug info useless.

== How can I build a sanitized version of LuxCore? ==

It is possible to build a sanitized version of LuxCore, including <code>luxcoreui</code>, <code>luxcoreconsole</code>, <code>pyluxcore</code> and the wheels.
It just consists in setting the environment variable <code>LUX_SANITIZE</code> before the build:

<pre>export LUX_SANITIZE=1 # or whatever value you want</pre>

To come back to unsanitized build, just <code>unset LUX_SANITIZE</code>.

2 caveats:
* You'll need to export the following before running LuxCore:
<pre>export ASAN_OPTIONS=protect_shadow_gap=0</pre>
otherwise LuxCore will stop early with the following error message:
<pre>terminate called after throwing an instance of 'std::runtime_error'
what(): CUDA driver API error CUDA_ERROR_NOT_INITIALIZED
</pre>
* To run Blender with ASAN, see here: https://developer.blender.org/docs/handbook/tooling/asan/
This may help:
<pre>export ASAN_OPTIONS=check_initialization_order=0:protect_shadow_gap=0:verify_asan_link_order=0</pre>

== In Linux, I try to set an environment variable that should control LuxCore build, but it does not work ==

In Linux, for LuxCore build system to take them into account, the environment variables that control the build (LUX_BUILD_TYPE, LUX_SANITIZE...) should not only be set, but also exported:

<pre>export LUX_BUILD_TYPE=Debug # `set LUX_BUILD_TYPE=Debug` would be insufficient</pre>

== In gdb, how to debug one thread at a time? ==
<pre>set scheduler-locking step</pre>

== Can I contribute with AI-generated content? ==
Yes, you can - we aim at being a modern project!

However, you must follow a few rules:
* Proposed commits from AI must be short, ideally less than a dozen of lines and at any rate not above 20 lines.
* AI usage must be clearly mentionned in the commits messages
* You must have a complete understanding of what you propose and be able to explain every detail of the implementation. You must demonstrate a good command of the languages (C++, Python, bash etc.) used by the code and of the solutions the AI used. In short, do not propose a code you cannot explain. Please keep in mind that each PR (AI or not) is reviewed and questionned, so lack of understanding from the submitter will be detected soon and will decrease significantly the chances for the PR to be accepted.
* Your proposal must stay focused on the issue you want to fix or the feature you want to implement. Simultaneous linting, reformating etc. is not allowed.
* Proposed code must comply with LuxCore license. This is your responsability to ensure that.
* You're expected to have a good command of <code>git</code> (not limited to AI-generated contributions, by the way)

Building LuxCoreRender - FAQ

2026-07-24T17:22:25Z

Howetuft: /* Can I contribute with AI-generated content? */

Building LuxCoreRender - FAQ

2026-07-24T17:21:47Z

Howetuft: /* Can I contribute with AI-generated content? */

== Is it possible to set-up a local-only, end-to-end, build chain? ==

Yes it is, but for Linux only, at the moment, and starting with v2.11.
Also, important caveat: this kind of build is solely intended for development and tests. Do not use in production.

Here are the steps to do so:
# Build dependencies locally: Use [[Building_LuxCoreRender#Local_Plain_Build|local plain build]] or [[Building_LuxCoreRender#Local_Continuous_Integration | local CI build]] of LuxCoreDeps
# Inject local dependencies in LuxCore build: <pre>python -m build-system.luxmake.deps --local <path/to/deps> --release test</pre>
# Build a testing wheel: <pre>make wheel-test</pre>
# Inject testing wheel in Blender: Use [[Developing_and_debugging_BlendLuxCore | BlendLuxHelper]]

Comments for step#2:
* You may want to get a clean situation before injecting local deps: <code>make clear</code>
* On Linux, <path/to/depth> should likely be <code>/tmp/conan-cache/luxcoredeps.zip</code> (plain) or <code>/tmp/luxcoredeps/artifact/1/luxcore-deps-ubuntu-latest/luxcore-deps-ubuntu-latest.zip</code> (CI).
* Be careful about build type.If the build type of the deps is <code>Debug</code> and the build type of <code>pyluxcore</code> is <code>Release</code>, or vice-versa, then the build system will recompile all dependencies.
* Release build is faster than Debug build so, if you are just testing compilation, we would recommend you to use Release.

Comments for #3 & #4
For a debugging with luxcoreui only, one can also replace steps #3 & #4 by:
* Step#3bis: Build luxcoreui: <pre>make luxcoreui</pre>

A good practice we recommend:
* Secure plain local build
** Ensure you can build LuxCoreDeps with plain local build
** Ensure you can build and run LuxCore with your local plain built package.
* Secure CI local build
** Ensure you can build LuxCoreDeps with CI local build
** Ensure you can build and run LuxCore with your CI local built package.
* Secure CI server build - private repo
** Commit your work above
** Push your work to one of your repos (not LuxCore, at this stage). This should trigger CI: ensure build is ok.
** Build LuxCore against it (set LuxCore settings beforehands)
* Secure CI server build - main repo
** Merge your work and check CI
** Try compiling LuxCore

== Can I use <code>git bisect</code>? ==

Yes, if you need to find a faulty commit in <code>LuxCore</code>, you can use <code>git bisect</code>.

In that case, please note the correct verb to build LuxCoreRender at each step is
<pre>make clear && make deps && make</pre>

Caveat: this method only works for version >= v2.10.0

Example for Linux (please adapt to other contexts):

<pre>
# For bisecting, we recommend to build in Release type (shorter build time)
export LUX_BUILD_TYPE=Release

# Start git bisecting
git bisect start

# Define bounds
git bisect good samples-v2.10.0 # For instance
git bisect bad HEAD

# Build the app, test it and report status to git bisect
make clear && make deps && make # Build at this stage
./out/install/Release/bin/luxcoreui mytestscene/render.cfg
git bisect <good|bad|skip> # Depending on above test...

# Bisection loop
...

# At a certain point, the bisection stops and points at the faulty commit
# You can reset bisection
git bisect reset
</pre>

== Can I generate debug information for dependencies (LuxCoreDeps)? ==
Yes, it's possible, but only for local build.

In this context, the build type is controlled by <code>DEPS_BUILD_TYPE</code> environment variable, so set it to your target build type before building:

<pre>export DEPS_BUILD_TYPE=Debug</pre>

Then you will build the deps with [[Building_LuxCoreRender#Local_Plain_Build|local plain build]].

After having built dependencies in local, you may want to inject them in LuxCore build. This can be done with the following:

<pre>python -m build-system.luxmake.deps --local <path/to/deps> --release test --build-type=Debug</pre>

(this replaces <code>make deps</code>)

At this stage, you will be able to build LuxCore artifacts, embedding the debug information of dependencies, for instance:
<pre>
export LUX_BUILD_TYPE=Debug
make wheel-test # If the previous steps have been completed, the testing wheel will contain deps' debug info
</pre>

Remark: in this scenario, do not build the dependencies with CI local build, as the deps source files should be inaccessible at the end of the build, what should make the deps debug info useless.

== How can I build a sanitized version of LuxCore? ==

It is possible to build a sanitized version of LuxCore, including <code>luxcoreui</code>, <code>luxcoreconsole</code>, <code>pyluxcore</code> and the wheels.
It just consists in setting the environment variable <code>LUX_SANITIZE</code> before the build:

<pre>export LUX_SANITIZE=1 # or whatever value you want</pre>

To come back to unsanitized build, just <code>unset LUX_SANITIZE</code>.

2 caveats:
* You'll need to export the following before running LuxCore:
<pre>export ASAN_OPTIONS=protect_shadow_gap=0</pre>
otherwise LuxCore will stop early with the following error message:
<pre>terminate called after throwing an instance of 'std::runtime_error'
what(): CUDA driver API error CUDA_ERROR_NOT_INITIALIZED
</pre>
* To run Blender with ASAN, see here: https://developer.blender.org/docs/handbook/tooling/asan/
This may help:
<pre>export ASAN_OPTIONS=check_initialization_order=0:protect_shadow_gap=0:verify_asan_link_order=0</pre>

== In Linux, I try to set an environment variable that should control LuxCore build, but it does not work ==

In Linux, for LuxCore build system to take them into account, the environment variables that control the build (LUX_BUILD_TYPE, LUX_SANITIZE...) should not only be set, but also exported:

<pre>export LUX_BUILD_TYPE=Debug # `set LUX_BUILD_TYPE=Debug` would be insufficient</pre>

== In gdb, how to debug one thread at a time? ==
<pre>set scheduler-locking step</pre>

== Can I contribute with AI-generated content? ==
Yes, you can - we aim at being a modern project!

However, you must follow a few rules:
* Proposed commits from AI must be short, ideally less than a dozen of lines and at any rate not above 20 lines.
* AI usage must be clearly mentionned in the commits messages
* You must have a complete understanding of what you propose and be able to explain every detail of the implementation. You must demonstrate a good command of the languages (C++, Python, bash etc.) used by the code and of the solutions the AI generated. In short, do not propose a code you cannot explain. Please keep in mind that each PR (AI or not) is reviewed and questionned, so lack of understanding from the submitter will be detected soon and will decrease significantly the chances for the PR to be accepted.
* Your proposal must stay focused on the issue you want to fix or the feature you want to implement. Simultaneous linting, reformating etc. is not allowed.
* Proposed code must comply with LuxCore license. This is your responsability to ensure that.
* You're expected to have a good command of <code>git</code>

Building LuxCoreRender - FAQ

2026-07-24T17:21:27Z

Howetuft: /* Can I contribute with AI-generated content? */

== Is it possible to set-up a local-only, end-to-end, build chain? ==

Yes it is, but for Linux only, at the moment, and starting with v2.11.
Also, important caveat: this kind of build is solely intended for development and tests. Do not use in production.

Here are the steps to do so:
# Build dependencies locally: Use [[Building_LuxCoreRender#Local_Plain_Build|local plain build]] or [[Building_LuxCoreRender#Local_Continuous_Integration | local CI build]] of LuxCoreDeps
# Inject local dependencies in LuxCore build: <pre>python -m build-system.luxmake.deps --local <path/to/deps> --release test</pre>
# Build a testing wheel: <pre>make wheel-test</pre>
# Inject testing wheel in Blender: Use [[Developing_and_debugging_BlendLuxCore | BlendLuxHelper]]

Comments for step#2:
* You may want to get a clean situation before injecting local deps: <code>make clear</code>
* On Linux, <path/to/depth> should likely be <code>/tmp/conan-cache/luxcoredeps.zip</code> (plain) or <code>/tmp/luxcoredeps/artifact/1/luxcore-deps-ubuntu-latest/luxcore-deps-ubuntu-latest.zip</code> (CI).
* Be careful about build type.If the build type of the deps is <code>Debug</code> and the build type of <code>pyluxcore</code> is <code>Release</code>, or vice-versa, then the build system will recompile all dependencies.
* Release build is faster than Debug build so, if you are just testing compilation, we would recommend you to use Release.

Comments for #3 & #4
For a debugging with luxcoreui only, one can also replace steps #3 & #4 by:
* Step#3bis: Build luxcoreui: <pre>make luxcoreui</pre>

A good practice we recommend:
* Secure plain local build
** Ensure you can build LuxCoreDeps with plain local build
** Ensure you can build and run LuxCore with your local plain built package.
* Secure CI local build
** Ensure you can build LuxCoreDeps with CI local build
** Ensure you can build and run LuxCore with your CI local built package.
* Secure CI server build - private repo
** Commit your work above
** Push your work to one of your repos (not LuxCore, at this stage). This should trigger CI: ensure build is ok.
** Build LuxCore against it (set LuxCore settings beforehands)
* Secure CI server build - main repo
** Merge your work and check CI
** Try compiling LuxCore

== Can I use <code>git bisect</code>? ==

Yes, if you need to find a faulty commit in <code>LuxCore</code>, you can use <code>git bisect</code>.

In that case, please note the correct verb to build LuxCoreRender at each step is
<pre>make clear && make deps && make</pre>

Caveat: this method only works for version >= v2.10.0

Example for Linux (please adapt to other contexts):

<pre>
# For bisecting, we recommend to build in Release type (shorter build time)
export LUX_BUILD_TYPE=Release

# Start git bisecting
git bisect start

# Define bounds
git bisect good samples-v2.10.0 # For instance
git bisect bad HEAD

# Build the app, test it and report status to git bisect
make clear && make deps && make # Build at this stage
./out/install/Release/bin/luxcoreui mytestscene/render.cfg
git bisect <good|bad|skip> # Depending on above test...

# Bisection loop
...

# At a certain point, the bisection stops and points at the faulty commit
# You can reset bisection
git bisect reset
</pre>

== Can I generate debug information for dependencies (LuxCoreDeps)? ==
Yes, it's possible, but only for local build.

In this context, the build type is controlled by <code>DEPS_BUILD_TYPE</code> environment variable, so set it to your target build type before building:

<pre>export DEPS_BUILD_TYPE=Debug</pre>

Then you will build the deps with [[Building_LuxCoreRender#Local_Plain_Build|local plain build]].

After having built dependencies in local, you may want to inject them in LuxCore build. This can be done with the following:

<pre>python -m build-system.luxmake.deps --local <path/to/deps> --release test --build-type=Debug</pre>

(this replaces <code>make deps</code>)

At this stage, you will be able to build LuxCore artifacts, embedding the debug information of dependencies, for instance:
<pre>
export LUX_BUILD_TYPE=Debug
make wheel-test # If the previous steps have been completed, the testing wheel will contain deps' debug info
</pre>

Remark: in this scenario, do not build the dependencies with CI local build, as the deps source files should be inaccessible at the end of the build, what should make the deps debug info useless.

== How can I build a sanitized version of LuxCore? ==

It is possible to build a sanitized version of LuxCore, including <code>luxcoreui</code>, <code>luxcoreconsole</code>, <code>pyluxcore</code> and the wheels.
It just consists in setting the environment variable <code>LUX_SANITIZE</code> before the build:

<pre>export LUX_SANITIZE=1 # or whatever value you want</pre>

To come back to unsanitized build, just <code>unset LUX_SANITIZE</code>.

2 caveats:
* You'll need to export the following before running LuxCore:
<pre>export ASAN_OPTIONS=protect_shadow_gap=0</pre>
otherwise LuxCore will stop early with the following error message:
<pre>terminate called after throwing an instance of 'std::runtime_error'
what(): CUDA driver API error CUDA_ERROR_NOT_INITIALIZED
</pre>
* To run Blender with ASAN, see here: https://developer.blender.org/docs/handbook/tooling/asan/
This may help:
<pre>export ASAN_OPTIONS=check_initialization_order=0:protect_shadow_gap=0:verify_asan_link_order=0</pre>

== In Linux, I try to set an environment variable that should control LuxCore build, but it does not work ==

In Linux, for LuxCore build system to take them into account, the environment variables that control the build (LUX_BUILD_TYPE, LUX_SANITIZE...) should not only be set, but also exported:

<pre>export LUX_BUILD_TYPE=Debug # `set LUX_BUILD_TYPE=Debug` would be insufficient</pre>

== In gdb, how to debug one thread at a time? ==
<pre>set scheduler-locking step</pre>

== Can I contribute with AI-generated content? ==
Yes, you can - we aim at being a modern project!

However, you must follow a few rules:
* Proposed commits from AI must be short, ideally less than a dozen of lines and at any rate not above 20 lines.
* AI usage must be clearly mentionned in the commits messages
* You must have a complete understanding of what you propose and be able to explain every detail of the implementation. You must demonstrate a good command of the languages (C++, Python, bash etc.) used by the code and of the solutions the AI generated. In short, do not propose a code you cannot explain. Please keep in mind that each PR (AI or not) is reviewed and questionned, so lack of understanding from the submitter will be detected soon and will decrease significantly the chance for the PR to be accepted.
* Your proposal must stay focused on the issue you want to fix or the feature you want to implement. Simultaneous linting, reformating etc. is not allowed.
* Proposed code must comply with LuxCore license. This is your responsability to ensure that.
* You're expected to have a good command of <code>git</code>

Building LuxCoreRender - FAQ

2026-07-24T17:20:53Z

Howetuft: /* Can I contribute with AI-generated content? */

== Is it possible to set-up a local-only, end-to-end, build chain? ==

Yes it is, but for Linux only, at the moment, and starting with v2.11.
Also, important caveat: this kind of build is solely intended for development and tests. Do not use in production.

Here are the steps to do so:
# Build dependencies locally: Use [[Building_LuxCoreRender#Local_Plain_Build|local plain build]] or [[Building_LuxCoreRender#Local_Continuous_Integration | local CI build]] of LuxCoreDeps
# Inject local dependencies in LuxCore build: <pre>python -m build-system.luxmake.deps --local <path/to/deps> --release test</pre>
# Build a testing wheel: <pre>make wheel-test</pre>
# Inject testing wheel in Blender: Use [[Developing_and_debugging_BlendLuxCore | BlendLuxHelper]]

Comments for step#2:
* You may want to get a clean situation before injecting local deps: <code>make clear</code>
* On Linux, <path/to/depth> should likely be <code>/tmp/conan-cache/luxcoredeps.zip</code> (plain) or <code>/tmp/luxcoredeps/artifact/1/luxcore-deps-ubuntu-latest/luxcore-deps-ubuntu-latest.zip</code> (CI).
* Be careful about build type.If the build type of the deps is <code>Debug</code> and the build type of <code>pyluxcore</code> is <code>Release</code>, or vice-versa, then the build system will recompile all dependencies.
* Release build is faster than Debug build so, if you are just testing compilation, we would recommend you to use Release.

Comments for #3 & #4
For a debugging with luxcoreui only, one can also replace steps #3 & #4 by:
* Step#3bis: Build luxcoreui: <pre>make luxcoreui</pre>

A good practice we recommend:
* Secure plain local build
** Ensure you can build LuxCoreDeps with plain local build
** Ensure you can build and run LuxCore with your local plain built package.
* Secure CI local build
** Ensure you can build LuxCoreDeps with CI local build
** Ensure you can build and run LuxCore with your CI local built package.
* Secure CI server build - private repo
** Commit your work above
** Push your work to one of your repos (not LuxCore, at this stage). This should trigger CI: ensure build is ok.
** Build LuxCore against it (set LuxCore settings beforehands)
* Secure CI server build - main repo
** Merge your work and check CI
** Try compiling LuxCore

== Can I use <code>git bisect</code>? ==

Yes, if you need to find a faulty commit in <code>LuxCore</code>, you can use <code>git bisect</code>.

In that case, please note the correct verb to build LuxCoreRender at each step is
<pre>make clear && make deps && make</pre>

Caveat: this method only works for version >= v2.10.0

Example for Linux (please adapt to other contexts):

<pre>
# For bisecting, we recommend to build in Release type (shorter build time)
export LUX_BUILD_TYPE=Release

# Start git bisecting
git bisect start

# Define bounds
git bisect good samples-v2.10.0 # For instance
git bisect bad HEAD

# Build the app, test it and report status to git bisect
make clear && make deps && make # Build at this stage
./out/install/Release/bin/luxcoreui mytestscene/render.cfg
git bisect <good|bad|skip> # Depending on above test...

# Bisection loop
...

# At a certain point, the bisection stops and points at the faulty commit
# You can reset bisection
git bisect reset
</pre>

== Can I generate debug information for dependencies (LuxCoreDeps)? ==
Yes, it's possible, but only for local build.

In this context, the build type is controlled by <code>DEPS_BUILD_TYPE</code> environment variable, so set it to your target build type before building:

<pre>export DEPS_BUILD_TYPE=Debug</pre>

Then you will build the deps with [[Building_LuxCoreRender#Local_Plain_Build|local plain build]].

After having built dependencies in local, you may want to inject them in LuxCore build. This can be done with the following:

<pre>python -m build-system.luxmake.deps --local <path/to/deps> --release test --build-type=Debug</pre>

(this replaces <code>make deps</code>)

At this stage, you will be able to build LuxCore artifacts, embedding the debug information of dependencies, for instance:
<pre>
export LUX_BUILD_TYPE=Debug
make wheel-test # If the previous steps have been completed, the testing wheel will contain deps' debug info
</pre>

Remark: in this scenario, do not build the dependencies with CI local build, as the deps source files should be inaccessible at the end of the build, what should make the deps debug info useless.

== How can I build a sanitized version of LuxCore? ==

It is possible to build a sanitized version of LuxCore, including <code>luxcoreui</code>, <code>luxcoreconsole</code>, <code>pyluxcore</code> and the wheels.
It just consists in setting the environment variable <code>LUX_SANITIZE</code> before the build:

<pre>export LUX_SANITIZE=1 # or whatever value you want</pre>

To come back to unsanitized build, just <code>unset LUX_SANITIZE</code>.

2 caveats:
* You'll need to export the following before running LuxCore:
<pre>export ASAN_OPTIONS=protect_shadow_gap=0</pre>
otherwise LuxCore will stop early with the following error message:
<pre>terminate called after throwing an instance of 'std::runtime_error'
what(): CUDA driver API error CUDA_ERROR_NOT_INITIALIZED
</pre>
* To run Blender with ASAN, see here: https://developer.blender.org/docs/handbook/tooling/asan/
This may help:
<pre>export ASAN_OPTIONS=check_initialization_order=0:protect_shadow_gap=0:verify_asan_link_order=0</pre>

== In Linux, I try to set an environment variable that should control LuxCore build, but it does not work ==

In Linux, for LuxCore build system to take them into account, the environment variables that control the build (LUX_BUILD_TYPE, LUX_SANITIZE...) should not only be set, but also exported:

<pre>export LUX_BUILD_TYPE=Debug # `set LUX_BUILD_TYPE=Debug` would be insufficient</pre>

== In gdb, how to debug one thread at a time? ==
<pre>set scheduler-locking step</pre>

== Can I contribute with AI-generated content? ==
Yes, you can - we aim at being a modern project!

However, you must follow a few rules:
* Proposed commits from AI must be short, ideally less than a dozen of lines and at any rate not above 20 lines.
* AI usage must be clearly mentionned in the commits messages
* You must have a complete understanding of what you propose and be able to explain every detail of the implementation. You must demonstrate a good command of the languages (C++, Python, bash etc.) used by the code and of the solutions the AI generated. In short, do not propose a code you cannot explain. Please keep in mind that each PR (AI or not) is reviewed and questionned, so lack of understanding from the submitter will be detected soon and decrease significantly the chance for the PR to be accepted.
* Your proposal must stay focused on the issue you want to fix or the feature you want to implement. Simultaneous linting, reformating etc. is not allowed.
* Proposed code must comply with LuxCore license. This is your responsability to ensure that.
* You're expected to have a good command of <code>git</code>

Building LuxCoreRender - FAQ

2026-07-24T17:20:26Z

Howetuft: /* Can I contribute with AI-generated content? */

== Is it possible to set-up a local-only, end-to-end, build chain? ==

Yes it is, but for Linux only, at the moment, and starting with v2.11.
Also, important caveat: this kind of build is solely intended for development and tests. Do not use in production.

Here are the steps to do so:
# Build dependencies locally: Use [[Building_LuxCoreRender#Local_Plain_Build|local plain build]] or [[Building_LuxCoreRender#Local_Continuous_Integration | local CI build]] of LuxCoreDeps
# Inject local dependencies in LuxCore build: <pre>python -m build-system.luxmake.deps --local <path/to/deps> --release test</pre>
# Build a testing wheel: <pre>make wheel-test</pre>
# Inject testing wheel in Blender: Use [[Developing_and_debugging_BlendLuxCore | BlendLuxHelper]]

Comments for step#2:
* You may want to get a clean situation before injecting local deps: <code>make clear</code>
* On Linux, <path/to/depth> should likely be <code>/tmp/conan-cache/luxcoredeps.zip</code> (plain) or <code>/tmp/luxcoredeps/artifact/1/luxcore-deps-ubuntu-latest/luxcore-deps-ubuntu-latest.zip</code> (CI).
* Be careful about build type.If the build type of the deps is <code>Debug</code> and the build type of <code>pyluxcore</code> is <code>Release</code>, or vice-versa, then the build system will recompile all dependencies.
* Release build is faster than Debug build so, if you are just testing compilation, we would recommend you to use Release.

Comments for #3 & #4
For a debugging with luxcoreui only, one can also replace steps #3 & #4 by:
* Step#3bis: Build luxcoreui: <pre>make luxcoreui</pre>

A good practice we recommend:
* Secure plain local build
** Ensure you can build LuxCoreDeps with plain local build
** Ensure you can build and run LuxCore with your local plain built package.
* Secure CI local build
** Ensure you can build LuxCoreDeps with CI local build
** Ensure you can build and run LuxCore with your CI local built package.
* Secure CI server build - private repo
** Commit your work above
** Push your work to one of your repos (not LuxCore, at this stage). This should trigger CI: ensure build is ok.
** Build LuxCore against it (set LuxCore settings beforehands)
* Secure CI server build - main repo
** Merge your work and check CI
** Try compiling LuxCore

== Can I use <code>git bisect</code>? ==

Yes, if you need to find a faulty commit in <code>LuxCore</code>, you can use <code>git bisect</code>.

In that case, please note the correct verb to build LuxCoreRender at each step is
<pre>make clear && make deps && make</pre>

Caveat: this method only works for version >= v2.10.0

Example for Linux (please adapt to other contexts):

<pre>
# For bisecting, we recommend to build in Release type (shorter build time)
export LUX_BUILD_TYPE=Release

# Start git bisecting
git bisect start

# Define bounds
git bisect good samples-v2.10.0 # For instance
git bisect bad HEAD

# Build the app, test it and report status to git bisect
make clear && make deps && make # Build at this stage
./out/install/Release/bin/luxcoreui mytestscene/render.cfg
git bisect <good|bad|skip> # Depending on above test...

# Bisection loop
...

# At a certain point, the bisection stops and points at the faulty commit
# You can reset bisection
git bisect reset
</pre>

== Can I generate debug information for dependencies (LuxCoreDeps)? ==
Yes, it's possible, but only for local build.

In this context, the build type is controlled by <code>DEPS_BUILD_TYPE</code> environment variable, so set it to your target build type before building:

<pre>export DEPS_BUILD_TYPE=Debug</pre>

Then you will build the deps with [[Building_LuxCoreRender#Local_Plain_Build|local plain build]].

After having built dependencies in local, you may want to inject them in LuxCore build. This can be done with the following:

<pre>python -m build-system.luxmake.deps --local <path/to/deps> --release test --build-type=Debug</pre>

(this replaces <code>make deps</code>)

At this stage, you will be able to build LuxCore artifacts, embedding the debug information of dependencies, for instance:
<pre>
export LUX_BUILD_TYPE=Debug
make wheel-test # If the previous steps have been completed, the testing wheel will contain deps' debug info
</pre>

Remark: in this scenario, do not build the dependencies with CI local build, as the deps source files should be inaccessible at the end of the build, what should make the deps debug info useless.

== How can I build a sanitized version of LuxCore? ==

It is possible to build a sanitized version of LuxCore, including <code>luxcoreui</code>, <code>luxcoreconsole</code>, <code>pyluxcore</code> and the wheels.
It just consists in setting the environment variable <code>LUX_SANITIZE</code> before the build:

<pre>export LUX_SANITIZE=1 # or whatever value you want</pre>

To come back to unsanitized build, just <code>unset LUX_SANITIZE</code>.

2 caveats:
* You'll need to export the following before running LuxCore:
<pre>export ASAN_OPTIONS=protect_shadow_gap=0</pre>
otherwise LuxCore will stop early with the following error message:
<pre>terminate called after throwing an instance of 'std::runtime_error'
what(): CUDA driver API error CUDA_ERROR_NOT_INITIALIZED
</pre>
* To run Blender with ASAN, see here: https://developer.blender.org/docs/handbook/tooling/asan/
This may help:
<pre>export ASAN_OPTIONS=check_initialization_order=0:protect_shadow_gap=0:verify_asan_link_order=0</pre>

== In Linux, I try to set an environment variable that should control LuxCore build, but it does not work ==

In Linux, for LuxCore build system to take them into account, the environment variables that control the build (LUX_BUILD_TYPE, LUX_SANITIZE...) should not only be set, but also exported:

<pre>export LUX_BUILD_TYPE=Debug # `set LUX_BUILD_TYPE=Debug` would be insufficient</pre>

== In gdb, how to debug one thread at a time? ==
<pre>set scheduler-locking step</pre>

== Can I contribute with AI-generated content? ==
Yes, you can - we aim at being a modern project!

However, you must follow a few rules:
* Proposed commits from AI must be short, ideally less than a dozen of lines and at any rate not above 20 lines.
* AI usage must be clearly mentionned in the commits messages
* You must have a complete understanding of what you propose and be able to explain every detail of the implementation. You must demonstrate a good command of the languages (C++, Python, bash etc.) used by the code and of the solutions the AI generated. In short, **do not propose a code you cannot explain**. Please keep in mind that each PR (AI or not) is reviewed and questionned, so lack of understanding from the submitter will be detected soon and decrease significantly the chance for the PR to be accepted.
* Your proposal must stay focused on the issue you want to fix or the feature you want to implement. Simultaneous linting, reformating etc. is not allowed.
* Proposed code must comply with LuxCore license. This is your responsability to ensure that.
* You're expected to have a good command of <code>git</code>

Building LuxCoreRender - FAQ

2026-07-24T17:10:44Z

Howetuft: /* Can I contribute with AI-generated content? */

== Is it possible to set-up a local-only, end-to-end, build chain? ==

Yes it is, but for Linux only, at the moment, and starting with v2.11.
Also, important caveat: this kind of build is solely intended for development and tests. Do not use in production.

Here are the steps to do so:
# Build dependencies locally: Use [[Building_LuxCoreRender#Local_Plain_Build|local plain build]] or [[Building_LuxCoreRender#Local_Continuous_Integration | local CI build]] of LuxCoreDeps
# Inject local dependencies in LuxCore build: <pre>python -m build-system.luxmake.deps --local <path/to/deps> --release test</pre>
# Build a testing wheel: <pre>make wheel-test</pre>
# Inject testing wheel in Blender: Use [[Developing_and_debugging_BlendLuxCore | BlendLuxHelper]]

Comments for step#2:
* You may want to get a clean situation before injecting local deps: <code>make clear</code>
* On Linux, <path/to/depth> should likely be <code>/tmp/conan-cache/luxcoredeps.zip</code> (plain) or <code>/tmp/luxcoredeps/artifact/1/luxcore-deps-ubuntu-latest/luxcore-deps-ubuntu-latest.zip</code> (CI).
* Be careful about build type.If the build type of the deps is <code>Debug</code> and the build type of <code>pyluxcore</code> is <code>Release</code>, or vice-versa, then the build system will recompile all dependencies.
* Release build is faster than Debug build so, if you are just testing compilation, we would recommend you to use Release.

Comments for #3 & #4
For a debugging with luxcoreui only, one can also replace steps #3 & #4 by:
* Step#3bis: Build luxcoreui: <pre>make luxcoreui</pre>

A good practice we recommend:
* Secure plain local build
** Ensure you can build LuxCoreDeps with plain local build
** Ensure you can build and run LuxCore with your local plain built package.
* Secure CI local build
** Ensure you can build LuxCoreDeps with CI local build
** Ensure you can build and run LuxCore with your CI local built package.
* Secure CI server build - private repo
** Commit your work above
** Push your work to one of your repos (not LuxCore, at this stage). This should trigger CI: ensure build is ok.
** Build LuxCore against it (set LuxCore settings beforehands)
* Secure CI server build - main repo
** Merge your work and check CI
** Try compiling LuxCore

== Can I use <code>git bisect</code>? ==

Yes, if you need to find a faulty commit in <code>LuxCore</code>, you can use <code>git bisect</code>.

In that case, please note the correct verb to build LuxCoreRender at each step is
<pre>make clear && make deps && make</pre>

Caveat: this method only works for version >= v2.10.0

Example for Linux (please adapt to other contexts):

<pre>
# For bisecting, we recommend to build in Release type (shorter build time)
export LUX_BUILD_TYPE=Release

# Start git bisecting
git bisect start

# Define bounds
git bisect good samples-v2.10.0 # For instance
git bisect bad HEAD

# Build the app, test it and report status to git bisect
make clear && make deps && make # Build at this stage
./out/install/Release/bin/luxcoreui mytestscene/render.cfg
git bisect <good|bad|skip> # Depending on above test...

# Bisection loop
...

# At a certain point, the bisection stops and points at the faulty commit
# You can reset bisection
git bisect reset
</pre>

== Can I generate debug information for dependencies (LuxCoreDeps)? ==
Yes, it's possible, but only for local build.

In this context, the build type is controlled by <code>DEPS_BUILD_TYPE</code> environment variable, so set it to your target build type before building:

<pre>export DEPS_BUILD_TYPE=Debug</pre>

Then you will build the deps with [[Building_LuxCoreRender#Local_Plain_Build|local plain build]].

After having built dependencies in local, you may want to inject them in LuxCore build. This can be done with the following:

<pre>python -m build-system.luxmake.deps --local <path/to/deps> --release test --build-type=Debug</pre>

(this replaces <code>make deps</code>)

At this stage, you will be able to build LuxCore artifacts, embedding the debug information of dependencies, for instance:
<pre>
export LUX_BUILD_TYPE=Debug
make wheel-test # If the previous steps have been completed, the testing wheel will contain deps' debug info
</pre>

Remark: in this scenario, do not build the dependencies with CI local build, as the deps source files should be inaccessible at the end of the build, what should make the deps debug info useless.

== How can I build a sanitized version of LuxCore? ==

It is possible to build a sanitized version of LuxCore, including <code>luxcoreui</code>, <code>luxcoreconsole</code>, <code>pyluxcore</code> and the wheels.
It just consists in setting the environment variable <code>LUX_SANITIZE</code> before the build:

<pre>export LUX_SANITIZE=1 # or whatever value you want</pre>

To come back to unsanitized build, just <code>unset LUX_SANITIZE</code>.

2 caveats:
* You'll need to export the following before running LuxCore:
<pre>export ASAN_OPTIONS=protect_shadow_gap=0</pre>
otherwise LuxCore will stop early with the following error message:
<pre>terminate called after throwing an instance of 'std::runtime_error'
what(): CUDA driver API error CUDA_ERROR_NOT_INITIALIZED
</pre>
* To run Blender with ASAN, see here: https://developer.blender.org/docs/handbook/tooling/asan/
This may help:
<pre>export ASAN_OPTIONS=check_initialization_order=0:protect_shadow_gap=0:verify_asan_link_order=0</pre>

== In Linux, I try to set an environment variable that should control LuxCore build, but it does not work ==

In Linux, for LuxCore build system to take them into account, the environment variables that control the build (LUX_BUILD_TYPE, LUX_SANITIZE...) should not only be set, but also exported:

<pre>export LUX_BUILD_TYPE=Debug # `set LUX_BUILD_TYPE=Debug` would be insufficient</pre>

== In gdb, how to debug one thread at a time? ==
<pre>set scheduler-locking step</pre>

== Can I contribute with AI-generated content? ==
Yes, you can - we aim at being a modern project!

However, you must follow a few rules:
* Proposed commits from AI must be short, ideally less than a dozen of lines and at any rate not above 20 lines.
* AI usage must be clearly mentionned in the commits messages
* Proposed code must comply with LuxCore license. This is your responsability to ensure that.
* You must have a complete understanding of what you propose and be able to explain every detail of the implementation.
* Your proposal must stay focused on the issue you want to fix or the feature you want to implement. Simultaneous linting, reformating etc. is not allowed.
* You're expected to have a good command of <code>git</code>

Building LuxCoreRender - FAQ

2026-07-24T17:09:49Z

Howetuft: /* Can I contribute with AI-generated content? */

== Is it possible to set-up a local-only, end-to-end, build chain? ==

Yes it is, but for Linux only, at the moment, and starting with v2.11.
Also, important caveat: this kind of build is solely intended for development and tests. Do not use in production.

Here are the steps to do so:
# Build dependencies locally: Use [[Building_LuxCoreRender#Local_Plain_Build|local plain build]] or [[Building_LuxCoreRender#Local_Continuous_Integration | local CI build]] of LuxCoreDeps
# Inject local dependencies in LuxCore build: <pre>python -m build-system.luxmake.deps --local <path/to/deps> --release test</pre>
# Build a testing wheel: <pre>make wheel-test</pre>
# Inject testing wheel in Blender: Use [[Developing_and_debugging_BlendLuxCore | BlendLuxHelper]]

Comments for step#2:
* You may want to get a clean situation before injecting local deps: <code>make clear</code>
* On Linux, <path/to/depth> should likely be <code>/tmp/conan-cache/luxcoredeps.zip</code> (plain) or <code>/tmp/luxcoredeps/artifact/1/luxcore-deps-ubuntu-latest/luxcore-deps-ubuntu-latest.zip</code> (CI).
* Be careful about build type.If the build type of the deps is <code>Debug</code> and the build type of <code>pyluxcore</code> is <code>Release</code>, or vice-versa, then the build system will recompile all dependencies.
* Release build is faster than Debug build so, if you are just testing compilation, we would recommend you to use Release.

Comments for #3 & #4
For a debugging with luxcoreui only, one can also replace steps #3 & #4 by:
* Step#3bis: Build luxcoreui: <pre>make luxcoreui</pre>

A good practice we recommend:
* Secure plain local build
** Ensure you can build LuxCoreDeps with plain local build
** Ensure you can build and run LuxCore with your local plain built package.
* Secure CI local build
** Ensure you can build LuxCoreDeps with CI local build
** Ensure you can build and run LuxCore with your CI local built package.
* Secure CI server build - private repo
** Commit your work above
** Push your work to one of your repos (not LuxCore, at this stage). This should trigger CI: ensure build is ok.
** Build LuxCore against it (set LuxCore settings beforehands)
* Secure CI server build - main repo
** Merge your work and check CI
** Try compiling LuxCore

== Can I use <code>git bisect</code>? ==

Yes, if you need to find a faulty commit in <code>LuxCore</code>, you can use <code>git bisect</code>.

In that case, please note the correct verb to build LuxCoreRender at each step is
<pre>make clear && make deps && make</pre>

Caveat: this method only works for version >= v2.10.0

Example for Linux (please adapt to other contexts):

<pre>
# For bisecting, we recommend to build in Release type (shorter build time)
export LUX_BUILD_TYPE=Release

# Start git bisecting
git bisect start

# Define bounds
git bisect good samples-v2.10.0 # For instance
git bisect bad HEAD

# Build the app, test it and report status to git bisect
make clear && make deps && make # Build at this stage
./out/install/Release/bin/luxcoreui mytestscene/render.cfg
git bisect <good|bad|skip> # Depending on above test...

# Bisection loop
...

# At a certain point, the bisection stops and points at the faulty commit
# You can reset bisection
git bisect reset
</pre>

== Can I generate debug information for dependencies (LuxCoreDeps)? ==
Yes, it's possible, but only for local build.

In this context, the build type is controlled by <code>DEPS_BUILD_TYPE</code> environment variable, so set it to your target build type before building:

<pre>export DEPS_BUILD_TYPE=Debug</pre>

Then you will build the deps with [[Building_LuxCoreRender#Local_Plain_Build|local plain build]].

After having built dependencies in local, you may want to inject them in LuxCore build. This can be done with the following:

<pre>python -m build-system.luxmake.deps --local <path/to/deps> --release test --build-type=Debug</pre>

(this replaces <code>make deps</code>)

At this stage, you will be able to build LuxCore artifacts, embedding the debug information of dependencies, for instance:
<pre>
export LUX_BUILD_TYPE=Debug
make wheel-test # If the previous steps have been completed, the testing wheel will contain deps' debug info
</pre>

Remark: in this scenario, do not build the dependencies with CI local build, as the deps source files should be inaccessible at the end of the build, what should make the deps debug info useless.

== How can I build a sanitized version of LuxCore? ==

It is possible to build a sanitized version of LuxCore, including <code>luxcoreui</code>, <code>luxcoreconsole</code>, <code>pyluxcore</code> and the wheels.
It just consists in setting the environment variable <code>LUX_SANITIZE</code> before the build:

<pre>export LUX_SANITIZE=1 # or whatever value you want</pre>

To come back to unsanitized build, just <code>unset LUX_SANITIZE</code>.

2 caveats:
* You'll need to export the following before running LuxCore:
<pre>export ASAN_OPTIONS=protect_shadow_gap=0</pre>
otherwise LuxCore will stop early with the following error message:
<pre>terminate called after throwing an instance of 'std::runtime_error'
what(): CUDA driver API error CUDA_ERROR_NOT_INITIALIZED
</pre>
* To run Blender with ASAN, see here: https://developer.blender.org/docs/handbook/tooling/asan/
This may help:
<pre>export ASAN_OPTIONS=check_initialization_order=0:protect_shadow_gap=0:verify_asan_link_order=0</pre>

== In Linux, I try to set an environment variable that should control LuxCore build, but it does not work ==

In Linux, for LuxCore build system to take them into account, the environment variables that control the build (LUX_BUILD_TYPE, LUX_SANITIZE...) should not only be set, but also exported:

<pre>export LUX_BUILD_TYPE=Debug # `set LUX_BUILD_TYPE=Debug` would be insufficient</pre>

== In gdb, how to debug one thread at a time? ==
<pre>set scheduler-locking step</pre>

== Can I contribute with AI-generated content? ==
Yes, you can - we aim at being a modern project!

However, you must follow a few rules:
* Proposed commits from AI must be short, ideally less than a dozen of lines and at any rate not above 20 lines.
* AI usage must be clearly mentionned in the PR
* Proposed code must comply with license.
* You must have a complete understanding of what you propose and be able to explain every detail of the implementation.
* Your proposal must stay focused on the issue you want to fix or the feature you want to implement. Simultaneous linting, reformating etc. is not allowed.
* You're expected to have a good command of <code>git</code>

Building LuxCoreRender - FAQ

2026-07-24T16:39:31Z

Howetuft: /* Can I contribute with AI-generated content? */

== Is it possible to set-up a local-only, end-to-end, build chain? ==

Yes it is, but for Linux only, at the moment, and starting with v2.11.
Also, important caveat: this kind of build is solely intended for development and tests. Do not use in production.

Here are the steps to do so:
# Build dependencies locally: Use [[Building_LuxCoreRender#Local_Plain_Build|local plain build]] or [[Building_LuxCoreRender#Local_Continuous_Integration | local CI build]] of LuxCoreDeps
# Inject local dependencies in LuxCore build: <pre>python -m build-system.luxmake.deps --local <path/to/deps> --release test</pre>
# Build a testing wheel: <pre>make wheel-test</pre>
# Inject testing wheel in Blender: Use [[Developing_and_debugging_BlendLuxCore | BlendLuxHelper]]

Comments for step#2:
* You may want to get a clean situation before injecting local deps: <code>make clear</code>
* On Linux, <path/to/depth> should likely be <code>/tmp/conan-cache/luxcoredeps.zip</code> (plain) or <code>/tmp/luxcoredeps/artifact/1/luxcore-deps-ubuntu-latest/luxcore-deps-ubuntu-latest.zip</code> (CI).
* Be careful about build type.If the build type of the deps is <code>Debug</code> and the build type of <code>pyluxcore</code> is <code>Release</code>, or vice-versa, then the build system will recompile all dependencies.
* Release build is faster than Debug build so, if you are just testing compilation, we would recommend you to use Release.

Comments for #3 & #4
For a debugging with luxcoreui only, one can also replace steps #3 & #4 by:
* Step#3bis: Build luxcoreui: <pre>make luxcoreui</pre>

A good practice we recommend:
* Secure plain local build
** Ensure you can build LuxCoreDeps with plain local build
** Ensure you can build and run LuxCore with your local plain built package.
* Secure CI local build
** Ensure you can build LuxCoreDeps with CI local build
** Ensure you can build and run LuxCore with your CI local built package.
* Secure CI server build - private repo
** Commit your work above
** Push your work to one of your repos (not LuxCore, at this stage). This should trigger CI: ensure build is ok.
** Build LuxCore against it (set LuxCore settings beforehands)
* Secure CI server build - main repo
** Merge your work and check CI
** Try compiling LuxCore

== Can I use <code>git bisect</code>? ==

Yes, if you need to find a faulty commit in <code>LuxCore</code>, you can use <code>git bisect</code>.

In that case, please note the correct verb to build LuxCoreRender at each step is
<pre>make clear && make deps && make</pre>

Caveat: this method only works for version >= v2.10.0

Example for Linux (please adapt to other contexts):

<pre>
# For bisecting, we recommend to build in Release type (shorter build time)
export LUX_BUILD_TYPE=Release

# Start git bisecting
git bisect start

# Define bounds
git bisect good samples-v2.10.0 # For instance
git bisect bad HEAD

# Build the app, test it and report status to git bisect
make clear && make deps && make # Build at this stage
./out/install/Release/bin/luxcoreui mytestscene/render.cfg
git bisect <good|bad|skip> # Depending on above test...

# Bisection loop
...

# At a certain point, the bisection stops and points at the faulty commit
# You can reset bisection
git bisect reset
</pre>

== Can I generate debug information for dependencies (LuxCoreDeps)? ==
Yes, it's possible, but only for local build.

In this context, the build type is controlled by <code>DEPS_BUILD_TYPE</code> environment variable, so set it to your target build type before building:

<pre>export DEPS_BUILD_TYPE=Debug</pre>

Then you will build the deps with [[Building_LuxCoreRender#Local_Plain_Build|local plain build]].

After having built dependencies in local, you may want to inject them in LuxCore build. This can be done with the following:

<pre>python -m build-system.luxmake.deps --local <path/to/deps> --release test --build-type=Debug</pre>

(this replaces <code>make deps</code>)

At this stage, you will be able to build LuxCore artifacts, embedding the debug information of dependencies, for instance:
<pre>
export LUX_BUILD_TYPE=Debug
make wheel-test # If the previous steps have been completed, the testing wheel will contain deps' debug info
</pre>

Remark: in this scenario, do not build the dependencies with CI local build, as the deps source files should be inaccessible at the end of the build, what should make the deps debug info useless.

== How can I build a sanitized version of LuxCore? ==

It is possible to build a sanitized version of LuxCore, including <code>luxcoreui</code>, <code>luxcoreconsole</code>, <code>pyluxcore</code> and the wheels.
It just consists in setting the environment variable <code>LUX_SANITIZE</code> before the build:

<pre>export LUX_SANITIZE=1 # or whatever value you want</pre>

To come back to unsanitized build, just <code>unset LUX_SANITIZE</code>.

2 caveats:
* You'll need to export the following before running LuxCore:
<pre>export ASAN_OPTIONS=protect_shadow_gap=0</pre>
otherwise LuxCore will stop early with the following error message:
<pre>terminate called after throwing an instance of 'std::runtime_error'
what(): CUDA driver API error CUDA_ERROR_NOT_INITIALIZED
</pre>
* To run Blender with ASAN, see here: https://developer.blender.org/docs/handbook/tooling/asan/
This may help:
<pre>export ASAN_OPTIONS=check_initialization_order=0:protect_shadow_gap=0:verify_asan_link_order=0</pre>

== In Linux, I try to set an environment variable that should control LuxCore build, but it does not work ==

In Linux, for LuxCore build system to take them into account, the environment variables that control the build (LUX_BUILD_TYPE, LUX_SANITIZE...) should not only be set, but also exported:

<pre>export LUX_BUILD_TYPE=Debug # `set LUX_BUILD_TYPE=Debug` would be insufficient</pre>

== In gdb, how to debug one thread at a time? ==
<pre>set scheduler-locking step</pre>

== Can I contribute with AI-generated content? ==
Yes, you can - we aim at being a modern project!

However, you must follow a few rules:
* Proposed commits from AI must be short, ideally less than a dozen of lines and at any rate not above 20 lines.
* AI usage must be clearly mentionned in the PR
* Proposed code must comply with license.
* You must have a complete understanding of what you propose and be able to explain every detail of the implementation.
* Your proposal must stay focused on the issue you want to fix or the feature you want to implement. Simultaneous linting, reformating etc. is not allowed.
* You have to master `git`

Building LuxCoreRender - FAQ

2026-07-24T16:38:32Z

Howetuft: /* In gdb, how to debug one thread at a time? */

== Is it possible to set-up a local-only, end-to-end, build chain? ==

Yes it is, but for Linux only, at the moment, and starting with v2.11.
Also, important caveat: this kind of build is solely intended for development and tests. Do not use in production.

Here are the steps to do so:
# Build dependencies locally: Use [[Building_LuxCoreRender#Local_Plain_Build|local plain build]] or [[Building_LuxCoreRender#Local_Continuous_Integration | local CI build]] of LuxCoreDeps
# Inject local dependencies in LuxCore build: <pre>python -m build-system.luxmake.deps --local <path/to/deps> --release test</pre>
# Build a testing wheel: <pre>make wheel-test</pre>
# Inject testing wheel in Blender: Use [[Developing_and_debugging_BlendLuxCore | BlendLuxHelper]]

Comments for step#2:
* You may want to get a clean situation before injecting local deps: <code>make clear</code>
* On Linux, <path/to/depth> should likely be <code>/tmp/conan-cache/luxcoredeps.zip</code> (plain) or <code>/tmp/luxcoredeps/artifact/1/luxcore-deps-ubuntu-latest/luxcore-deps-ubuntu-latest.zip</code> (CI).
* Be careful about build type.If the build type of the deps is <code>Debug</code> and the build type of <code>pyluxcore</code> is <code>Release</code>, or vice-versa, then the build system will recompile all dependencies.
* Release build is faster than Debug build so, if you are just testing compilation, we would recommend you to use Release.

Comments for #3 & #4
For a debugging with luxcoreui only, one can also replace steps #3 & #4 by:
* Step#3bis: Build luxcoreui: <pre>make luxcoreui</pre>

A good practice we recommend:
* Secure plain local build
** Ensure you can build LuxCoreDeps with plain local build
** Ensure you can build and run LuxCore with your local plain built package.
* Secure CI local build
** Ensure you can build LuxCoreDeps with CI local build
** Ensure you can build and run LuxCore with your CI local built package.
* Secure CI server build - private repo
** Commit your work above
** Push your work to one of your repos (not LuxCore, at this stage). This should trigger CI: ensure build is ok.
** Build LuxCore against it (set LuxCore settings beforehands)
* Secure CI server build - main repo
** Merge your work and check CI
** Try compiling LuxCore

== Can I use <code>git bisect</code>? ==

Yes, if you need to find a faulty commit in <code>LuxCore</code>, you can use <code>git bisect</code>.

In that case, please note the correct verb to build LuxCoreRender at each step is
<pre>make clear && make deps && make</pre>

Caveat: this method only works for version >= v2.10.0

Example for Linux (please adapt to other contexts):

<pre>
# For bisecting, we recommend to build in Release type (shorter build time)
export LUX_BUILD_TYPE=Release

# Start git bisecting
git bisect start

# Define bounds
git bisect good samples-v2.10.0 # For instance
git bisect bad HEAD

# Build the app, test it and report status to git bisect
make clear && make deps && make # Build at this stage
./out/install/Release/bin/luxcoreui mytestscene/render.cfg
git bisect <good|bad|skip> # Depending on above test...

# Bisection loop
...

# At a certain point, the bisection stops and points at the faulty commit
# You can reset bisection
git bisect reset
</pre>

== Can I generate debug information for dependencies (LuxCoreDeps)? ==
Yes, it's possible, but only for local build.

In this context, the build type is controlled by <code>DEPS_BUILD_TYPE</code> environment variable, so set it to your target build type before building:

<pre>export DEPS_BUILD_TYPE=Debug</pre>

Then you will build the deps with [[Building_LuxCoreRender#Local_Plain_Build|local plain build]].

After having built dependencies in local, you may want to inject them in LuxCore build. This can be done with the following:

<pre>python -m build-system.luxmake.deps --local <path/to/deps> --release test --build-type=Debug</pre>

(this replaces <code>make deps</code>)

At this stage, you will be able to build LuxCore artifacts, embedding the debug information of dependencies, for instance:
<pre>
export LUX_BUILD_TYPE=Debug
make wheel-test # If the previous steps have been completed, the testing wheel will contain deps' debug info
</pre>

Remark: in this scenario, do not build the dependencies with CI local build, as the deps source files should be inaccessible at the end of the build, what should make the deps debug info useless.

== How can I build a sanitized version of LuxCore? ==

It is possible to build a sanitized version of LuxCore, including <code>luxcoreui</code>, <code>luxcoreconsole</code>, <code>pyluxcore</code> and the wheels.
It just consists in setting the environment variable <code>LUX_SANITIZE</code> before the build:

<pre>export LUX_SANITIZE=1 # or whatever value you want</pre>

To come back to unsanitized build, just <code>unset LUX_SANITIZE</code>.

2 caveats:
* You'll need to export the following before running LuxCore:
<pre>export ASAN_OPTIONS=protect_shadow_gap=0</pre>
otherwise LuxCore will stop early with the following error message:
<pre>terminate called after throwing an instance of 'std::runtime_error'
what(): CUDA driver API error CUDA_ERROR_NOT_INITIALIZED
</pre>
* To run Blender with ASAN, see here: https://developer.blender.org/docs/handbook/tooling/asan/
This may help:
<pre>export ASAN_OPTIONS=check_initialization_order=0:protect_shadow_gap=0:verify_asan_link_order=0</pre>

== In Linux, I try to set an environment variable that should control LuxCore build, but it does not work ==

In Linux, for LuxCore build system to take them into account, the environment variables that control the build (LUX_BUILD_TYPE, LUX_SANITIZE...) should not only be set, but also exported:

<pre>export LUX_BUILD_TYPE=Debug # `set LUX_BUILD_TYPE=Debug` would be insufficient</pre>

== In gdb, how to debug one thread at a time? ==
<pre>set scheduler-locking step</pre>

== Can I contribute with AI-generated content? ==
Yes, you can - we aim at being a modern project!

However, you must follow a few rules:
* Proposed commits from AI must be short, ideally less than a dozen of lines and at any rate not above 20 lines.
* AI usage must be clearly mentionned in the PR
* You must have a complete understanding of what you propose and be able to explain every detail of the implementation.
* Your proposal must stay focused on the issue you want to fix or the feature you want to implement. Simultaneous linting, reformating etc. is not allowed.
* You have to master `git`

Building LuxCoreRender - FAQ

2026-07-24T16:38:15Z

Howetuft:

== Is it possible to set-up a local-only, end-to-end, build chain? ==

Yes it is, but for Linux only, at the moment, and starting with v2.11.
Also, important caveat: this kind of build is solely intended for development and tests. Do not use in production.

Here are the steps to do so:
# Build dependencies locally: Use [[Building_LuxCoreRender#Local_Plain_Build|local plain build]] or [[Building_LuxCoreRender#Local_Continuous_Integration | local CI build]] of LuxCoreDeps
# Inject local dependencies in LuxCore build: <pre>python -m build-system.luxmake.deps --local <path/to/deps> --release test</pre>
# Build a testing wheel: <pre>make wheel-test</pre>
# Inject testing wheel in Blender: Use [[Developing_and_debugging_BlendLuxCore | BlendLuxHelper]]

Comments for step#2:
* You may want to get a clean situation before injecting local deps: <code>make clear</code>
* On Linux, <path/to/depth> should likely be <code>/tmp/conan-cache/luxcoredeps.zip</code> (plain) or <code>/tmp/luxcoredeps/artifact/1/luxcore-deps-ubuntu-latest/luxcore-deps-ubuntu-latest.zip</code> (CI).
* Be careful about build type.If the build type of the deps is <code>Debug</code> and the build type of <code>pyluxcore</code> is <code>Release</code>, or vice-versa, then the build system will recompile all dependencies.
* Release build is faster than Debug build so, if you are just testing compilation, we would recommend you to use Release.

Comments for #3 & #4
For a debugging with luxcoreui only, one can also replace steps #3 & #4 by:
* Step#3bis: Build luxcoreui: <pre>make luxcoreui</pre>

A good practice we recommend:
* Secure plain local build
** Ensure you can build LuxCoreDeps with plain local build
** Ensure you can build and run LuxCore with your local plain built package.
* Secure CI local build
** Ensure you can build LuxCoreDeps with CI local build
** Ensure you can build and run LuxCore with your CI local built package.
* Secure CI server build - private repo
** Commit your work above
** Push your work to one of your repos (not LuxCore, at this stage). This should trigger CI: ensure build is ok.
** Build LuxCore against it (set LuxCore settings beforehands)
* Secure CI server build - main repo
** Merge your work and check CI
** Try compiling LuxCore

== Can I use <code>git bisect</code>? ==

Yes, if you need to find a faulty commit in <code>LuxCore</code>, you can use <code>git bisect</code>.

In that case, please note the correct verb to build LuxCoreRender at each step is
<pre>make clear && make deps && make</pre>

Caveat: this method only works for version >= v2.10.0

Example for Linux (please adapt to other contexts):

<pre>
# For bisecting, we recommend to build in Release type (shorter build time)
export LUX_BUILD_TYPE=Release

# Start git bisecting
git bisect start

# Define bounds
git bisect good samples-v2.10.0 # For instance
git bisect bad HEAD

# Build the app, test it and report status to git bisect
make clear && make deps && make # Build at this stage
./out/install/Release/bin/luxcoreui mytestscene/render.cfg
git bisect <good|bad|skip> # Depending on above test...

# Bisection loop
...

# At a certain point, the bisection stops and points at the faulty commit
# You can reset bisection
git bisect reset
</pre>

== Can I generate debug information for dependencies (LuxCoreDeps)? ==
Yes, it's possible, but only for local build.

In this context, the build type is controlled by <code>DEPS_BUILD_TYPE</code> environment variable, so set it to your target build type before building:

<pre>export DEPS_BUILD_TYPE=Debug</pre>

Then you will build the deps with [[Building_LuxCoreRender#Local_Plain_Build|local plain build]].

After having built dependencies in local, you may want to inject them in LuxCore build. This can be done with the following:

<pre>python -m build-system.luxmake.deps --local <path/to/deps> --release test --build-type=Debug</pre>

(this replaces <code>make deps</code>)

At this stage, you will be able to build LuxCore artifacts, embedding the debug information of dependencies, for instance:
<pre>
export LUX_BUILD_TYPE=Debug
make wheel-test # If the previous steps have been completed, the testing wheel will contain deps' debug info
</pre>

Remark: in this scenario, do not build the dependencies with CI local build, as the deps source files should be inaccessible at the end of the build, what should make the deps debug info useless.

== How can I build a sanitized version of LuxCore? ==

It is possible to build a sanitized version of LuxCore, including <code>luxcoreui</code>, <code>luxcoreconsole</code>, <code>pyluxcore</code> and the wheels.
It just consists in setting the environment variable <code>LUX_SANITIZE</code> before the build:

<pre>export LUX_SANITIZE=1 # or whatever value you want</pre>

To come back to unsanitized build, just <code>unset LUX_SANITIZE</code>.

2 caveats:
* You'll need to export the following before running LuxCore:
<pre>export ASAN_OPTIONS=protect_shadow_gap=0</pre>
otherwise LuxCore will stop early with the following error message:
<pre>terminate called after throwing an instance of 'std::runtime_error'
what(): CUDA driver API error CUDA_ERROR_NOT_INITIALIZED
</pre>
* To run Blender with ASAN, see here: https://developer.blender.org/docs/handbook/tooling/asan/
This may help:
<pre>export ASAN_OPTIONS=check_initialization_order=0:protect_shadow_gap=0:verify_asan_link_order=0</pre>

== In Linux, I try to set an environment variable that should control LuxCore build, but it does not work ==

In Linux, for LuxCore build system to take them into account, the environment variables that control the build (LUX_BUILD_TYPE, LUX_SANITIZE...) should not only be set, but also exported:

<pre>export LUX_BUILD_TYPE=Debug # `set LUX_BUILD_TYPE=Debug` would be insufficient</pre>

== In gdb, how to debug one thread at a time? ==
<pre>set scheduler-locking step</pre>

== Can I contribute with AI-generated content?
Yes, you can - we aim at being a modern project!

However, you must follow a few rules:
* Proposed commits from AI must be short, ideally less than a dozen of lines and at any rate not above 20 lines.
* AI usage must be clearly mentionned in the PR
* You must have a complete understanding of what you propose and be able to explain every detail of the implementation.
* Your proposal must stay focused on the issue you want to fix or the feature you want to implement. Simultaneous linting, reformating etc. is not allowed.
* You have to master `git`

Building LuxCoreRender - FAQ

2026-07-18T12:15:49Z

Howetuft: /* Is it possible to set-up a local-only, end-to-end, build chain? */

Building LuxCoreRender - FAQ

2026-07-18T11:59:25Z

Howetuft: /* Is it possible to set-up a local-only, end-to-end, build chain? */

== Is it possible to set-up a local-only, end-to-end, build chain? ==

Yes it is, but for Linux only, at the moment, and starting with v2.11.
Also, important caveat: this kind of build is solely intended for development and tests. Do not use in production.

Here are the steps to do so:
# Build dependencies locally: Use [[Building_LuxCoreRender#Local_Plain_Build|local plain build]] or [[Building_LuxCoreRender#Local_Continuous_Integration | local CI build]] of LuxCoreDeps
# Inject local dependencies in LuxCore build: <pre>python -m build-system.luxmake.deps --local <path/to/deps> --release test</pre>
# Build a testing wheel: <pre>make wheel-test</pre>
# Inject testing wheel in Blender: Use [[Developing_and_debugging_BlendLuxCore | BlendLuxHelper]]

Important, for step#2:
* You may want to get a clean situation before injecting local deps: <code>make clear</code>
* On Linux, <path/to/depth> should likely be <code>/tmp/conan-cache/luxcoredeps.zip</code> (plain) or <code>/tmp/luxcoredeps/artifact/1/luxcore-deps-ubuntu-latest/luxcore-deps-ubuntu-latest.zip</code> (CI).
* Be careful about build type.If the build type of the deps is <code>Debug</code> and the build type of <code>pyluxcore</code> is <code>Release</code>, or vice-versa, then the build system will recompile all dependencies.
* Release build is faster than Debug build so, if you are just testing compilation, we would recommend you to use Release.

A good practice we recommend:
* Secure plain local build
** Ensure you can build LuxCoreDeps with plain local build
** Ensure you can build and run LuxCore with your local plain built package.
* Secure CI local build
** Ensure you can build LuxCoreDeps with CI local build
** Ensure you can build and run LuxCore with your CI local built package.
* Secure CI server build - private repo
** Commit your work above
** Push your work to one of your repos (not LuxCore, at this stage). This should trigger CI: ensure build is ok.
** Build LuxCore against it (set LuxCore settings beforehands)
* Secure CI server build - main repo
** Merge your work and check CI
** Try compiling LuxCore

For a debugging with luxcoreui only, one can also replace steps #3 & #4 by:

* Step#3bis: Build luxcoreui: <pre>make luxcoreui</pre>

== Can I use <code>git bisect</code>? ==

Yes, if you need to find a faulty commit in <code>LuxCore</code>, you can use <code>git bisect</code>.

In that case, please note the correct verb to build LuxCoreRender at each step is
<pre>make clear && make deps && make</pre>

Caveat: this method only works for version >= v2.10.0

Example for Linux (please adapt to other contexts):

<pre>
# For bisecting, we recommend to build in Release type (shorter build time)
export LUX_BUILD_TYPE=Release

# Start git bisecting
git bisect start

# Define bounds
git bisect good samples-v2.10.0 # For instance
git bisect bad HEAD

# Build the app, test it and report status to git bisect
make clear && make deps && make # Build at this stage
./out/install/Release/bin/luxcoreui mytestscene/render.cfg
git bisect <good|bad|skip> # Depending on above test...

# Bisection loop
...

# At a certain point, the bisection stops and points at the faulty commit
# You can reset bisection
git bisect reset
</pre>

== Can I generate debug information for dependencies (LuxCoreDeps)? ==
Yes, it's possible, but only for local build.

In this context, the build type is controlled by <code>DEPS_BUILD_TYPE</code> environment variable, so set it to your target build type before building:

<pre>export DEPS_BUILD_TYPE=Debug</pre>

Then you will build the deps with [[Building_LuxCoreRender#Local_Plain_Build|local plain build]].

After having built dependencies in local, you may want to inject them in LuxCore build. This can be done with the following:

<pre>python -m build-system.luxmake.deps --local <path/to/deps> --release test --build-type=Debug</pre>

(this replaces <code>make deps</code>)

At this stage, you will be able to build LuxCore artifacts, embedding the debug information of dependencies, for instance:
<pre>
export LUX_BUILD_TYPE=Debug
make wheel-test # If the previous steps have been completed, the testing wheel will contain deps' debug info
</pre>

Remark: in this scenario, do not build the dependencies with CI local build, as the deps source files should be inaccessible at the end of the build, what should make the deps debug info useless.

== How can I build a sanitized version of LuxCore? ==

It is possible to build a sanitized version of LuxCore, including <code>luxcoreui</code>, <code>luxcoreconsole</code>, <code>pyluxcore</code> and the wheels.
It just consists in setting the environment variable <code>LUX_SANITIZE</code> before the build:

<pre>export LUX_SANITIZE=1 # or whatever value you want</pre>

To come back to unsanitized build, just <code>unset LUX_SANITIZE</code>.

2 caveats:
* You'll need to export the following before running LuxCore:
<pre>export ASAN_OPTIONS=protect_shadow_gap=0</pre>
otherwise LuxCore will stop early with the following error message:
<pre>terminate called after throwing an instance of 'std::runtime_error'
what(): CUDA driver API error CUDA_ERROR_NOT_INITIALIZED
</pre>
* To run Blender with ASAN, see here: https://developer.blender.org/docs/handbook/tooling/asan/
This may help:
<pre>export ASAN_OPTIONS=check_initialization_order=0:protect_shadow_gap=0:verify_asan_link_order=0</pre>

== In Linux, I try to set an environment variable that should control LuxCore build, but it does not work ==

In Linux, for LuxCore build system to take them into account, the environment variables that control the build (LUX_BUILD_TYPE, LUX_SANITIZE...) should not only be set, but also exported:

<pre>export LUX_BUILD_TYPE=Debug # `set LUX_BUILD_TYPE=Debug` would be insufficient</pre>

== In gdb, how to debug one thread at a time? ==
<pre>set scheduler-locking step</pre>

Building LuxCoreRender - FAQ

2026-07-18T11:57:31Z

Howetuft: /* Is it possible to set-up a local-only, end-to-end, build chain? */

== Is it possible to set-up a local-only, end-to-end, build chain? ==

Yes it is, but for Linux only, at the moment, and starting with v2.11.
Also, important caveat: this kind of build is solely intended for development and tests. Do not use in production.

Here are the steps to do so:
# Build dependencies locally: Use [[Building_LuxCoreRender#Local_Plain_Build|local plain build]] or [[Building_LuxCoreRender#Local_Continuous_Integration | local CI build]] of LuxCoreDeps
# Inject local dependencies in LuxCore build: <pre>python -m build-system.luxmake.deps --local <path/to/deps> --release test</pre>
# Build a testing wheel: <pre>make wheel-test</pre>
# Inject testing wheel in Blender: Use [[Developing_and_debugging_BlendLuxCore | BlendLuxHelper]]

Important, for step#2:
* You may want to get a clean situation before injecting local deps: <code>make clear</code>
* On Linux, <path/to/depth> should likely be <code>/tmp/conan-cache/luxcoredeps.zip</code> (plain) or <code>/tmp/luxcoredeps/artifact/1/luxcore-deps-ubuntu-latest/luxcore-deps-ubuntu-latest.zip</code> (CI).
* Be careful about build type.If the build type of the deps is <code>Debug</code> and the build type of <code>pyluxcore</code> is <code>Release</code>, or vice-versa, then the build system will recompile all dependencies.
* Release build is faster than Debug build so, if you are just testing compilation, we would recommend you to use Release.

A good practice we recommend:
# Secure plain local build
* Ensure you can build LuxCoreDeps with plain local build
* Ensure you can build and run LuxCore with your local plain built package.
# Secure CI local build
* Ensure you can build LuxCoreDeps with CI local build
* Ensure you can build and run LuxCore with your CI local built package.
# Secure CI server build - private repo
* Commit your work above
* Push your work to one of your repos (not LuxCore, at this stage). This should trigger CI: ensure build is ok.
* build LuxCore against it (set LuxCore settings beforehands)
# Secure CI server build - main repo
* Merge your work and check CI
* Try compiling LuxCore

For a debugging with luxcoreui only, one can also replace steps #3 & #4 by:

* Step#3bis: Build luxcoreui: <pre>make luxcoreui</pre>

== Can I use <code>git bisect</code>? ==

Yes, if you need to find a faulty commit in <code>LuxCore</code>, you can use <code>git bisect</code>.

In that case, please note the correct verb to build LuxCoreRender at each step is
<pre>make clear && make deps && make</pre>

Caveat: this method only works for version >= v2.10.0

Example for Linux (please adapt to other contexts):

<pre>
# For bisecting, we recommend to build in Release type (shorter build time)
export LUX_BUILD_TYPE=Release

# Start git bisecting
git bisect start

# Define bounds
git bisect good samples-v2.10.0 # For instance
git bisect bad HEAD

# Build the app, test it and report status to git bisect
make clear && make deps && make # Build at this stage
./out/install/Release/bin/luxcoreui mytestscene/render.cfg
git bisect <good|bad|skip> # Depending on above test...

# Bisection loop
...

# At a certain point, the bisection stops and points at the faulty commit
# You can reset bisection
git bisect reset
</pre>

== Can I generate debug information for dependencies (LuxCoreDeps)? ==
Yes, it's possible, but only for local build.

In this context, the build type is controlled by <code>DEPS_BUILD_TYPE</code> environment variable, so set it to your target build type before building:

<pre>export DEPS_BUILD_TYPE=Debug</pre>

Then you will build the deps with [[Building_LuxCoreRender#Local_Plain_Build|local plain build]].

After having built dependencies in local, you may want to inject them in LuxCore build. This can be done with the following:

<pre>python -m build-system.luxmake.deps --local <path/to/deps> --release test --build-type=Debug</pre>

(this replaces <code>make deps</code>)

At this stage, you will be able to build LuxCore artifacts, embedding the debug information of dependencies, for instance:
<pre>
export LUX_BUILD_TYPE=Debug
make wheel-test # If the previous steps have been completed, the testing wheel will contain deps' debug info
</pre>

Remark: in this scenario, do not build the dependencies with CI local build, as the deps source files should be inaccessible at the end of the build, what should make the deps debug info useless.

== How can I build a sanitized version of LuxCore? ==

It is possible to build a sanitized version of LuxCore, including <code>luxcoreui</code>, <code>luxcoreconsole</code>, <code>pyluxcore</code> and the wheels.
It just consists in setting the environment variable <code>LUX_SANITIZE</code> before the build:

<pre>export LUX_SANITIZE=1 # or whatever value you want</pre>

To come back to unsanitized build, just <code>unset LUX_SANITIZE</code>.

2 caveats:
* You'll need to export the following before running LuxCore:
<pre>export ASAN_OPTIONS=protect_shadow_gap=0</pre>
otherwise LuxCore will stop early with the following error message:
<pre>terminate called after throwing an instance of 'std::runtime_error'
what(): CUDA driver API error CUDA_ERROR_NOT_INITIALIZED
</pre>
* To run Blender with ASAN, see here: https://developer.blender.org/docs/handbook/tooling/asan/
This may help:
<pre>export ASAN_OPTIONS=check_initialization_order=0:protect_shadow_gap=0:verify_asan_link_order=0</pre>

== In Linux, I try to set an environment variable that should control LuxCore build, but it does not work ==

In Linux, for LuxCore build system to take them into account, the environment variables that control the build (LUX_BUILD_TYPE, LUX_SANITIZE...) should not only be set, but also exported:

<pre>export LUX_BUILD_TYPE=Debug # `set LUX_BUILD_TYPE=Debug` would be insufficient</pre>

== In gdb, how to debug one thread at a time? ==
<pre>set scheduler-locking step</pre>

Building LuxCoreRender - FAQ

2026-07-18T11:56:55Z

Howetuft: /* Is it possible to set-up a local-only, end-to-end, build chain? */

== Is it possible to set-up a local-only, end-to-end, build chain? ==

Yes it is, but for Linux only, at the moment, and starting with v2.11.
Also, important caveat: this kind of build is solely intended for development and tests. Do not use in production.

Here are the steps to do so:
# Build dependencies locally: Use [[Building_LuxCoreRender#Local_Plain_Build|local plain build]] or [[Building_LuxCoreRender#Local_Continuous_Integration | local CI build]] of LuxCoreDeps
# Inject local dependencies in LuxCore build: <pre>python -m build-system.luxmake.deps --local <path/to/deps> --release test</pre>
# Build a testing wheel: <pre>make wheel-test</pre>
# Inject testing wheel in Blender: Use [[Developing_and_debugging_BlendLuxCore | BlendLuxHelper]]

Important, for step#2:
* You may want to get a clean situation before injecting local deps: <code>make clear</code>
* On Linux, <path/to/depth> should likely be <code>/tmp/conan-cache/luxcoredeps.zip</code> (plain) or <code>/tmp/luxcoredeps/artifact/1/luxcore-deps-ubuntu-latest/luxcore-deps-ubuntu-latest.zip</code> (CI).
* Be careful about build type.If the build type of the deps is <code>Debug</code> and the build type of <code>pyluxcore</code> is <code>Release</code>, or vice-versa, then the build system will recompile all dependencies.
* Release build is faster than Debug build so, if you are just testing compilation, we would recommend you to use Release.

A good practice we recommend:
# Secure plain local build
** Ensure you can build LuxCoreDeps with plain local build
** Ensure you can build and run LuxCore with your local plain built package.
# Secure CI local build
** Ensure you can build LuxCoreDeps with CI local build
** Ensure you can build and run LuxCore with your CI local built package.
# Secure CI server build - private repo
** Commit your work above
** Push your work to one of your repos (not LuxCore, at this stage). This should trigger CI: ensure build is ok.
* build LuxCore against it (set LuxCore settings beforehands)
# Secure CI server build - main repo
** Merge your work and check CI
** Try compiling LuxCore

For a debugging with luxcoreui only, one can also replace steps #3 & #4 by:

* Step#3bis: Build luxcoreui: <pre>make luxcoreui</pre>

== Can I use <code>git bisect</code>? ==

Yes, if you need to find a faulty commit in <code>LuxCore</code>, you can use <code>git bisect</code>.

In that case, please note the correct verb to build LuxCoreRender at each step is
<pre>make clear && make deps && make</pre>

Caveat: this method only works for version >= v2.10.0

Example for Linux (please adapt to other contexts):

<pre>
# For bisecting, we recommend to build in Release type (shorter build time)
export LUX_BUILD_TYPE=Release

# Start git bisecting
git bisect start

# Define bounds
git bisect good samples-v2.10.0 # For instance
git bisect bad HEAD

# Build the app, test it and report status to git bisect
make clear && make deps && make # Build at this stage
./out/install/Release/bin/luxcoreui mytestscene/render.cfg
git bisect <good|bad|skip> # Depending on above test...

# Bisection loop
...

# At a certain point, the bisection stops and points at the faulty commit
# You can reset bisection
git bisect reset
</pre>

== Can I generate debug information for dependencies (LuxCoreDeps)? ==
Yes, it's possible, but only for local build.

In this context, the build type is controlled by <code>DEPS_BUILD_TYPE</code> environment variable, so set it to your target build type before building:

<pre>export DEPS_BUILD_TYPE=Debug</pre>

Then you will build the deps with [[Building_LuxCoreRender#Local_Plain_Build|local plain build]].

After having built dependencies in local, you may want to inject them in LuxCore build. This can be done with the following:

<pre>python -m build-system.luxmake.deps --local <path/to/deps> --release test --build-type=Debug</pre>

(this replaces <code>make deps</code>)

At this stage, you will be able to build LuxCore artifacts, embedding the debug information of dependencies, for instance:
<pre>
export LUX_BUILD_TYPE=Debug
make wheel-test # If the previous steps have been completed, the testing wheel will contain deps' debug info
</pre>

Remark: in this scenario, do not build the dependencies with CI local build, as the deps source files should be inaccessible at the end of the build, what should make the deps debug info useless.

== How can I build a sanitized version of LuxCore? ==

It is possible to build a sanitized version of LuxCore, including <code>luxcoreui</code>, <code>luxcoreconsole</code>, <code>pyluxcore</code> and the wheels.
It just consists in setting the environment variable <code>LUX_SANITIZE</code> before the build:

<pre>export LUX_SANITIZE=1 # or whatever value you want</pre>

To come back to unsanitized build, just <code>unset LUX_SANITIZE</code>.

2 caveats:
* You'll need to export the following before running LuxCore:
<pre>export ASAN_OPTIONS=protect_shadow_gap=0</pre>
otherwise LuxCore will stop early with the following error message:
<pre>terminate called after throwing an instance of 'std::runtime_error'
what(): CUDA driver API error CUDA_ERROR_NOT_INITIALIZED
</pre>
* To run Blender with ASAN, see here: https://developer.blender.org/docs/handbook/tooling/asan/
This may help:
<pre>export ASAN_OPTIONS=check_initialization_order=0:protect_shadow_gap=0:verify_asan_link_order=0</pre>

== In Linux, I try to set an environment variable that should control LuxCore build, but it does not work ==

In Linux, for LuxCore build system to take them into account, the environment variables that control the build (LUX_BUILD_TYPE, LUX_SANITIZE...) should not only be set, but also exported:

<pre>export LUX_BUILD_TYPE=Debug # `set LUX_BUILD_TYPE=Debug` would be insufficient</pre>

== In gdb, how to debug one thread at a time? ==
<pre>set scheduler-locking step</pre>

Building LuxCoreRender - FAQ

2026-07-18T11:55:54Z

Howetuft: /* Is it possible to set-up a local-only, end-to-end, build chain? */

== Is it possible to set-up a local-only, end-to-end, build chain? ==

Yes it is, but for Linux only, at the moment, and starting with v2.11.
Also, important caveat: this kind of build is solely intended for development and tests. Do not use in production.

Here are the steps to do so:
# Build dependencies locally: Use [[Building_LuxCoreRender#Local_Plain_Build|local plain build]] or [[Building_LuxCoreRender#Local_Continuous_Integration | local CI build]] of LuxCoreDeps
# Inject local dependencies in LuxCore build: <pre>python -m build-system.luxmake.deps --local <path/to/deps> --release test</pre>
# Build a testing wheel: <pre>make wheel-test</pre>
# Inject testing wheel in Blender: Use [[Developing_and_debugging_BlendLuxCore | BlendLuxHelper]]

Important, for step#2:
* You may want to get a clean situation before injecting local deps: <code>make clear</code>
* On Linux, <path/to/depth> should likely be <code>/tmp/conan-cache/luxcoredeps.zip</code> (plain) or <code>/tmp/luxcoredeps/artifact/1/luxcore-deps-ubuntu-latest/luxcore-deps-ubuntu-latest.zip</code> (CI).
* Be careful about build type.If the build type of the deps is <code>Debug</code> and the build type of <code>pyluxcore</code> is <code>Release</code>, or vice-versa, then the build system will recompile all dependencies.
* Release build is faster than Debug build so, if you are just testing compilation, we would recommend you to use Release.

A good practice we recommend:
# Secure plain local build
## Ensure you can build LuxCoreDeps with plain local build
## Ensure you can build and run LuxCore with your local plain built package.
# Secure CI local build
## Ensure you can build LuxCoreDeps with CI local build
## Ensure you can build and run LuxCore with your CI local built package.
# Secure CI server build - private repo
## Commit your work above
## Push your work to one of your repos (not LuxCore, at this stage). This should trigger CI: ensure build is ok.
## build LuxCore against it (set LuxCore settings beforehands)
# Secure CI server build - main repo
## Merge your work and check CI
## Try compiling LuxCore

# Merge to

# Ensure you can build and run LuxCore with your local LexCoreDeps
# Ensure

For a debugging with luxcoreui only, one can also replace steps #3 & #4 by:

* Step#3bis: Build luxcoreui: <pre>make luxcoreui</pre>

== Can I use <code>git bisect</code>? ==

Yes, if you need to find a faulty commit in <code>LuxCore</code>, you can use <code>git bisect</code>.

In that case, please note the correct verb to build LuxCoreRender at each step is
<pre>make clear && make deps && make</pre>

Caveat: this method only works for version >= v2.10.0

Example for Linux (please adapt to other contexts):

<pre>
# For bisecting, we recommend to build in Release type (shorter build time)
export LUX_BUILD_TYPE=Release

# Start git bisecting
git bisect start

# Define bounds
git bisect good samples-v2.10.0 # For instance
git bisect bad HEAD

# Build the app, test it and report status to git bisect
make clear && make deps && make # Build at this stage
./out/install/Release/bin/luxcoreui mytestscene/render.cfg
git bisect <good|bad|skip> # Depending on above test...

# Bisection loop
...

# At a certain point, the bisection stops and points at the faulty commit
# You can reset bisection
git bisect reset
</pre>

== Can I generate debug information for dependencies (LuxCoreDeps)? ==
Yes, it's possible, but only for local build.

In this context, the build type is controlled by <code>DEPS_BUILD_TYPE</code> environment variable, so set it to your target build type before building:

<pre>export DEPS_BUILD_TYPE=Debug</pre>

Then you will build the deps with [[Building_LuxCoreRender#Local_Plain_Build|local plain build]].

After having built dependencies in local, you may want to inject them in LuxCore build. This can be done with the following:

<pre>python -m build-system.luxmake.deps --local <path/to/deps> --release test --build-type=Debug</pre>

(this replaces <code>make deps</code>)

At this stage, you will be able to build LuxCore artifacts, embedding the debug information of dependencies, for instance:
<pre>
export LUX_BUILD_TYPE=Debug
make wheel-test # If the previous steps have been completed, the testing wheel will contain deps' debug info
</pre>

Remark: in this scenario, do not build the dependencies with CI local build, as the deps source files should be inaccessible at the end of the build, what should make the deps debug info useless.

== How can I build a sanitized version of LuxCore? ==

It is possible to build a sanitized version of LuxCore, including <code>luxcoreui</code>, <code>luxcoreconsole</code>, <code>pyluxcore</code> and the wheels.
It just consists in setting the environment variable <code>LUX_SANITIZE</code> before the build:

<pre>export LUX_SANITIZE=1 # or whatever value you want</pre>

To come back to unsanitized build, just <code>unset LUX_SANITIZE</code>.

2 caveats:
* You'll need to export the following before running LuxCore:
<pre>export ASAN_OPTIONS=protect_shadow_gap=0</pre>
otherwise LuxCore will stop early with the following error message:
<pre>terminate called after throwing an instance of 'std::runtime_error'
what(): CUDA driver API error CUDA_ERROR_NOT_INITIALIZED
</pre>
* To run Blender with ASAN, see here: https://developer.blender.org/docs/handbook/tooling/asan/
This may help:
<pre>export ASAN_OPTIONS=check_initialization_order=0:protect_shadow_gap=0:verify_asan_link_order=0</pre>

== In Linux, I try to set an environment variable that should control LuxCore build, but it does not work ==

In Linux, for LuxCore build system to take them into account, the environment variables that control the build (LUX_BUILD_TYPE, LUX_SANITIZE...) should not only be set, but also exported:

<pre>export LUX_BUILD_TYPE=Debug # `set LUX_BUILD_TYPE=Debug` would be insufficient</pre>

== In gdb, how to debug one thread at a time? ==
<pre>set scheduler-locking step</pre>

Building LuxCoreRender - FAQ

2026-07-18T11:41:01Z

Howetuft: /* Is it possible to set-up a local-only, end-to-end, build chain? */

== Is it possible to set-up a local-only, end-to-end, build chain? ==

Yes it is, but for Linux only, at the moment, and starting with v2.11.
Also, important caveat: this kind of build is solely intended for development and tests. Do not use in production.

Here are the steps to do so:
# Build dependencies locally: Use [[Building_LuxCoreRender#Local_Plain_Build|local plain build]] or [[Building_LuxCoreRender#Local_Continuous_Integration | local CI build]] of LuxCoreDeps
# Inject local dependencies in LuxCore build: <pre>python -m build-system.luxmake.deps --local <path/to/deps> --release test</pre>
# Build a testing wheel: <pre>make wheel-test</pre>
# Inject testing wheel in Blender: Use [[Developing_and_debugging_BlendLuxCore | BlendLuxHelper]]

Important, for step#2:
* You may want to get a clean situation before injecting local deps: <code>make clear</code>
* On Linux, <path/to/depth> should likely be <code>/tmp/conan-cache/luxcoredeps.zip</code> (plain) or <code>/tmp/luxcoredeps/artifact/1/luxcore-deps-ubuntu-latest/luxcore-deps-ubuntu-latest.zip</code> (CI).
* Be careful about build type.If the build type of the deps is <code>Debug</code> and the build type of <code>pyluxcore</code> is <code>Release</code>, or vice-versa, then the build system will recompile all dependencies.

For a debugging with luxcoreui only, one can also replace steps #3 & #4 by:

* Step#3bis: Build luxcoreui: <pre>make luxcoreui</pre>

== Can I use <code>git bisect</code>? ==

Yes, if you need to find a faulty commit in <code>LuxCore</code>, you can use <code>git bisect</code>.

In that case, please note the correct verb to build LuxCoreRender at each step is
<pre>make clear && make deps && make</pre>

Caveat: this method only works for version >= v2.10.0

Example for Linux (please adapt to other contexts):

<pre>
# For bisecting, we recommend to build in Release type (shorter build time)
export LUX_BUILD_TYPE=Release

# Start git bisecting
git bisect start

# Define bounds
git bisect good samples-v2.10.0 # For instance
git bisect bad HEAD

# Build the app, test it and report status to git bisect
make clear && make deps && make # Build at this stage
./out/install/Release/bin/luxcoreui mytestscene/render.cfg
git bisect <good|bad|skip> # Depending on above test...

# Bisection loop
...

# At a certain point, the bisection stops and points at the faulty commit
# You can reset bisection
git bisect reset
</pre>

== Can I generate debug information for dependencies (LuxCoreDeps)? ==
Yes, it's possible, but only for local build.

In this context, the build type is controlled by <code>DEPS_BUILD_TYPE</code> environment variable, so set it to your target build type before building:

<pre>export DEPS_BUILD_TYPE=Debug</pre>

Then you will build the deps with [[Building_LuxCoreRender#Local_Plain_Build|local plain build]].

After having built dependencies in local, you may want to inject them in LuxCore build. This can be done with the following:

<pre>python -m build-system.luxmake.deps --local <path/to/deps> --release test --build-type=Debug</pre>

(this replaces <code>make deps</code>)

At this stage, you will be able to build LuxCore artifacts, embedding the debug information of dependencies, for instance:
<pre>
export LUX_BUILD_TYPE=Debug
make wheel-test # If the previous steps have been completed, the testing wheel will contain deps' debug info
</pre>

Remark: in this scenario, do not build the dependencies with CI local build, as the deps source files should be inaccessible at the end of the build, what should make the deps debug info useless.

== How can I build a sanitized version of LuxCore? ==

It is possible to build a sanitized version of LuxCore, including <code>luxcoreui</code>, <code>luxcoreconsole</code>, <code>pyluxcore</code> and the wheels.
It just consists in setting the environment variable <code>LUX_SANITIZE</code> before the build:

<pre>export LUX_SANITIZE=1 # or whatever value you want</pre>

To come back to unsanitized build, just <code>unset LUX_SANITIZE</code>.

2 caveats:
* You'll need to export the following before running LuxCore:
<pre>export ASAN_OPTIONS=protect_shadow_gap=0</pre>
otherwise LuxCore will stop early with the following error message:
<pre>terminate called after throwing an instance of 'std::runtime_error'
what(): CUDA driver API error CUDA_ERROR_NOT_INITIALIZED
</pre>
* To run Blender with ASAN, see here: https://developer.blender.org/docs/handbook/tooling/asan/
This may help:
<pre>export ASAN_OPTIONS=check_initialization_order=0:protect_shadow_gap=0:verify_asan_link_order=0</pre>

== In Linux, I try to set an environment variable that should control LuxCore build, but it does not work ==

In Linux, for LuxCore build system to take them into account, the environment variables that control the build (LUX_BUILD_TYPE, LUX_SANITIZE...) should not only be set, but also exported:

<pre>export LUX_BUILD_TYPE=Debug # `set LUX_BUILD_TYPE=Debug` would be insufficient</pre>

== In gdb, how to debug one thread at a time? ==
<pre>set scheduler-locking step</pre>

Building LuxCoreRender - FAQ

2026-07-18T11:40:16Z

Howetuft: /* Is it possible to set-up a local-only, end-to-end, build chain? */

== Is it possible to set-up a local-only, end-to-end, build chain? ==

Yes it is, but for Linux only, at the moment, and starting with v2.11.
Also, important caveat: this kind of build is solely intended for development and tests. Do not use in production.

Here are the steps to do so:
# Build dependencies locally: Use [[Building_LuxCoreRender#Local_Plain_Build|local plain build]] or [[Building_LuxCoreRender#Local_Continuous_Integration | local CI build]] of LuxCoreDeps
# Inject local dependencies in LuxCore:build <pre>python -m build-system.luxmake.deps --local <path/to/deps> --release test</pre>
# Build a testing wheel: <pre>make wheel-test</pre>
# Inject testing wheel in Blender: Use [[Developing_and_debugging_BlendLuxCore | BlendLuxHelper]]

Important, for step#2:
* You may want to get a clean situation before injecting local deps: <code>make clear</code>
* On Linux, <path/to/depth> should likely be <code>/tmp/conan-cache/luxcoredeps.zip</code> (plain) or <code>/tmp/luxcoredeps/artifact/1/luxcore-deps-ubuntu-latest/luxcore-deps-ubuntu-latest.zip</code> (CI).
* Be careful about build type.If the build type of the deps is <code>Debug</code> and the build type of <code>pyluxcore</code> is <code>Release</code>, or vice-versa, then the build system will recompile all dependencies.

For a debugging with luxcoreui only, one can also replace steps #3 & #4 by:

* Step#3bis: Build luxcoreui: <pre>make luxcoreui</pre>

== Can I use <code>git bisect</code>? ==

Yes, if you need to find a faulty commit in <code>LuxCore</code>, you can use <code>git bisect</code>.

In that case, please note the correct verb to build LuxCoreRender at each step is
<pre>make clear && make deps && make</pre>

Caveat: this method only works for version >= v2.10.0

Example for Linux (please adapt to other contexts):

<pre>
# For bisecting, we recommend to build in Release type (shorter build time)
export LUX_BUILD_TYPE=Release

# Start git bisecting
git bisect start

# Define bounds
git bisect good samples-v2.10.0 # For instance
git bisect bad HEAD

# Build the app, test it and report status to git bisect
make clear && make deps && make # Build at this stage
./out/install/Release/bin/luxcoreui mytestscene/render.cfg
git bisect <good|bad|skip> # Depending on above test...

# Bisection loop
...

# At a certain point, the bisection stops and points at the faulty commit
# You can reset bisection
git bisect reset
</pre>

== Can I generate debug information for dependencies (LuxCoreDeps)? ==
Yes, it's possible, but only for local build.

In this context, the build type is controlled by <code>DEPS_BUILD_TYPE</code> environment variable, so set it to your target build type before building:

<pre>export DEPS_BUILD_TYPE=Debug</pre>

Then you will build the deps with [[Building_LuxCoreRender#Local_Plain_Build|local plain build]].

After having built dependencies in local, you may want to inject them in LuxCore build. This can be done with the following:

<pre>python -m build-system.luxmake.deps --local <path/to/deps> --release test --build-type=Debug</pre>

(this replaces <code>make deps</code>)

At this stage, you will be able to build LuxCore artifacts, embedding the debug information of dependencies, for instance:
<pre>
export LUX_BUILD_TYPE=Debug
make wheel-test # If the previous steps have been completed, the testing wheel will contain deps' debug info
</pre>

Remark: in this scenario, do not build the dependencies with CI local build, as the deps source files should be inaccessible at the end of the build, what should make the deps debug info useless.

== How can I build a sanitized version of LuxCore? ==

It is possible to build a sanitized version of LuxCore, including <code>luxcoreui</code>, <code>luxcoreconsole</code>, <code>pyluxcore</code> and the wheels.
It just consists in setting the environment variable <code>LUX_SANITIZE</code> before the build:

<pre>export LUX_SANITIZE=1 # or whatever value you want</pre>

To come back to unsanitized build, just <code>unset LUX_SANITIZE</code>.

2 caveats:
* You'll need to export the following before running LuxCore:
<pre>export ASAN_OPTIONS=protect_shadow_gap=0</pre>
otherwise LuxCore will stop early with the following error message:
<pre>terminate called after throwing an instance of 'std::runtime_error'
what(): CUDA driver API error CUDA_ERROR_NOT_INITIALIZED
</pre>
* To run Blender with ASAN, see here: https://developer.blender.org/docs/handbook/tooling/asan/
This may help:
<pre>export ASAN_OPTIONS=check_initialization_order=0:protect_shadow_gap=0:verify_asan_link_order=0</pre>

== In Linux, I try to set an environment variable that should control LuxCore build, but it does not work ==

In Linux, for LuxCore build system to take them into account, the environment variables that control the build (LUX_BUILD_TYPE, LUX_SANITIZE...) should not only be set, but also exported:

<pre>export LUX_BUILD_TYPE=Debug # `set LUX_BUILD_TYPE=Debug` would be insufficient</pre>

== In gdb, how to debug one thread at a time? ==
<pre>set scheduler-locking step</pre>

Building LuxCoreRender - FAQ

2026-07-17T17:38:53Z

Howetuft: /* Is it possible to set-up a local-only, end-to-end, build chain? */

== Is it possible to set-up a local-only, end-to-end, build chain? ==

Yes it is, but for Linux only, at the moment, and starting with v2.11.
Also, important caveat: this kind of build is solely intended for development and tests. Do not use in production.

Here are the steps to do so:
# Build dependencies locally: Use [[Building_LuxCoreRender#Local_Plain_Build|local plain build]] or [[Building_LuxCoreRender#Local_Continuous_Integration | local CI build]] of LuxCoreDeps
# Inject local dependencies in LuxCore build <pre>python -m build-system.luxmake.deps --local <path/to/deps> --release test</pre>
# Build a testing wheel <pre>make wheel-test</pre>
# Inject testing wheel in Blender: Use [[Developing_and_debugging_BlendLuxCore | BlendLuxHelper]]

Important, for step#2:
* You may want to get a clean situation before injecting local deps: <code>make clear</code>
* On Linux, <path/to/depth> should likely be <code>/tmp/conan-cache/luxcoredeps.zip</code> or <code>/tmp/luxcoredeps/artifact/1/luxcore-deps-ubuntu-latest/luxcore-deps-ubuntu-latest.zip</code>.
* Be careful about build type.If the build type of the deps is <code>Debug</code> and the build type of <code>pyluxcore</code> is <code>Release</code>, or vice-versa, then the build system will recompile all dependencies.

For a debugging with luxcoreui only, one can also replace steps #3 & #4 by:

* Step#3bis: Build luxcoreui:
<pre>make luxcoreui</pre>

== Can I use <code>git bisect</code>? ==

Yes, if you need to find a faulty commit in <code>LuxCore</code>, you can use <code>git bisect</code>.

In that case, please note the correct verb to build LuxCoreRender at each step is
<pre>make clear && make deps && make</pre>

Caveat: this method only works for version >= v2.10.0

Example for Linux (please adapt to other contexts):

<pre>
# For bisecting, we recommend to build in Release type (shorter build time)
export LUX_BUILD_TYPE=Release

# Start git bisecting
git bisect start

# Define bounds
git bisect good samples-v2.10.0 # For instance
git bisect bad HEAD

# Build the app, test it and report status to git bisect
make clear && make deps && make # Build at this stage
./out/install/Release/bin/luxcoreui mytestscene/render.cfg
git bisect <good|bad|skip> # Depending on above test...

# Bisection loop
...

# At a certain point, the bisection stops and points at the faulty commit
# You can reset bisection
git bisect reset
</pre>

== Can I generate debug information for dependencies (LuxCoreDeps)? ==
Yes, it's possible, but only for local build.

In this context, the build type is controlled by <code>DEPS_BUILD_TYPE</code> environment variable, so set it to your target build type before building:

<pre>export DEPS_BUILD_TYPE=Debug</pre>

Then you will build the deps with [[Building_LuxCoreRender#Local_Plain_Build|local plain build]].

After having built dependencies in local, you may want to inject them in LuxCore build. This can be done with the following:

<pre>python -m build-system.luxmake.deps --local <path/to/deps> --release test --build-type=Debug</pre>

(this replaces <code>make deps</code>)

At this stage, you will be able to build LuxCore artifacts, embedding the debug information of dependencies, for instance:
<pre>
export LUX_BUILD_TYPE=Debug
make wheel-test # If the previous steps have been completed, the testing wheel will contain deps' debug info
</pre>

Remark: in this scenario, do not build the dependencies with CI local build, as the deps source files should be inaccessible at the end of the build, what should make the deps debug info useless.

== How can I build a sanitized version of LuxCore? ==

It is possible to build a sanitized version of LuxCore, including <code>luxcoreui</code>, <code>luxcoreconsole</code>, <code>pyluxcore</code> and the wheels.
It just consists in setting the environment variable <code>LUX_SANITIZE</code> before the build:

<pre>export LUX_SANITIZE=1 # or whatever value you want</pre>

To come back to unsanitized build, just <code>unset LUX_SANITIZE</code>.

2 caveats:
* You'll need to export the following before running LuxCore:
<pre>export ASAN_OPTIONS=protect_shadow_gap=0</pre>
otherwise LuxCore will stop early with the following error message:
<pre>terminate called after throwing an instance of 'std::runtime_error'
what(): CUDA driver API error CUDA_ERROR_NOT_INITIALIZED
</pre>
* To run Blender with ASAN, see here: https://developer.blender.org/docs/handbook/tooling/asan/
This may help:
<pre>export ASAN_OPTIONS=check_initialization_order=0:protect_shadow_gap=0:verify_asan_link_order=0</pre>

== In Linux, I try to set an environment variable that should control LuxCore build, but it does not work ==

In Linux, for LuxCore build system to take them into account, the environment variables that control the build (LUX_BUILD_TYPE, LUX_SANITIZE...) should not only be set, but also exported:

<pre>export LUX_BUILD_TYPE=Debug # `set LUX_BUILD_TYPE=Debug` would be insufficient</pre>

== In gdb, how to debug one thread at a time? ==
<pre>set scheduler-locking step</pre>

Building LuxCoreRender - FAQ

2026-07-17T16:58:04Z

Howetuft: /* Is it possible to set-up a local-only, end-to-end, build chain? */

== Is it possible to set-up a local-only, end-to-end, build chain? ==

Yes it is, but for Linux only, at the moment, and starting with v2.11.
Also, important caveat: this kind of build is solely intended for development and tests. Do not use in production

* Step#1: Build dependencies locally

Use [[Building_LuxCoreRender#Local_Plain_Build|local plain build]] or [[Building_LuxCoreRender#Local_Continuous_Integration | local CI build]] of LuxCoreDeps

* Step#2: Inject local dependencies in LuxCore build
<pre>python -m build-system.luxmake.deps --local <path/to/deps> --release test</pre>

A few tips and caveats:
* You may want to get a clean situation before injecting local deps: <code>make clear</code>
* On Linux, <path/to/depth> should likely be <code>/tmp/conan-cache/luxcoredeps.zip</code> or <code>/tmp/luxcoredeps/artifact/1/luxcore-deps-ubuntu-latest/luxcore-deps-ubuntu-latest.zip</code>.
* Be careful about build type.If the build type of the deps is <code>Debug</code> and the build type of <code>pyluxcore</code> is <code>Release</code>, then the build system will recompile all dependences.

* Step#3: Build a testing wheel
<pre>make wheel-test</pre>

* Step#4: Inject testing wheel in Blender:

Use [[Developing_and_debugging_BlendLuxCore | BlendLuxHelper]]

For a debugging with luxcoreui only, one can also replace steps #3 & #4 by:

* Step#3bis: Build luxcoreui:
<pre>make luxcoreui</pre>

== Can I use <code>git bisect</code>? ==

Yes, if you need to find a faulty commit in <code>LuxCore</code>, you can use <code>git bisect</code>.

In that case, please note the correct verb to build LuxCoreRender at each step is
<pre>make clear && make deps && make</pre>

Caveat: this method only works for version >= v2.10.0

Example for Linux (please adapt to other contexts):

<pre>
# For bisecting, we recommend to build in Release type (shorter build time)
export LUX_BUILD_TYPE=Release

# Start git bisecting
git bisect start

# Define bounds
git bisect good samples-v2.10.0 # For instance
git bisect bad HEAD

# Build the app, test it and report status to git bisect
make clear && make deps && make # Build at this stage
./out/install/Release/bin/luxcoreui mytestscene/render.cfg
git bisect <good|bad|skip> # Depending on above test...

# Bisection loop
...

# At a certain point, the bisection stops and points at the faulty commit
# You can reset bisection
git bisect reset
</pre>

== Can I generate debug information for dependencies (LuxCoreDeps)? ==
Yes, it's possible, but only for local build.

In this context, the build type is controlled by <code>DEPS_BUILD_TYPE</code> environment variable, so set it to your target build type before building:

<pre>export DEPS_BUILD_TYPE=Debug</pre>

Then you will build the deps with [[Building_LuxCoreRender#Local_Plain_Build|local plain build]].

After having built dependencies in local, you may want to inject them in LuxCore build. This can be done with the following:

<pre>python -m build-system.luxmake.deps --local <path/to/deps> --release test --build-type=Debug</pre>

(this replaces <code>make deps</code>)

At this stage, you will be able to build LuxCore artifacts, embedding the debug information of dependencies, for instance:
<pre>
export LUX_BUILD_TYPE=Debug
make wheel-test # If the previous steps have been completed, the testing wheel will contain deps' debug info
</pre>

Remark: in this scenario, do not build the dependencies with CI local build, as the deps source files should be inaccessible at the end of the build, what should make the deps debug info useless.

== How can I build a sanitized version of LuxCore? ==

It is possible to build a sanitized version of LuxCore, including <code>luxcoreui</code>, <code>luxcoreconsole</code>, <code>pyluxcore</code> and the wheels.
It just consists in setting the environment variable <code>LUX_SANITIZE</code> before the build:

<pre>export LUX_SANITIZE=1 # or whatever value you want</pre>

To come back to unsanitized build, just <code>unset LUX_SANITIZE</code>.

2 caveats:
* You'll need to export the following before running LuxCore:
<pre>export ASAN_OPTIONS=protect_shadow_gap=0</pre>
otherwise LuxCore will stop early with the following error message:
<pre>terminate called after throwing an instance of 'std::runtime_error'
what(): CUDA driver API error CUDA_ERROR_NOT_INITIALIZED
</pre>
* To run Blender with ASAN, see here: https://developer.blender.org/docs/handbook/tooling/asan/
This may help:
<pre>export ASAN_OPTIONS=check_initialization_order=0:protect_shadow_gap=0:verify_asan_link_order=0</pre>

== In Linux, I try to set an environment variable that should control LuxCore build, but it does not work ==

In Linux, for LuxCore build system to take them into account, the environment variables that control the build (LUX_BUILD_TYPE, LUX_SANITIZE...) should not only be set, but also exported:

<pre>export LUX_BUILD_TYPE=Debug # `set LUX_BUILD_TYPE=Debug` would be insufficient</pre>

== In gdb, how to debug one thread at a time? ==
<pre>set scheduler-locking step</pre>

Building LuxCoreRender - FAQ

2026-07-16T22:52:08Z

Howetuft: /* Is it possible to set-up a local-only, end-to-end, build chain? */

Building LuxCoreRender - FAQ

2026-07-16T22:39:27Z

Howetuft: /* Is it possible to set-up a local-only, end-to-end, build chain? */

Building LuxCoreRender - FAQ

2026-07-16T21:42:54Z

Howetuft: /* Is it possible to set-up a local-only, end-to-end, build chain? */

Building LuxCoreRender - FAQ

2026-07-16T21:42:36Z

Howetuft: /* Is it possible to set-up a local-only, end-to-end, build chain? */

Building LuxCoreRender - FAQ

2026-06-27T04:18:09Z

Howetuft: /* Can I use git bisect? */

Building LuxCoreRender - FAQ

2026-06-11T04:47:40Z

Howetuft:

Building LuxCoreRender - FAQ

2026-06-07T21:12:39Z

Howetuft: /* How can I build a sanitized version of LuxCore? */

Building LuxCoreRender - FAQ

2026-06-07T20:53:27Z

Howetuft: /* How can I build a sanitized version of LuxCore? */

Building LuxCoreRender - FAQ

2026-06-07T20:49:47Z

Howetuft: /* How can I build a sanitized version of LuxCore? */

C++ Coding Guidelines

2026-06-07T11:12:06Z

Howetuft: /* Indentation */

Here are some guidelines for C++ Coding.

= Modern C++ =
We ask you to enforce the best practices of "modern" C++ programming, as defined by best experts:
https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines

True it is that legacy code may not always comply to those recommendations, but this is no reason for new code not to enforce them.

= Indentation & Line Return =
Indentation in LuxCore has historically used tabs rather than spaces, so we will continue to observe this in the future, even if it may not be the most practical... Massive replacement of tabs by spaces may obfuscate history, so not recommended. Thank you for your compliance.

On a different note, please avoid trailing spaces.

Line return should use LF (not CRLF). This is the convention for most of the existing files in the codebase and must absolutely be enforce in new files. By exception, however, there are still a few old files that use CRLF. Inside those ones, for minor changes, respect CRLF convention.

= Object naming =
LuxCore uses camelCase/CamelCase style.

Local symbols are named with camelCase
Global symbols are named with CamelCase.

= Boost =
Boost was used extensively in LuxCore, at a time when it was probably the only option for efficiently coding certain mechanisms (filepath, thread synchronization etc.).

Since v2.10, however, this is no longer the case, as LuxCore has been ported to C++20, which offers a standard library that can largely replace Boost, with a few exceptions.

Therefore please systematically prefer C++20 standard library over Boost whenever possible and limit Boost to cases where there is no other solution.

= Raw pointers =
LuxCore development was started before the advent of modern C++ (C++11 and higher) and logically conceals numerous raw pointers. However, raw pointers are quite risky, particularly in terms of memory leaks, dangling pointers, pointer aliasing etc., and should be avoided now, to the benefit of smart pointers.

= Dependencies =
Since version 2.10, a new dependency manager has been added (<code> LuxCoreDeps</code>). Other means to add dependencies are deprecated. In particular:
* do not embed external dependency source code
* do not use git submodules
* do not rely on precompiled binaries
Etc.

<code> LuxCoreDeps</code> builds dependencies for sources, for all platforms, based on Conan database of build recipes.
It guarantees reliability, portability and sustainability.
If you need to add a new dependency, please contact admin/dev team (on Discord, for instance, but also on Git or Forum).

= Code Documentation =
Please document your code: insert necessary information, comments etc., in the code in order for your peers to understand what you intend to do. "Your peers" encompass reviewers, other developers now and in the future etc.

LuxCore relies on Doxygen to generate code documentation: use Doxygen syntax to add the necessary information in your code.
Doxygen documentation can be built with <code> make doc </code>. After building, you'll find the documentation in <code> out/doc </code>.

Building LuxCoreRender - FAQ

2026-06-06T09:22:06Z

Howetuft: /* Can I use git bisect? */

Building LuxCoreRender

2026-06-02T11:37:15Z

Howetuft: /* Local dependency set */

This document describes the various processes involved in building LuxCoreRender, starting with version 2.10 “Back-on-track”.

LuxCoreRender's build system has been significantly modified for version 2.10. This document therefore renders obsolete all [[Building_LuxCoreRender_(legacy)|previous documents]] related to the compilation of older versions (<=2.9).

TL;DR If you are just interested in a quick, local (but platform limited) compilation of LuxCore C++ samples or Python wheels, you may want to jump directly to [[#Build LuxCore, Samples & Python Wheels | Build LuxCore, Samples & Python Wheels]].

= Audience =

This document is intended for:
* LuxCoreRender administrators in charge of releasing the various LuxCoreRender end-products;
* Developers wishing to contribute to the project;
* External package maintainers wishing to integrate all or part of LuxCoreRender into a distribution;

This document assumes that the reader is skilled in the following areas:
* C/C++ compilation
* [https://cmake.org/ cmake]
* [https://git-scm.com/ git]
* [https://docs.github.com/en/actions/writing-workflows Github Workflows]
* [https://packaging.python.org/en/latest/ Python Packaging], including [https://realpython.com/python-wheels/ Python Wheels format]

Familiarity with [https://conan.io/ Conan] dependency manager may also help.


This document is not intended for end-users without any knowledge about application building. Such users are invited to look for already compiled binaries on the official [https://luxcorerender.org/download/ Download] page.

= Build Targets =

== Synoptic ==
LuxCoreRender contains several build targets, below represented with dependency links:

{{#mermaid:
%%{
init: {
"theme": "forest",
"logLevel": "info",
"flowchart": {"curve": "basis"}
}
}%%

flowchart LR;

classDef TYPE font-weight:bold,font-size:1.1rem;
classDef TARGET font-weight:bold,font-size:0.9rem;

classDef LUXCOREDEPS fill:#ffe8ff,stroke:#9488af,font-weight:bold,font-size:1.1rem;
classDef TARGETDEPS fill:#e4d8ff,stroke:#9488af,font-weight:bold,font-size:0.9rem;

classDef LUXCORE fill:#bbceff,font-weight:bold,font-size:1.1rem,stroke:#999999;
classDef TARGETLUXCORE fill:#7799ee,font-weight:bold,font-size:0.9rem,stroke:#999999;

classDef SAMPLES fill:#ffffdd,font-weight:bold,font-size:1.1rem,stroke:#999999;
classDef TARGETSAMPLES fill:#eeeecc,font-weight:bold,font-size:0.9rem,stroke:#999999;

classDef NEUTRAL fill:#fafafa,font-weight:bold,font-size:1.1rem,stroke:#999999;
classDef TARGETNEUTRAL fill:#eeeeee,font-weight:bold,font-size:0.9rem,stroke:#999999;

classDef EXTDEP fill:#00000000,stroke:#00000000;

subgraph Dependencies[External Dependencies]
deps(LuxCore Dependencies)
end

class Dependencies LUXCOREDEPS;
class deps TARGETDEPS;

subgraph LuxCore
lux(luxcore.so/.dll)
luxa(luxcore.a)
end
class LuxCore LUXCORE;
class lux TARGETLUXCORE;
class luxa TARGETLUXCORE;

subgraph Python_Wheels[Python Wheels]
pylux(pyluxcore.so/.dll)
wheels(LuxCore Python Wheels)
end
class Python_Wheels TYPE;
class pylux TARGET;
class wheels TARGET;

subgraph Samples
luxcoreui(luxcoreui)
luxcoreconsole(luxcoreconsole)
end
class Samples SAMPLES;
class luxcoreui TARGETSAMPLES;
class luxcoreconsole TARGETSAMPLES;

subgraph PyLuxCoreTools
pyluxcon(pyluxcoreconsole)
pyluxothers(...)
end
class PyLuxCoreTools NEUTRAL;
class pyluxcon TARGETNEUTRAL;
class pyluxothers TARGETNEUTRAL;

subgraph Plugins[Python Plugins]
blc(BlendLuxCore)
otherplugins(...)
end
class blc TARGETNEUTRAL;
class otherplugins TARGETNEUTRAL;

class Plugins NEUTRAL;

%% Warning: order matters
deps-->lux
deps-->luxa
deps-->luxcoreui
deps-->luxcoreconsole

luxa--->pylux
lux-->luxcoreui
lux-->luxcoreconsole
deps-->pylux

pylux-->wheels
wheels-. runtime .->blc
wheels-. runtime .->otherplugins

wheels-. runtime .->pyluxcon
wheels-. runtime .->pyluxothers

Python:::EXTDEP-->pylux

%% Mermaid version: 8.14.0
%% https://github.com/mermaid-js/mermaid/blob/8.14.0/src/defaultConfig.js

}}

{| class="wikitable" style="margin:auto"
|-
! Target !! Source Repository !! Content
|-
| External Dependencies|| [https://github.com/LuxCoreRender/LuxCoreDeps <code>LuxCoreDeps</code>] || A bundled Conan cache populated with LuxCoreRender external dependency binaries, built from sources. Please refer to [https://github.com/LuxCoreRender/LuxCoreDeps/blob/main/README.md LuxCoreDeps README] for more information.
|-
| LuxCore || [https://github.com/LuxCoreRender/LuxCore <code>LuxCore</code>] || LuxCore core binaries, in the form of static and shared libraries: luxcore.so, luxcore_static.lib, luxcore.dll etc.
|-
| Samples|| [https://github.com/LuxCoreRender/LuxCore <code>LuxCore</code>] || Sample C++ programs, illustrating luxcore use, namely <code>luxcoreconsole</code> and <code>luxcoreui</code>
|-
| Python Wheels|| [https://github.com/LuxCoreRender/LuxCore <code>LuxCore</code>] || Python bindings of core binaries, in the form of Python wheels (1 per pair Platform/Python version). As a byproduct, a Pythonized version of LuxCore shared library is also built (pyluxcore.so).
|-
| Python Plugins|| [https://github.com/LuxCoreRender/BlendLuxCore <code>BlendLuxCore</code>] etc. || Plugins to expose LuxCore in various external applications, notably Blender. Written in Python and relying on Python Wheels as runtime dependency.
|-
| PyLuxCoreTools|| [https://github.com/LuxCoreRender/LuxCore <code>LuxCore</code>] || Python LuxCore Tools: set of command line tools based on pyluxcore, written in Python.
|}

== Targeted platforms ==

LuxCoreRender aims at being available on the following 4 platforms:
* Linux (glibc 2.28+)
* Windows
* MacOS Intel (>=10.15)
* MacOS Arm (>=12.0)

For Python-related targets, LuxCoreRender aims at being declined for [https://devguide.python.org/versions all Python versions supported at a given time].

= Workflow Types =

We distinguish between two types of build workflows:
* Developer workflows
* Publisher workflows

''[[#Developer Workflows | Developer workflows]]'' are designed for development, debugging and test steps.

Their purpose is to allow development and verify the code is ready for publication.

''[[#Publisher Workflows | Publisher workflows]]'' are designed to be used by LuxCoreRender administrators to publish a new release of one or more LuxCoreRender components.

They exclusively take place in a CI/CD Github pipeline.

These workflows are not designed for debugging or testing the underlying code. Execution of these workflows assumes that the development phase has been correctly completed and the underlying code is ready for final build and release. See [[#Developer Workflows | Developer Workflows]] to learn how to get code ready for final build.

Running these workflows require users to be granted of extended rights on LuxCoreRender repositories.

= Developer Workflows =

== Prerequisites ==

Tools

You will need several build tools installed and referenced in the PATH.

First, ensure you have a suitable toolchain:

{| class="wikitable" style="margin:auto"
|-
! OS !! Compiler !! Minimal version
|-
| Windows || MSVC || 194x latest version
|-
| Linux|| gcc || 14
|-
| MacOS Intel|| XCode + llvm + libomp || llvm >= 20 (<code>brew install llvm && brew install libomp</code>)
|-
| MacOS Arm || XCode + llvm + libomp || llvm >= 20 (<code>brew install llvm && brew install libomp</code>)
|}

''Toolchain compliance is a very sensitive condition for a successful build. Before filing any claim, please check that your toolchain complies with the above requirements.''

Then ensure the following software is also installed and available in your PATH:

* [https://git-scm.com/ Git]
* [https://cli.github.com/ Github CLI] (optional but recommended - for dependency signature checking)
* [https://www.python.org/ Python 3] - any [https://devguide.python.org/versions/ currently supported version]
* [https://conan.io Conan] latest version (pip install conan)
* [https://github.com/pypa/wheel/tree/main Wheel] latest version (pip install wheel)
* [https://cmake.org/ CMake] >= 3.29
* [https://github.com/nektos/act nektos/act] (optional but recommended - for local build based on Github workflows)
* [https://pypi.org/project/repairwheel repairwheel] (optional but recommended - for local build of test wheels)

Platform specifics:
* For Windows, ensure the command line is configured for building (<code>vcvarsall.bat</code>).
* For Linux, you'll need <code>pkgconfig</code> in addition.
* For MacOS, you'll need to ensure CC and CXX point to LLVM clang/clang++

Accounts

A ''Github account'' is mandatory for LuxCore development.

Following accounts are also recommended, in order to get in touch with LuxCore community:
* [https://forums.luxcorerender.org/ LuxCoreRender Forums]
* [https://discord.gg/chPGsKV LuxCoreRender Discord channel]

== General Developer Workflow ==

To compile and verify LuxCore component modifications in development process, there are 3 stages:
* Local plain build: only run build system (cmake) on developer computer
* Local Continuous Integration build: run full Continuous Integration workflow on developer computer
* Server Continuous Integration build: run full Continuous Integration workflow on server

Local plain build is generally faster than other builds and does not require to commit changes beforehand. Plain build installs a minimal build configuration (dependencies), but heavily relies on computer build environment for the rest (build tools, system libraries etc.). As a counterpart, it builds only for the platform where it is executed and can be significantly altered by local conditions (build tools local versions, dependency local versions etc.), thus not fully guaranteeing that final publish workflow will succeed.

LocalCI is generally faster than Server build, but slower than local plain build. CI workflow installs a complete build environment (compilers, sdk, build tools, containers, dependencies etc.) before running build system. It does not require to commit changes beforehand. However, it builds only for the platform where it is executed, thus not fully guaranteeing that final publish workflow will succeed.

Server CI, if successful, should guarantee success when publishing, as it occurs in conditions similar to release workflow (all platforms, complete build environment). As a counterpart, it is generally significantly slower than local builds and also implies to commit and push changes beforehand, even if the code is in unstable state.

The recommended workflow thus strives to make the most of all stages:

{{#mermaid:

%%{ init: {
'theme': 'neutral',
'flowchart': { 'curve': 'monotoneX' }
}
}%%

flowchart TD;

fork(Fork Source repository in your own Github space)
clone("Clone your fork locally<code>git clone...</code>")
devel(Make modifications in your local fork)
localBuild("Run local plain build<code>cmake</code>, <code>make</code>...")
localCI("Run local CI<code>act</code>")
git("Commit, Rebase & Push<code>git ...</code>")
serverCI(Run server CI<code>Github workflow</code>)
PR(PR your changes to Source repository)

fork-->clone
clone-->devel
devel-->localBuild
localBuild-->localCI
localCI-- "Success(including debug & tests)" -->git
git-->serverCI
serverCI-- Success -->PR

localBuild & localCI & serverCI ----> |Failure| devel

classDef BUILD fill:#acc,stroke-width:4px;
class localBuild BUILD;
class localCI BUILD;
class serverCI BUILD;

}}

This is the common process between all components. Each step will then be adapted to each component, as explained below.

Comments:
* Running local CI relies on [https://github.com/nektos/act <code>nektos/act</code>]
* Rebase must be made against upstream directory (<code>git pull --rebase upstream <branch></code>)before pushing
* Push must be made towards developer own fork. Caveat: do not try to push directly to upstream

== Build External Dependencies ==

=== Local Plain Build ===
==== Caveats ====
Dependency local plain build is possible but:
* Local plain build IS NOT THE RECOMMENDED BUILD FOR FINAL DEPS. This build is solely intended for intermediary development and debugging. No support will be provided when used out-of-scope.
* Local plain build has only been tested on Linux, with gcc >=14. For other platforms, adaptations should be necessary (contributions welcome).
* Local plain build is much impacted by local particulars (local compiler version, dependencies already in cache or in system dirs etc.) and therefore does not guarantee further success for other builds.

==== Prerequisites ====
In addition with general [[#Prerequisites_2 | Prerequisites]], you'll need the OneAPI ISPC compiler.

==== Conan cache interaction ====

The build relies on the local Conan cache, which will be modified by the process. You may want to make a copy beforehand.

In some scenarios, you may also want to reset your Conan cache (warning: may remove files unrelated to LuxCoreDeps):
<pre>conan remove -c "*" # Be careful: may remove packages unrelated to LuxCoreDeps!</pre>

==== Run ====

To run a plain local build, run the following statements in a console, from the root of LuxCoreDeps repository:

<pre>
export RUNNER_OS=<os>
export RUNNER_ARCH=<arch>

export LUXDEPS_VERSION=test
export GCC_VERSION=14 # Note: even for gcc > 14
export WORKSPACE=.
export CXX_VERSION=20
export CMAKE_POLICY_VERSION_MINIMUM=3.25
export DEPS_BUILD_TYPE=Release # Or Debug/RelWithDebInfo/MinSizeRel, as needed
export cache_dir

./run_conan.sh
</pre>

with <code>RUNNER_OS</code>, <code>RUNNER_ARCH</code> in:
* <code>Linux</code> / <code>X64</code>
* <code>Windows</code> / <code>X64</code>
* <code>macOS</code> / <code>X64</code>
* <code>macOS</code> / <code>ARM64</code>
reflecting your build platform.

No detection is made (compiler, OS, arch...) . You'll have to do it on your own and set environment variables accordingly.

==== Cleaning ====

Conan will produce a bunch of scripts in the root of LuxCoreDeps repo. You can clean them with the following:
<pre> ./utils/clean-conan-files.sh </pre>

=== Local Continuous Integration ===

Run <code>act</code> on workflows located in <code>.github/workflows</code> folder, for instance <code>.github/workflows/build.yml</code> workflow.

For more convenience, a wrapper script is also provided in <code>LuxCoreDeps</code> repository (Linux only, at the moment): <pre>./utils/local-CI-build.sh</pre>

=== Server Continuous Integration ===

This process relies on the following Github workflow: [https://github.com/LuxCoreRender/LuxCoreDeps/actions/workflows/checker.yml <code>LuxCore Dependency Checker</code>].
Important points:
* Your changes must have been committed and pushed to repository before.
* The Checker workflow is actually also triggered on push event, so you may not have to run it by yourself

If build succeeds, you will find the expected outputs in Artifacts section of the action run.

== Build LuxCore, Samples & Python Wheels ==

=== Local Plain Build ===

==== Prerequisites ====

First, we will assume you have correctly completed the [[#Prerequisites_2 | Prerequisites]].

Second, we will also assume you've already git-cloned LuxCore on your local machine, opened a terminal, changed directory to LuxCore folder and git-checked out the branch that you want to build (+ for Windows: initialized build environment with <code>vcvarsall.bat</code>)

==== Basic build ====

Our build system internally relies on <code>cmake</code> but, for more convenience, everything has been wrapped into <code>make</code>-like statements.

So, to build LuxCore, one just have to enter the following magic words:
<pre>
make deps
make
</pre>

This should retrieve and install LuxCore dependencies, configure the project and run the build. That's all!

For subsequent builds, if no modification have been made to dependencies, you'll just have to re-enter: <pre>make</pre>

==== Specific targets ====

If you want to target a specific component, you can replace the above plain <code>make</code> by one of the following verbs:
<pre>make luxcore</pre>
<pre>make pyluxcore</pre>
<pre>make luxcoreui</pre>
<pre>make luxcoreconsole</pre>

Starting from version 2.11, this method can build a "test wheel". This is a simplified wheel, only for current platform and current Python version, for testing purpose. The test wheel is particularly useful for developing/debugging LuxCore/BlendLuxCore integration.
The verb is:
<pre>make wheel-test</pre>

You can also build Doxygen documentation with the following statement:
<pre>make doc</pre>

==== Build type ====

By default, this method builds a release version, striped from all symbols. If you want to build a debug version, enter the following before any <code>make ...</code> command:

<pre>export LUX_BUILD_TYPE=Debug</pre>

==== Local dependency set ====

It is possible to use a local dependency set, rather than relying on automatic downloading. It is especially useful for developing/debugging of LuxCoreDeps/LuxCore integration. In this case, one can replace the <code>make deps</code> statement by the following one:

<pre>
python -m build-system.luxmake.deps --local <path/to/local/deps> --release <release>
</pre>

Nota: <code><release></code> is the release tag used by your local dependency set. If you build this set locally, it should likely be <code>test</code>.

Nota 2: if you built with debug symbol, you'll need to add <code>--build-type=Debug</code> to the above statement.

==== Cleaning ====

You can remove build outputs with one of the following statement:
<pre>make clean</pre>
or
<pre>make clear</pre>
The former will remove build files, however preserving dependencies.
The latter will remove everything and will require to reinstall dependencies (<code>make deps</code>).

=== Local Continuous Integration ===

This method is complementary to Local plain build, with the following additional capabilities:
* test the LuxCore build in an environment close to the release environment (manylinux container, for instance)
* can build wheels
* debug any changes made to the build workflow

It consists in running Github workflows locally, via <code>act</code>. Github workflows are located in <code>.github/workflows</code> folder.

<code>act</code> invokation can be made on command line but, for convenience, a wrapper script is provided (for Linux): <pre>./build-helpers/debug/debug_wheels.sh</pre>

Caveat: this build can produce wheels, but only for the host platform (no cross-compiling).

=== Server Continuous Integration ===

The process is nearly the same as publisher build, but the release steps are skipped. For that purpose, another Github workflow has to be executed: [https://github.com/LuxCoreRender/LuxCore/actions/workflows/wheel-builder.yml <code>LuxCore Python Wheels Builder</code>].

Please note that your changes must have been committed to repository before running the workflow.

If build succeeds, you will find the expected outputs in Artifacts section of the action run.

= Publisher Workflows =

== Prerequisites ==

For these workflows, a Github account is required, with extended rights on the source repositories.

== General Workflow ==

The general workflow for publishing is in 3 parts:

{{#mermaid:

%%{ init: {
'theme': 'neutral',
'flowchart': { 'curve': 'monotoneX' }
}
}%%
flowchart TD;
subgraph Build["<center>BUILD & RELEASE DRAFT (Run Releaser workflow)</center>"]
padBuild(" "):::INVISIBLE
repo("Go to <code>[Source repository]</code> on Github and open <code>Actions menu</code>")
select("Select <code>[Releaser workflow]</code>")
runwf(Click on <code>Run workflow</code> button, in the upper-right corner)
branch(Select <code>Branch</code> in drop-down menu)
options(Set workflow options)
validate(Click <code>Run workflow</code>)
wait(Wait for build to complete)
end

subgraph Release["<center>MAKE FINAL RELEASE(Switch release to final status)</center>"]
padRelease(" "):::INVISIBLE
release("Open <code>[Release folder]</code>, find the newly-built release (in Draft mode) and edit it")
complete(Add relevant information: change log, comments on version etc.)
dedraft(Unset <code>Draft</code> checkbox)
update(Click <code>Publish release</code>/<code>Update release</code> to finalize)
end

subgraph Deploy["<center>PUBLISH(Run Publisher workflow)</center>"]
padDeploy(" ")
repoDeploy("Go to <code>[Source repository]</code> on Github and open <code>[Actions menu]</code>")
selectDeploy("Select <code>[Publisher workflow]</code>")
runwfDeploy("Click on <code>Run workflow</code> drop-down button, in the upper-right corner")
choiceDeploy("Select <code>Branch</code>, set the <code>Tag to publish</code> and uncheck <code>Publish on Pypi Test</code> if needed")
validateDeploy("Click on <code>Run workflow</code> button")
waitDeploy("Wait for deployment to complete")
end

padBuild---repo
repo-->select
select-->runwf
runwf-->branch
branch-->options
options-->validate
validate-->wait:::WAIT
linkStyle 0 stroke:#fff,stroke-width:0px,color:blue;

padRelease---release
release-->complete
complete-->dedraft
dedraft-->update
linkStyle 7 stroke:#fff,stroke-width:0px,color:blue;

padDeploy:::INVISIBLE---repoDeploy
repoDeploy-->selectDeploy
selectDeploy-->runwfDeploy
runwfDeploy-->choiceDeploy
choiceDeploy-->validateDeploy
validateDeploy-->waitDeploy:::WAIT
linkStyle 11 stroke:#fff,color:blue,stroke-width:0px;

Build-- if success -->Release
Release-- if success & if needed -->Deploy

classDef WAIT fill:#ddd;
classDef DEPS fill:#e4d8ff,stroke:#9488af;
classDef INVISIBLE fill:#ffffffff,stroke:#ffffffff,stroke-width:0px,font-color:#ffffffff;
classDef OPTIONAL stroke-dasharray: 5 5;

class Deploy OPTIONAL;

%% Note: padXXX is a poor hack to create a top-margin in subgraph...
}}

A few comments:
* <code>[bracketed tokens]</code> refer to data specific to each component, which will be detailed below.
* Publish part is optional, it will depends on the target
* ''Caveat: if you provide an already-existing release version number during the process, the workflow will replace the existing release with the newly-built one. This can be what you expected... or not. Be cautious.''

== Per-target details ==

=== External Dependencies ===

* Source repository: [https://github.com/LuxCoreRender/LuxCoreDeps <code>LuxCoreRender/LuxCoreDeps</code>]
* Releaser workflow: [https://github.com/LuxCoreRender/LuxCoreDeps/actions/workflows/release.yml <code>LuxCore Dependency Releaser</code>]
* Release folder: [https://github.com/LuxCoreRender/LuxCoreDeps/releases <code>Releases</code>]
* Publisher workflow: ∅

As a byproduct, External Dependencies are not intended to be deployed, so no Publisher workflow is provided.

=== Python Wheels ===

As far as wheels are concerned, in addition to building them, it is also necessary to upload them to [https://pypi.org/ PyPi] ("publish" them), so that they are available for [https://pypi.org/project/pip pip] installation.

* Source repository: [https://github.com/LuxCoreRender/LuxCore <code>LuxCoreRender/LuxCore</code>]
* Releaser workflow: [https://github.com/LuxCoreRender/LuxCore/actions/workflows/wheel-releaser.yml <code>LuxCore Wheels Releaser</code>]
* Release folder: [https://github.com/LuxCoreRender/LuxCore/releases <code>Releases</code>]
* Publisher workflow: [https://github.com/LuxCoreRender/LuxCore/actions/workflows/wheel-publisher.yml <code>LuxCore Wheels Publisher</code>]

''Prerequisite: you must have released a compatible version of External Dependencies (LuxCoreDeps) before building Python Wheels.''

=== Samples ===

As we plan to replace Samples by equivalent Python tools and thus deprecate them, the workflow has been limited to the Release part (no publish).

* Source repository: [https://github.com/LuxCoreRender/LuxCore <code>LuxCoreRender/LuxCore</code>]
* Releaser workflow: [https://github.com/LuxCoreRender/LuxCore/actions/workflows/sample-releaser.yml <code>LuxCore Samples Releaser</code>]
* Release folder: [https://github.com/LuxCoreRender/LuxCore/releases <code>Releases</code>]
* Publisher workflow: ∅

=== BlendLuxCore ===

TODO

= Version Management =

== Semantic Versioning ==

Starting for LuxCore version 2.10.0, we require that LuxCoreRender applies [https://semver.org/ Semantic Versioning]. Please strictly enforce this rule when incrementing version numbers.

Remark: component versions does not have to be synced. For instance, in strict application of the standard, the newly created LuxCoreDeps will start at 1.0.0, while at the same time LuxCore is already at 2.10.0

== Dependency Version pointer ==

To make LuxCore know which version of dependencies it must be built against, we use a pointer.

This pointer is stored in the file <code>build-helpers/build-settings.json</code>, under the path <code>Dependencies/release</code>.

Make sure you keep it up-to-date when you upgrade LuxCore components.

Building LuxCoreRender

2026-06-02T11:35:39Z

Howetuft: /* Run */

This document describes the various processes involved in building LuxCoreRender, starting with version 2.10 “Back-on-track”.

LuxCoreRender's build system has been significantly modified for version 2.10. This document therefore renders obsolete all [[Building_LuxCoreRender_(legacy)|previous documents]] related to the compilation of older versions (<=2.9).

TL;DR If you are just interested in a quick, local (but platform limited) compilation of LuxCore C++ samples or Python wheels, you may want to jump directly to [[#Build LuxCore, Samples & Python Wheels | Build LuxCore, Samples & Python Wheels]].

= Audience =

This document is intended for:
* LuxCoreRender administrators in charge of releasing the various LuxCoreRender end-products;
* Developers wishing to contribute to the project;
* External package maintainers wishing to integrate all or part of LuxCoreRender into a distribution;

This document assumes that the reader is skilled in the following areas:
* C/C++ compilation
* [https://cmake.org/ cmake]
* [https://git-scm.com/ git]
* [https://docs.github.com/en/actions/writing-workflows Github Workflows]
* [https://packaging.python.org/en/latest/ Python Packaging], including [https://realpython.com/python-wheels/ Python Wheels format]

Familiarity with [https://conan.io/ Conan] dependency manager may also help.


This document is not intended for end-users without any knowledge about application building. Such users are invited to look for already compiled binaries on the official [https://luxcorerender.org/download/ Download] page.

= Build Targets =

== Synoptic ==
LuxCoreRender contains several build targets, below represented with dependency links:

{{#mermaid:
%%{
init: {
"theme": "forest",
"logLevel": "info",
"flowchart": {"curve": "basis"}
}
}%%

flowchart LR;

classDef TYPE font-weight:bold,font-size:1.1rem;
classDef TARGET font-weight:bold,font-size:0.9rem;

classDef LUXCOREDEPS fill:#ffe8ff,stroke:#9488af,font-weight:bold,font-size:1.1rem;
classDef TARGETDEPS fill:#e4d8ff,stroke:#9488af,font-weight:bold,font-size:0.9rem;

classDef LUXCORE fill:#bbceff,font-weight:bold,font-size:1.1rem,stroke:#999999;
classDef TARGETLUXCORE fill:#7799ee,font-weight:bold,font-size:0.9rem,stroke:#999999;

classDef SAMPLES fill:#ffffdd,font-weight:bold,font-size:1.1rem,stroke:#999999;
classDef TARGETSAMPLES fill:#eeeecc,font-weight:bold,font-size:0.9rem,stroke:#999999;

classDef NEUTRAL fill:#fafafa,font-weight:bold,font-size:1.1rem,stroke:#999999;
classDef TARGETNEUTRAL fill:#eeeeee,font-weight:bold,font-size:0.9rem,stroke:#999999;

classDef EXTDEP fill:#00000000,stroke:#00000000;

subgraph Dependencies[External Dependencies]
deps(LuxCore Dependencies)
end

class Dependencies LUXCOREDEPS;
class deps TARGETDEPS;

subgraph LuxCore
lux(luxcore.so/.dll)
luxa(luxcore.a)
end
class LuxCore LUXCORE;
class lux TARGETLUXCORE;
class luxa TARGETLUXCORE;

subgraph Python_Wheels[Python Wheels]
pylux(pyluxcore.so/.dll)
wheels(LuxCore Python Wheels)
end
class Python_Wheels TYPE;
class pylux TARGET;
class wheels TARGET;

subgraph Samples
luxcoreui(luxcoreui)
luxcoreconsole(luxcoreconsole)
end
class Samples SAMPLES;
class luxcoreui TARGETSAMPLES;
class luxcoreconsole TARGETSAMPLES;

subgraph PyLuxCoreTools
pyluxcon(pyluxcoreconsole)
pyluxothers(...)
end
class PyLuxCoreTools NEUTRAL;
class pyluxcon TARGETNEUTRAL;
class pyluxothers TARGETNEUTRAL;

subgraph Plugins[Python Plugins]
blc(BlendLuxCore)
otherplugins(...)
end
class blc TARGETNEUTRAL;
class otherplugins TARGETNEUTRAL;

class Plugins NEUTRAL;

%% Warning: order matters
deps-->lux
deps-->luxa
deps-->luxcoreui
deps-->luxcoreconsole

luxa--->pylux
lux-->luxcoreui
lux-->luxcoreconsole
deps-->pylux

pylux-->wheels
wheels-. runtime .->blc
wheels-. runtime .->otherplugins

wheels-. runtime .->pyluxcon
wheels-. runtime .->pyluxothers

Python:::EXTDEP-->pylux

%% Mermaid version: 8.14.0
%% https://github.com/mermaid-js/mermaid/blob/8.14.0/src/defaultConfig.js

}}

{| class="wikitable" style="margin:auto"
|-
! Target !! Source Repository !! Content
|-
| External Dependencies|| [https://github.com/LuxCoreRender/LuxCoreDeps <code>LuxCoreDeps</code>] || A bundled Conan cache populated with LuxCoreRender external dependency binaries, built from sources. Please refer to [https://github.com/LuxCoreRender/LuxCoreDeps/blob/main/README.md LuxCoreDeps README] for more information.
|-
| LuxCore || [https://github.com/LuxCoreRender/LuxCore <code>LuxCore</code>] || LuxCore core binaries, in the form of static and shared libraries: luxcore.so, luxcore_static.lib, luxcore.dll etc.
|-
| Samples|| [https://github.com/LuxCoreRender/LuxCore <code>LuxCore</code>] || Sample C++ programs, illustrating luxcore use, namely <code>luxcoreconsole</code> and <code>luxcoreui</code>
|-
| Python Wheels|| [https://github.com/LuxCoreRender/LuxCore <code>LuxCore</code>] || Python bindings of core binaries, in the form of Python wheels (1 per pair Platform/Python version). As a byproduct, a Pythonized version of LuxCore shared library is also built (pyluxcore.so).
|-
| Python Plugins|| [https://github.com/LuxCoreRender/BlendLuxCore <code>BlendLuxCore</code>] etc. || Plugins to expose LuxCore in various external applications, notably Blender. Written in Python and relying on Python Wheels as runtime dependency.
|-
| PyLuxCoreTools|| [https://github.com/LuxCoreRender/LuxCore <code>LuxCore</code>] || Python LuxCore Tools: set of command line tools based on pyluxcore, written in Python.
|}

== Targeted platforms ==

LuxCoreRender aims at being available on the following 4 platforms:
* Linux (glibc 2.28+)
* Windows
* MacOS Intel (>=10.15)
* MacOS Arm (>=12.0)

For Python-related targets, LuxCoreRender aims at being declined for [https://devguide.python.org/versions all Python versions supported at a given time].

= Workflow Types =

We distinguish between two types of build workflows:
* Developer workflows
* Publisher workflows

''[[#Developer Workflows | Developer workflows]]'' are designed for development, debugging and test steps.

Their purpose is to allow development and verify the code is ready for publication.

''[[#Publisher Workflows | Publisher workflows]]'' are designed to be used by LuxCoreRender administrators to publish a new release of one or more LuxCoreRender components.

They exclusively take place in a CI/CD Github pipeline.

These workflows are not designed for debugging or testing the underlying code. Execution of these workflows assumes that the development phase has been correctly completed and the underlying code is ready for final build and release. See [[#Developer Workflows | Developer Workflows]] to learn how to get code ready for final build.

Running these workflows require users to be granted of extended rights on LuxCoreRender repositories.

= Developer Workflows =

== Prerequisites ==

Tools

You will need several build tools installed and referenced in the PATH.

First, ensure you have a suitable toolchain:

{| class="wikitable" style="margin:auto"
|-
! OS !! Compiler !! Minimal version
|-
| Windows || MSVC || 194x latest version
|-
| Linux|| gcc || 14
|-
| MacOS Intel|| XCode + llvm + libomp || llvm >= 20 (<code>brew install llvm && brew install libomp</code>)
|-
| MacOS Arm || XCode + llvm + libomp || llvm >= 20 (<code>brew install llvm && brew install libomp</code>)
|}

''Toolchain compliance is a very sensitive condition for a successful build. Before filing any claim, please check that your toolchain complies with the above requirements.''

Then ensure the following software is also installed and available in your PATH:

* [https://git-scm.com/ Git]
* [https://cli.github.com/ Github CLI] (optional but recommended - for dependency signature checking)
* [https://www.python.org/ Python 3] - any [https://devguide.python.org/versions/ currently supported version]
* [https://conan.io Conan] latest version (pip install conan)
* [https://github.com/pypa/wheel/tree/main Wheel] latest version (pip install wheel)
* [https://cmake.org/ CMake] >= 3.29
* [https://github.com/nektos/act nektos/act] (optional but recommended - for local build based on Github workflows)
* [https://pypi.org/project/repairwheel repairwheel] (optional but recommended - for local build of test wheels)

Platform specifics:
* For Windows, ensure the command line is configured for building (<code>vcvarsall.bat</code>).
* For Linux, you'll need <code>pkgconfig</code> in addition.
* For MacOS, you'll need to ensure CC and CXX point to LLVM clang/clang++

Accounts

A ''Github account'' is mandatory for LuxCore development.

Following accounts are also recommended, in order to get in touch with LuxCore community:
* [https://forums.luxcorerender.org/ LuxCoreRender Forums]
* [https://discord.gg/chPGsKV LuxCoreRender Discord channel]

== General Developer Workflow ==

To compile and verify LuxCore component modifications in development process, there are 3 stages:
* Local plain build: only run build system (cmake) on developer computer
* Local Continuous Integration build: run full Continuous Integration workflow on developer computer
* Server Continuous Integration build: run full Continuous Integration workflow on server

Local plain build is generally faster than other builds and does not require to commit changes beforehand. Plain build installs a minimal build configuration (dependencies), but heavily relies on computer build environment for the rest (build tools, system libraries etc.). As a counterpart, it builds only for the platform where it is executed and can be significantly altered by local conditions (build tools local versions, dependency local versions etc.), thus not fully guaranteeing that final publish workflow will succeed.

LocalCI is generally faster than Server build, but slower than local plain build. CI workflow installs a complete build environment (compilers, sdk, build tools, containers, dependencies etc.) before running build system. It does not require to commit changes beforehand. However, it builds only for the platform where it is executed, thus not fully guaranteeing that final publish workflow will succeed.

Server CI, if successful, should guarantee success when publishing, as it occurs in conditions similar to release workflow (all platforms, complete build environment). As a counterpart, it is generally significantly slower than local builds and also implies to commit and push changes beforehand, even if the code is in unstable state.

The recommended workflow thus strives to make the most of all stages:

{{#mermaid:

%%{ init: {
'theme': 'neutral',
'flowchart': { 'curve': 'monotoneX' }
}
}%%

flowchart TD;

fork(Fork Source repository in your own Github space)
clone("Clone your fork locally<code>git clone...</code>")
devel(Make modifications in your local fork)
localBuild("Run local plain build<code>cmake</code>, <code>make</code>...")
localCI("Run local CI<code>act</code>")
git("Commit, Rebase & Push<code>git ...</code>")
serverCI(Run server CI<code>Github workflow</code>)
PR(PR your changes to Source repository)

fork-->clone
clone-->devel
devel-->localBuild
localBuild-->localCI
localCI-- "Success(including debug & tests)" -->git
git-->serverCI
serverCI-- Success -->PR

localBuild & localCI & serverCI ----> |Failure| devel

classDef BUILD fill:#acc,stroke-width:4px;
class localBuild BUILD;
class localCI BUILD;
class serverCI BUILD;

}}

This is the common process between all components. Each step will then be adapted to each component, as explained below.

Comments:
* Running local CI relies on [https://github.com/nektos/act <code>nektos/act</code>]
* Rebase must be made against upstream directory (<code>git pull --rebase upstream <branch></code>)before pushing
* Push must be made towards developer own fork. Caveat: do not try to push directly to upstream

== Build External Dependencies ==

=== Local Plain Build ===
==== Caveats ====
Dependency local plain build is possible but:
* Local plain build IS NOT THE RECOMMENDED BUILD FOR FINAL DEPS. This build is solely intended for intermediary development and debugging. No support will be provided when used out-of-scope.
* Local plain build has only been tested on Linux, with gcc >=14. For other platforms, adaptations should be necessary (contributions welcome).
* Local plain build is much impacted by local particulars (local compiler version, dependencies already in cache or in system dirs etc.) and therefore does not guarantee further success for other builds.

==== Prerequisites ====
In addition with general [[#Prerequisites_2 | Prerequisites]], you'll need the OneAPI ISPC compiler.

==== Conan cache interaction ====

The build relies on the local Conan cache, which will be modified by the process. You may want to make a copy beforehand.

In some scenarios, you may also want to reset your Conan cache (warning: may remove files unrelated to LuxCoreDeps):
<pre>conan remove -c "*" # Be careful: may remove packages unrelated to LuxCoreDeps!</pre>

==== Run ====

To run a plain local build, run the following statements in a console, from the root of LuxCoreDeps repository:

<pre>
export RUNNER_OS=<os>
export RUNNER_ARCH=<arch>

export LUXDEPS_VERSION=test
export GCC_VERSION=14 # Note: even for gcc > 14
export WORKSPACE=.
export CXX_VERSION=20
export CMAKE_POLICY_VERSION_MINIMUM=3.25
export DEPS_BUILD_TYPE=Release # Or Debug/RelWithDebInfo/MinSizeRel, as needed
export cache_dir

./run_conan.sh
</pre>

with <code>RUNNER_OS</code>, <code>RUNNER_ARCH</code> in:
* <code>Linux</code> / <code>X64</code>
* <code>Windows</code> / <code>X64</code>
* <code>macOS</code> / <code>X64</code>
* <code>macOS</code> / <code>ARM64</code>
reflecting your build platform.

No detection is made (compiler, OS, arch...) . You'll have to do it on your own and set environment variables accordingly.

==== Cleaning ====

Conan will produce a bunch of scripts in the root of LuxCoreDeps repo. You can clean them with the following:
<pre> ./utils/clean-conan-files.sh </pre>

=== Local Continuous Integration ===

Run <code>act</code> on workflows located in <code>.github/workflows</code> folder, for instance <code>.github/workflows/build.yml</code> workflow.

For more convenience, a wrapper script is also provided in <code>LuxCoreDeps</code> repository (Linux only, at the moment): <pre>./utils/local-CI-build.sh</pre>

=== Server Continuous Integration ===

This process relies on the following Github workflow: [https://github.com/LuxCoreRender/LuxCoreDeps/actions/workflows/checker.yml <code>LuxCore Dependency Checker</code>].
Important points:
* Your changes must have been committed and pushed to repository before.
* The Checker workflow is actually also triggered on push event, so you may not have to run it by yourself

If build succeeds, you will find the expected outputs in Artifacts section of the action run.

== Build LuxCore, Samples & Python Wheels ==

=== Local Plain Build ===

==== Prerequisites ====

First, we will assume you have correctly completed the [[#Prerequisites_2 | Prerequisites]].

Second, we will also assume you've already git-cloned LuxCore on your local machine, opened a terminal, changed directory to LuxCore folder and git-checked out the branch that you want to build (+ for Windows: initialized build environment with <code>vcvarsall.bat</code>)

==== Basic build ====

Our build system internally relies on <code>cmake</code> but, for more convenience, everything has been wrapped into <code>make</code>-like statements.

So, to build LuxCore, one just have to enter the following magic words:
<pre>
make deps
make
</pre>

This should retrieve and install LuxCore dependencies, configure the project and run the build. That's all!

For subsequent builds, if no modification have been made to dependencies, you'll just have to re-enter: <pre>make</pre>

==== Specific targets ====

If you want to target a specific component, you can replace the above plain <code>make</code> by one of the following verbs:
<pre>make luxcore</pre>
<pre>make pyluxcore</pre>
<pre>make luxcoreui</pre>
<pre>make luxcoreconsole</pre>

Starting from version 2.11, this method can build a "test wheel". This is a simplified wheel, only for current platform and current Python version, for testing purpose. The test wheel is particularly useful for developing/debugging LuxCore/BlendLuxCore integration.
The verb is:
<pre>make wheel-test</pre>

You can also build Doxygen documentation with the following statement:
<pre>make doc</pre>

==== Build type ====

By default, this method builds a release version, striped from all symbols. If you want to build a debug version, enter the following before any <code>make ...</code> command:

<pre>export LUX_BUILD_TYPE=Debug</pre>

==== Local dependency set ====

It is possible to use a local dependency set, rather than relying on automatic downloading. It is especially useful for developing/debugging of LuxCoreDeps/LuxCore integration. In this case, one can replace the <code>make deps</code> statement by the following one:

<pre>
python -m build-system.luxmake.deps --local <path/to/local/deps> --release <release>
</pre>

Nota: <code><release></code> is the release tag used by your local dependency set. If you build this set locally, it should likely be <code>test</code>.

==== Cleaning ====

You can remove build outputs with one of the following statement:
<pre>make clean</pre>
or
<pre>make clear</pre>
The former will remove build files, however preserving dependencies.
The latter will remove everything and will require to reinstall dependencies (<code>make deps</code>).

=== Local Continuous Integration ===

This method is complementary to Local plain build, with the following additional capabilities:
* test the LuxCore build in an environment close to the release environment (manylinux container, for instance)
* can build wheels
* debug any changes made to the build workflow

It consists in running Github workflows locally, via <code>act</code>. Github workflows are located in <code>.github/workflows</code> folder.

<code>act</code> invokation can be made on command line but, for convenience, a wrapper script is provided (for Linux): <pre>./build-helpers/debug/debug_wheels.sh</pre>

Caveat: this build can produce wheels, but only for the host platform (no cross-compiling).

=== Server Continuous Integration ===

The process is nearly the same as publisher build, but the release steps are skipped. For that purpose, another Github workflow has to be executed: [https://github.com/LuxCoreRender/LuxCore/actions/workflows/wheel-builder.yml <code>LuxCore Python Wheels Builder</code>].

Please note that your changes must have been committed to repository before running the workflow.

If build succeeds, you will find the expected outputs in Artifacts section of the action run.

= Publisher Workflows =

== Prerequisites ==

For these workflows, a Github account is required, with extended rights on the source repositories.

== General Workflow ==

The general workflow for publishing is in 3 parts:

{{#mermaid:

%%{ init: {
'theme': 'neutral',
'flowchart': { 'curve': 'monotoneX' }
}
}%%
flowchart TD;
subgraph Build["<center>BUILD & RELEASE DRAFT (Run Releaser workflow)</center>"]
padBuild(" "):::INVISIBLE
repo("Go to <code>[Source repository]</code> on Github and open <code>Actions menu</code>")
select("Select <code>[Releaser workflow]</code>")
runwf(Click on <code>Run workflow</code> button, in the upper-right corner)
branch(Select <code>Branch</code> in drop-down menu)
options(Set workflow options)
validate(Click <code>Run workflow</code>)
wait(Wait for build to complete)
end

subgraph Release["<center>MAKE FINAL RELEASE(Switch release to final status)</center>"]
padRelease(" "):::INVISIBLE
release("Open <code>[Release folder]</code>, find the newly-built release (in Draft mode) and edit it")
complete(Add relevant information: change log, comments on version etc.)
dedraft(Unset <code>Draft</code> checkbox)
update(Click <code>Publish release</code>/<code>Update release</code> to finalize)
end

subgraph Deploy["<center>PUBLISH(Run Publisher workflow)</center>"]
padDeploy(" ")
repoDeploy("Go to <code>[Source repository]</code> on Github and open <code>[Actions menu]</code>")
selectDeploy("Select <code>[Publisher workflow]</code>")
runwfDeploy("Click on <code>Run workflow</code> drop-down button, in the upper-right corner")
choiceDeploy("Select <code>Branch</code>, set the <code>Tag to publish</code> and uncheck <code>Publish on Pypi Test</code> if needed")
validateDeploy("Click on <code>Run workflow</code> button")
waitDeploy("Wait for deployment to complete")
end

padBuild---repo
repo-->select
select-->runwf
runwf-->branch
branch-->options
options-->validate
validate-->wait:::WAIT
linkStyle 0 stroke:#fff,stroke-width:0px,color:blue;

padRelease---release
release-->complete
complete-->dedraft
dedraft-->update
linkStyle 7 stroke:#fff,stroke-width:0px,color:blue;

padDeploy:::INVISIBLE---repoDeploy
repoDeploy-->selectDeploy
selectDeploy-->runwfDeploy
runwfDeploy-->choiceDeploy
choiceDeploy-->validateDeploy
validateDeploy-->waitDeploy:::WAIT
linkStyle 11 stroke:#fff,color:blue,stroke-width:0px;

Build-- if success -->Release
Release-- if success & if needed -->Deploy

classDef WAIT fill:#ddd;
classDef DEPS fill:#e4d8ff,stroke:#9488af;
classDef INVISIBLE fill:#ffffffff,stroke:#ffffffff,stroke-width:0px,font-color:#ffffffff;
classDef OPTIONAL stroke-dasharray: 5 5;

class Deploy OPTIONAL;

%% Note: padXXX is a poor hack to create a top-margin in subgraph...
}}

A few comments:
* <code>[bracketed tokens]</code> refer to data specific to each component, which will be detailed below.
* Publish part is optional, it will depends on the target
* ''Caveat: if you provide an already-existing release version number during the process, the workflow will replace the existing release with the newly-built one. This can be what you expected... or not. Be cautious.''

== Per-target details ==

=== External Dependencies ===

* Source repository: [https://github.com/LuxCoreRender/LuxCoreDeps <code>LuxCoreRender/LuxCoreDeps</code>]
* Releaser workflow: [https://github.com/LuxCoreRender/LuxCoreDeps/actions/workflows/release.yml <code>LuxCore Dependency Releaser</code>]
* Release folder: [https://github.com/LuxCoreRender/LuxCoreDeps/releases <code>Releases</code>]
* Publisher workflow: ∅

As a byproduct, External Dependencies are not intended to be deployed, so no Publisher workflow is provided.

=== Python Wheels ===

As far as wheels are concerned, in addition to building them, it is also necessary to upload them to [https://pypi.org/ PyPi] ("publish" them), so that they are available for [https://pypi.org/project/pip pip] installation.

* Source repository: [https://github.com/LuxCoreRender/LuxCore <code>LuxCoreRender/LuxCore</code>]
* Releaser workflow: [https://github.com/LuxCoreRender/LuxCore/actions/workflows/wheel-releaser.yml <code>LuxCore Wheels Releaser</code>]
* Release folder: [https://github.com/LuxCoreRender/LuxCore/releases <code>Releases</code>]
* Publisher workflow: [https://github.com/LuxCoreRender/LuxCore/actions/workflows/wheel-publisher.yml <code>LuxCore Wheels Publisher</code>]

''Prerequisite: you must have released a compatible version of External Dependencies (LuxCoreDeps) before building Python Wheels.''

=== Samples ===

As we plan to replace Samples by equivalent Python tools and thus deprecate them, the workflow has been limited to the Release part (no publish).

* Source repository: [https://github.com/LuxCoreRender/LuxCore <code>LuxCoreRender/LuxCore</code>]
* Releaser workflow: [https://github.com/LuxCoreRender/LuxCore/actions/workflows/sample-releaser.yml <code>LuxCore Samples Releaser</code>]
* Release folder: [https://github.com/LuxCoreRender/LuxCore/releases <code>Releases</code>]
* Publisher workflow: ∅

=== BlendLuxCore ===

TODO

= Version Management =

== Semantic Versioning ==

Starting for LuxCore version 2.10.0, we require that LuxCoreRender applies [https://semver.org/ Semantic Versioning]. Please strictly enforce this rule when incrementing version numbers.

Remark: component versions does not have to be synced. For instance, in strict application of the standard, the newly created LuxCoreDeps will start at 1.0.0, while at the same time LuxCore is already at 2.10.0

== Dependency Version pointer ==

To make LuxCore know which version of dependencies it must be built against, we use a pointer.

This pointer is stored in the file <code>build-helpers/build-settings.json</code>, under the path <code>Dependencies/release</code>.

Make sure you keep it up-to-date when you upgrade LuxCore components.

Building LuxCoreRender - FAQ

2026-04-28T03:22:34Z

Howetuft:

Building LuxCoreRender

2026-04-28T03:10:49Z

Howetuft: /* Caveats */

This document describes the various processes involved in building LuxCoreRender, starting with version 2.10 “Back-on-track”.

LuxCoreRender's build system has been significantly modified for version 2.10. This document therefore renders obsolete all [[Building_LuxCoreRender_(legacy)|previous documents]] related to the compilation of older versions (<=2.9).

TL;DR If you are just interested in a quick, local (but platform limited) compilation of LuxCore C++ samples or Python wheels, you may want to jump directly to [[#Build LuxCore, Samples & Python Wheels | Build LuxCore, Samples & Python Wheels]].

= Audience =

This document is intended for:
* LuxCoreRender administrators in charge of releasing the various LuxCoreRender end-products;
* Developers wishing to contribute to the project;
* External package maintainers wishing to integrate all or part of LuxCoreRender into a distribution;

This document assumes that the reader is skilled in the following areas:
* C/C++ compilation
* [https://cmake.org/ cmake]
* [https://git-scm.com/ git]
* [https://docs.github.com/en/actions/writing-workflows Github Workflows]
* [https://packaging.python.org/en/latest/ Python Packaging], including [https://realpython.com/python-wheels/ Python Wheels format]

Familiarity with [https://conan.io/ Conan] dependency manager may also help.


This document is not intended for end-users without any knowledge about application building. Such users are invited to look for already compiled binaries on the official [https://luxcorerender.org/download/ Download] page.

= Build Targets =

== Synoptic ==
LuxCoreRender contains several build targets, below represented with dependency links:

{{#mermaid:
%%{
init: {
"theme": "forest",
"logLevel": "info",
"flowchart": {"curve": "basis"}
}
}%%

flowchart LR;

classDef TYPE font-weight:bold,font-size:1.1rem;
classDef TARGET font-weight:bold,font-size:0.9rem;

classDef LUXCOREDEPS fill:#ffe8ff,stroke:#9488af,font-weight:bold,font-size:1.1rem;
classDef TARGETDEPS fill:#e4d8ff,stroke:#9488af,font-weight:bold,font-size:0.9rem;

classDef LUXCORE fill:#bbceff,font-weight:bold,font-size:1.1rem,stroke:#999999;
classDef TARGETLUXCORE fill:#7799ee,font-weight:bold,font-size:0.9rem,stroke:#999999;

classDef SAMPLES fill:#ffffdd,font-weight:bold,font-size:1.1rem,stroke:#999999;
classDef TARGETSAMPLES fill:#eeeecc,font-weight:bold,font-size:0.9rem,stroke:#999999;

classDef NEUTRAL fill:#fafafa,font-weight:bold,font-size:1.1rem,stroke:#999999;
classDef TARGETNEUTRAL fill:#eeeeee,font-weight:bold,font-size:0.9rem,stroke:#999999;

classDef EXTDEP fill:#00000000,stroke:#00000000;

subgraph Dependencies[External Dependencies]
deps(LuxCore Dependencies)
end

class Dependencies LUXCOREDEPS;
class deps TARGETDEPS;

subgraph LuxCore
lux(luxcore.so/.dll)
luxa(luxcore.a)
end
class LuxCore LUXCORE;
class lux TARGETLUXCORE;
class luxa TARGETLUXCORE;

subgraph Python_Wheels[Python Wheels]
pylux(pyluxcore.so/.dll)
wheels(LuxCore Python Wheels)
end
class Python_Wheels TYPE;
class pylux TARGET;
class wheels TARGET;

subgraph Samples
luxcoreui(luxcoreui)
luxcoreconsole(luxcoreconsole)
end
class Samples SAMPLES;
class luxcoreui TARGETSAMPLES;
class luxcoreconsole TARGETSAMPLES;

subgraph PyLuxCoreTools
pyluxcon(pyluxcoreconsole)
pyluxothers(...)
end
class PyLuxCoreTools NEUTRAL;
class pyluxcon TARGETNEUTRAL;
class pyluxothers TARGETNEUTRAL;

subgraph Plugins[Python Plugins]
blc(BlendLuxCore)
otherplugins(...)
end
class blc TARGETNEUTRAL;
class otherplugins TARGETNEUTRAL;

class Plugins NEUTRAL;

%% Warning: order matters
deps-->lux
deps-->luxa
deps-->luxcoreui
deps-->luxcoreconsole

luxa--->pylux
lux-->luxcoreui
lux-->luxcoreconsole
deps-->pylux

pylux-->wheels
wheels-. runtime .->blc
wheels-. runtime .->otherplugins

wheels-. runtime .->pyluxcon
wheels-. runtime .->pyluxothers

Python:::EXTDEP-->pylux

%% Mermaid version: 8.14.0
%% https://github.com/mermaid-js/mermaid/blob/8.14.0/src/defaultConfig.js

}}

{| class="wikitable" style="margin:auto"
|-
! Target !! Source Repository !! Content
|-
| External Dependencies|| [https://github.com/LuxCoreRender/LuxCoreDeps <code>LuxCoreDeps</code>] || A bundled Conan cache populated with LuxCoreRender external dependency binaries, built from sources. Please refer to [https://github.com/LuxCoreRender/LuxCoreDeps/blob/main/README.md LuxCoreDeps README] for more information.
|-
| LuxCore || [https://github.com/LuxCoreRender/LuxCore <code>LuxCore</code>] || LuxCore core binaries, in the form of static and shared libraries: luxcore.so, luxcore_static.lib, luxcore.dll etc.
|-
| Samples|| [https://github.com/LuxCoreRender/LuxCore <code>LuxCore</code>] || Sample C++ programs, illustrating luxcore use, namely <code>luxcoreconsole</code> and <code>luxcoreui</code>
|-
| Python Wheels|| [https://github.com/LuxCoreRender/LuxCore <code>LuxCore</code>] || Python bindings of core binaries, in the form of Python wheels (1 per pair Platform/Python version). As a byproduct, a Pythonized version of LuxCore shared library is also built (pyluxcore.so).
|-
| Python Plugins|| [https://github.com/LuxCoreRender/BlendLuxCore <code>BlendLuxCore</code>] etc. || Plugins to expose LuxCore in various external applications, notably Blender. Written in Python and relying on Python Wheels as runtime dependency.
|-
| PyLuxCoreTools|| [https://github.com/LuxCoreRender/LuxCore <code>LuxCore</code>] || Python LuxCore Tools: set of command line tools based on pyluxcore, written in Python.
|}

== Targeted platforms ==

LuxCoreRender aims at being available on the following 4 platforms:
* Linux (glibc 2.28+)
* Windows
* MacOS Intel (>=10.15)
* MacOS Arm (>=12.0)

For Python-related targets, LuxCoreRender aims at being declined for [https://devguide.python.org/versions all Python versions supported at a given time].

= Workflow Types =

We distinguish between two types of build workflows:
* Developer workflows
* Publisher workflows

''[[#Developer Workflows | Developer workflows]]'' are designed for development, debugging and test steps.

Their purpose is to allow development and verify the code is ready for publication.

''[[#Publisher Workflows | Publisher workflows]]'' are designed to be used by LuxCoreRender administrators to publish a new release of one or more LuxCoreRender components.

They exclusively take place in a CI/CD Github pipeline.

These workflows are not designed for debugging or testing the underlying code. Execution of these workflows assumes that the development phase has been correctly completed and the underlying code is ready for final build and release. See [[#Developer Workflows | Developer Workflows]] to learn how to get code ready for final build.

Running these workflows require users to be granted of extended rights on LuxCoreRender repositories.

= Developer Workflows =

== Prerequisites ==

Tools

You will need several build tools installed and referenced in the PATH.

First, ensure you have a suitable toolchain:

{| class="wikitable" style="margin:auto"
|-
! OS !! Compiler !! Minimal version
|-
| Windows || MSVC || 194x latest version
|-
| Linux|| gcc || 14
|-
| MacOS Intel|| XCode + llvm + libomp || llvm >= 20 (<code>brew install llvm && brew install libomp</code>)
|-
| MacOS Arm || XCode + llvm + libomp || llvm >= 20 (<code>brew install llvm && brew install libomp</code>)
|}

''Toolchain compliance is a very sensitive condition for a successful build. Before filing any claim, please check that your toolchain complies with the above requirements.''

Then ensure the following software is also installed and available in your PATH:

* [https://git-scm.com/ Git]
* [https://cli.github.com/ Github CLI] (optional but recommended - for dependency signature checking)
* [https://www.python.org/ Python 3] - any [https://devguide.python.org/versions/ currently supported version]
* [https://conan.io Conan] latest version (pip install conan)
* [https://github.com/pypa/wheel/tree/main Wheel] latest version (pip install wheel)
* [https://cmake.org/ CMake] >= 3.29
* [https://github.com/nektos/act nektos/act] (optional but recommended - for local build based on Github workflows)
* [https://pypi.org/project/repairwheel repairwheel] (optional but recommended - for local build of test wheels)

Platform specifics:
* For Windows, ensure the command line is configured for building (<code>vcvarsall.bat</code>).
* For Linux, you'll need <code>pkgconfig</code> in addition.
* For MacOS, you'll need to ensure CC and CXX point to LLVM clang/clang++

Accounts

A ''Github account'' is mandatory for LuxCore development.

Following accounts are also recommended, in order to get in touch with LuxCore community:
* [https://forums.luxcorerender.org/ LuxCoreRender Forums]
* [https://discord.gg/chPGsKV LuxCoreRender Discord channel]

== General Developer Workflow ==

To compile and verify LuxCore component modifications in development process, there are 3 stages:
* Local plain build: only run build system (cmake) on developer computer
* Local Continuous Integration build: run full Continuous Integration workflow on developer computer
* Server Continuous Integration build: run full Continuous Integration workflow on server

Local plain build is generally faster than other builds and does not require to commit changes beforehand. Plain build installs a minimal build configuration (dependencies), but heavily relies on computer build environment for the rest (build tools, system libraries etc.). As a counterpart, it builds only for the platform where it is executed and can be significantly altered by local conditions (build tools local versions, dependency local versions etc.), thus not fully guaranteeing that final publish workflow will succeed.

LocalCI is generally faster than Server build, but slower than local plain build. CI workflow installs a complete build environment (compilers, sdk, build tools, containers, dependencies etc.) before running build system. It does not require to commit changes beforehand. However, it builds only for the platform where it is executed, thus not fully guaranteeing that final publish workflow will succeed.

Server CI, if successful, should guarantee success when publishing, as it occurs in conditions similar to release workflow (all platforms, complete build environment). As a counterpart, it is generally significantly slower than local builds and also implies to commit and push changes beforehand, even if the code is in unstable state.

The recommended workflow thus strives to make the most of all stages:

{{#mermaid:

%%{ init: {
'theme': 'neutral',
'flowchart': { 'curve': 'monotoneX' }
}
}%%

flowchart TD;

fork(Fork Source repository in your own Github space)
clone("Clone your fork locally<code>git clone...</code>")
devel(Make modifications in your local fork)
localBuild("Run local plain build<code>cmake</code>, <code>make</code>...")
localCI("Run local CI<code>act</code>")
git("Commit, Rebase & Push<code>git ...</code>")
serverCI(Run server CI<code>Github workflow</code>)
PR(PR your changes to Source repository)

fork-->clone
clone-->devel
devel-->localBuild
localBuild-->localCI
localCI-- "Success(including debug & tests)" -->git
git-->serverCI
serverCI-- Success -->PR

localBuild & localCI & serverCI ----> |Failure| devel

classDef BUILD fill:#acc,stroke-width:4px;
class localBuild BUILD;
class localCI BUILD;
class serverCI BUILD;

}}

This is the common process between all components. Each step will then be adapted to each component, as explained below.

Comments:
* Running local CI relies on [https://github.com/nektos/act <code>nektos/act</code>]
* Rebase must be made against upstream directory (<code>git pull --rebase upstream <branch></code>)before pushing
* Push must be made towards developer own fork. Caveat: do not try to push directly to upstream

== Build External Dependencies ==

=== Local Plain Build ===
==== Caveats ====
Dependency local plain build is possible but:
* Local plain build IS NOT THE RECOMMENDED BUILD FOR FINAL DEPS. This build is solely intended for intermediary development and debugging. No support will be provided when used out-of-scope.
* Local plain build has only been tested on Linux, with gcc >=14. For other platforms, adaptations should be necessary (contributions welcome).
* Local plain build is much impacted by local particulars (local compiler version, dependencies already in cache or in system dirs etc.) and therefore does not guarantee further success for other builds.

==== Prerequisites ====
In addition with general [[#Prerequisites_2 | Prerequisites]], you'll need the OneAPI ISPC compiler.

==== Conan cache interaction ====

The build relies on the local Conan cache, which will be modified by the process. You may want to make a copy beforehand.

In some scenarios, you may also want to reset your Conan cache (warning: may remove files unrelated to LuxCoreDeps):
<pre>conan remove -c "*" # Be careful: may remove packages unrelated to LuxCoreDeps!</pre>

==== Run ====

To run a plain local build, run the following statements in a console, from the root of LuxCoreDeps repository:

<pre>
export RUNNER_OS=<os>
export RUNNER_ARCH=<arch>

export LUXDEPS_VERSION=test
export GCC_VERSION=14 # Note: even for gcc > 14
export WORKSPACE=.
export CXX_VERSION=20
export CMAKE_POLICY_VERSION_MINIMUM=3.25
export DEPS_BUILD_TYPE=Debug # Or Release/RelWithDebInfo/MinSizeRel, as needed
export cache_dir

./run_conan.sh
</pre>

with <code>RUNNER_OS</code>, <code>RUNNER_ARCH</code> in:
* <code>Linux</code> / <code>X64</code>
* <code>Windows</code> / <code>X64</code>
* <code>macOS</code> / <code>X64</code>
* <code>macOS</code> / <code>ARM64</code>
reflecting your build platform.

No detection is made (compiler, OS, arch...) . You'll have to do it on your own and set environment variables accordingly.

==== Cleaning ====

Conan will produce a bunch of scripts in the root of LuxCoreDeps repo. You can clean them with the following:
<pre> ./utils/clean-conan-files.sh </pre>

=== Local Continuous Integration ===

Run <code>act</code> on workflows located in <code>.github/workflows</code> folder, for instance <code>.github/workflows/build.yml</code> workflow.

For more convenience, a wrapper script is also provided in <code>LuxCoreDeps</code> repository (Linux only, at the moment): <pre>./utils/local-CI-build.sh</pre>

=== Server Continuous Integration ===

This process relies on the following Github workflow: [https://github.com/LuxCoreRender/LuxCoreDeps/actions/workflows/checker.yml <code>LuxCore Dependency Checker</code>].
Important points:
* Your changes must have been committed and pushed to repository before.
* The Checker workflow is actually also triggered on push event, so you may not have to run it by yourself

If build succeeds, you will find the expected outputs in Artifacts section of the action run.

== Build LuxCore, Samples & Python Wheels ==

=== Local Plain Build ===

==== Prerequisites ====

First, we will assume you have correctly completed the [[#Prerequisites_2 | Prerequisites]].

Second, we will also assume you've already git-cloned LuxCore on your local machine, opened a terminal, changed directory to LuxCore folder and git-checked out the branch that you want to build (+ for Windows: initialized build environment with <code>vcvarsall.bat</code>)

==== Basic build ====

Our build system internally relies on <code>cmake</code> but, for more convenience, everything has been wrapped into <code>make</code>-like statements.

So, to build LuxCore, one just have to enter the following magic words:
<pre>
make deps
make
</pre>

This should retrieve and install LuxCore dependencies, configure the project and run the build. That's all!

For subsequent builds, if no modification have been made to dependencies, you'll just have to re-enter: <pre>make</pre>

==== Specific targets ====

If you want to target a specific component, you can replace the above plain <code>make</code> by one of the following verbs:
<pre>make luxcore</pre>
<pre>make pyluxcore</pre>
<pre>make luxcoreui</pre>
<pre>make luxcoreconsole</pre>

Starting from version 2.11, this method can build a "test wheel". This is a simplified wheel, only for current platform and current Python version, for testing purpose. The test wheel is particularly useful for developing/debugging LuxCore/BlendLuxCore integration.
The verb is:
<pre>make wheel-test</pre>

You can also build Doxygen documentation with the following statement:
<pre>make doc</pre>

==== Build type ====

By default, this method builds a release version, striped from all symbols. If you want to build a debug version, enter the following before any <code>make ...</code> command:

<pre>export LUX_BUILD_TYPE=Debug</pre>

==== Local dependency set ====

It is possible to use a local dependency set, rather than relying on automatic downloading. It is especially useful for developing/debugging of LuxCoreDeps/LuxCore integration. In this case, one can replace the <code>make deps</code> statement by the following one:

<pre>
python -m build-system.luxmake.deps --local <path/to/local/deps> --release <release>
</pre>

Nota: <code><release></code> is the release tag used by your local dependency set. If you build this set locally, it should likely be <code>test</code>.

==== Cleaning ====

You can remove build outputs with one of the following statement:
<pre>make clean</pre>
or
<pre>make clear</pre>
The former will remove build files, however preserving dependencies.
The latter will remove everything and will require to reinstall dependencies (<code>make deps</code>).

=== Local Continuous Integration ===

This method is complementary to Local plain build, with the following additional capabilities:
* test the LuxCore build in an environment close to the release environment (manylinux container, for instance)
* can build wheels
* debug any changes made to the build workflow

It consists in running Github workflows locally, via <code>act</code>. Github workflows are located in <code>.github/workflows</code> folder.

<code>act</code> invokation can be made on command line but, for convenience, a wrapper script is provided (for Linux): <pre>./build-helpers/debug/debug_wheels.sh</pre>

Caveat: this build can produce wheels, but only for the host platform (no cross-compiling).

=== Server Continuous Integration ===

The process is nearly the same as publisher build, but the release steps are skipped. For that purpose, another Github workflow has to be executed: [https://github.com/LuxCoreRender/LuxCore/actions/workflows/wheel-builder.yml <code>LuxCore Python Wheels Builder</code>].

Please note that your changes must have been committed to repository before running the workflow.

If build succeeds, you will find the expected outputs in Artifacts section of the action run.

= Publisher Workflows =

== Prerequisites ==

For these workflows, a Github account is required, with extended rights on the source repositories.

== General Workflow ==

The general workflow for publishing is in 3 parts:

{{#mermaid:

%%{ init: {
'theme': 'neutral',
'flowchart': { 'curve': 'monotoneX' }
}
}%%
flowchart TD;
subgraph Build["<center>BUILD & RELEASE DRAFT (Run Releaser workflow)</center>"]
padBuild(" "):::INVISIBLE
repo("Go to <code>[Source repository]</code> on Github and open <code>Actions menu</code>")
select("Select <code>[Releaser workflow]</code>")
runwf(Click on <code>Run workflow</code> button, in the upper-right corner)
branch(Select <code>Branch</code> in drop-down menu)
options(Set workflow options)
validate(Click <code>Run workflow</code>)
wait(Wait for build to complete)
end

subgraph Release["<center>MAKE FINAL RELEASE(Switch release to final status)</center>"]
padRelease(" "):::INVISIBLE
release("Open <code>[Release folder]</code>, find the newly-built release (in Draft mode) and edit it")
complete(Add relevant information: change log, comments on version etc.)
dedraft(Unset <code>Draft</code> checkbox)
update(Click <code>Publish release</code>/<code>Update release</code> to finalize)
end

subgraph Deploy["<center>PUBLISH(Run Publisher workflow)</center>"]
padDeploy(" ")
repoDeploy("Go to <code>[Source repository]</code> on Github and open <code>[Actions menu]</code>")
selectDeploy("Select <code>[Publisher workflow]</code>")
runwfDeploy("Click on <code>Run workflow</code> drop-down button, in the upper-right corner")
choiceDeploy("Select <code>Branch</code>, set the <code>Tag to publish</code> and uncheck <code>Publish on Pypi Test</code> if needed")
validateDeploy("Click on <code>Run workflow</code> button")
waitDeploy("Wait for deployment to complete")
end

padBuild---repo
repo-->select
select-->runwf
runwf-->branch
branch-->options
options-->validate
validate-->wait:::WAIT
linkStyle 0 stroke:#fff,stroke-width:0px,color:blue;

padRelease---release
release-->complete
complete-->dedraft
dedraft-->update
linkStyle 7 stroke:#fff,stroke-width:0px,color:blue;

padDeploy:::INVISIBLE---repoDeploy
repoDeploy-->selectDeploy
selectDeploy-->runwfDeploy
runwfDeploy-->choiceDeploy
choiceDeploy-->validateDeploy
validateDeploy-->waitDeploy:::WAIT
linkStyle 11 stroke:#fff,color:blue,stroke-width:0px;

Build-- if success -->Release
Release-- if success & if needed -->Deploy

classDef WAIT fill:#ddd;
classDef DEPS fill:#e4d8ff,stroke:#9488af;
classDef INVISIBLE fill:#ffffffff,stroke:#ffffffff,stroke-width:0px,font-color:#ffffffff;
classDef OPTIONAL stroke-dasharray: 5 5;

class Deploy OPTIONAL;

%% Note: padXXX is a poor hack to create a top-margin in subgraph...
}}

A few comments:
* <code>[bracketed tokens]</code> refer to data specific to each component, which will be detailed below.
* Publish part is optional, it will depends on the target
* ''Caveat: if you provide an already-existing release version number during the process, the workflow will replace the existing release with the newly-built one. This can be what you expected... or not. Be cautious.''

== Per-target details ==

=== External Dependencies ===

* Source repository: [https://github.com/LuxCoreRender/LuxCoreDeps <code>LuxCoreRender/LuxCoreDeps</code>]
* Releaser workflow: [https://github.com/LuxCoreRender/LuxCoreDeps/actions/workflows/release.yml <code>LuxCore Dependency Releaser</code>]
* Release folder: [https://github.com/LuxCoreRender/LuxCoreDeps/releases <code>Releases</code>]
* Publisher workflow: ∅

As a byproduct, External Dependencies are not intended to be deployed, so no Publisher workflow is provided.

=== Python Wheels ===

As far as wheels are concerned, in addition to building them, it is also necessary to upload them to [https://pypi.org/ PyPi] ("publish" them), so that they are available for [https://pypi.org/project/pip pip] installation.

* Source repository: [https://github.com/LuxCoreRender/LuxCore <code>LuxCoreRender/LuxCore</code>]
* Releaser workflow: [https://github.com/LuxCoreRender/LuxCore/actions/workflows/wheel-releaser.yml <code>LuxCore Wheels Releaser</code>]
* Release folder: [https://github.com/LuxCoreRender/LuxCore/releases <code>Releases</code>]
* Publisher workflow: [https://github.com/LuxCoreRender/LuxCore/actions/workflows/wheel-publisher.yml <code>LuxCore Wheels Publisher</code>]

''Prerequisite: you must have released a compatible version of External Dependencies (LuxCoreDeps) before building Python Wheels.''

=== Samples ===

As we plan to replace Samples by equivalent Python tools and thus deprecate them, the workflow has been limited to the Release part (no publish).

* Source repository: [https://github.com/LuxCoreRender/LuxCore <code>LuxCoreRender/LuxCore</code>]
* Releaser workflow: [https://github.com/LuxCoreRender/LuxCore/actions/workflows/sample-releaser.yml <code>LuxCore Samples Releaser</code>]
* Release folder: [https://github.com/LuxCoreRender/LuxCore/releases <code>Releases</code>]
* Publisher workflow: ∅

=== BlendLuxCore ===

TODO

= Version Management =

== Semantic Versioning ==

Starting for LuxCore version 2.10.0, we require that LuxCoreRender applies [https://semver.org/ Semantic Versioning]. Please strictly enforce this rule when incrementing version numbers.

Remark: component versions does not have to be synced. For instance, in strict application of the standard, the newly created LuxCoreDeps will start at 1.0.0, while at the same time LuxCore is already at 2.10.0

== Dependency Version pointer ==

To make LuxCore know which version of dependencies it must be built against, we use a pointer.

This pointer is stored in the file <code>build-helpers/build-settings.json</code>, under the path <code>Dependencies/release</code>.

Make sure you keep it up-to-date when you upgrade LuxCore components.

Building LuxCoreRender

2026-04-28T03:10:04Z

Howetuft: /* Caveats */

This document describes the various processes involved in building LuxCoreRender, starting with version 2.10 “Back-on-track”.

LuxCoreRender's build system has been significantly modified for version 2.10. This document therefore renders obsolete all [[Building_LuxCoreRender_(legacy)|previous documents]] related to the compilation of older versions (<=2.9).

TL;DR If you are just interested in a quick, local (but platform limited) compilation of LuxCore C++ samples or Python wheels, you may want to jump directly to [[#Build LuxCore, Samples & Python Wheels | Build LuxCore, Samples & Python Wheels]].

= Audience =

This document is intended for:
* LuxCoreRender administrators in charge of releasing the various LuxCoreRender end-products;
* Developers wishing to contribute to the project;
* External package maintainers wishing to integrate all or part of LuxCoreRender into a distribution;

This document assumes that the reader is skilled in the following areas:
* C/C++ compilation
* [https://cmake.org/ cmake]
* [https://git-scm.com/ git]
* [https://docs.github.com/en/actions/writing-workflows Github Workflows]
* [https://packaging.python.org/en/latest/ Python Packaging], including [https://realpython.com/python-wheels/ Python Wheels format]

Familiarity with [https://conan.io/ Conan] dependency manager may also help.


This document is not intended for end-users without any knowledge about application building. Such users are invited to look for already compiled binaries on the official [https://luxcorerender.org/download/ Download] page.

= Build Targets =

== Synoptic ==
LuxCoreRender contains several build targets, below represented with dependency links:

{{#mermaid:
%%{
init: {
"theme": "forest",
"logLevel": "info",
"flowchart": {"curve": "basis"}
}
}%%

flowchart LR;

classDef TYPE font-weight:bold,font-size:1.1rem;
classDef TARGET font-weight:bold,font-size:0.9rem;

classDef LUXCOREDEPS fill:#ffe8ff,stroke:#9488af,font-weight:bold,font-size:1.1rem;
classDef TARGETDEPS fill:#e4d8ff,stroke:#9488af,font-weight:bold,font-size:0.9rem;

classDef LUXCORE fill:#bbceff,font-weight:bold,font-size:1.1rem,stroke:#999999;
classDef TARGETLUXCORE fill:#7799ee,font-weight:bold,font-size:0.9rem,stroke:#999999;

classDef SAMPLES fill:#ffffdd,font-weight:bold,font-size:1.1rem,stroke:#999999;
classDef TARGETSAMPLES fill:#eeeecc,font-weight:bold,font-size:0.9rem,stroke:#999999;

classDef NEUTRAL fill:#fafafa,font-weight:bold,font-size:1.1rem,stroke:#999999;
classDef TARGETNEUTRAL fill:#eeeeee,font-weight:bold,font-size:0.9rem,stroke:#999999;

classDef EXTDEP fill:#00000000,stroke:#00000000;

subgraph Dependencies[External Dependencies]
deps(LuxCore Dependencies)
end

class Dependencies LUXCOREDEPS;
class deps TARGETDEPS;

subgraph LuxCore
lux(luxcore.so/.dll)
luxa(luxcore.a)
end
class LuxCore LUXCORE;
class lux TARGETLUXCORE;
class luxa TARGETLUXCORE;

subgraph Python_Wheels[Python Wheels]
pylux(pyluxcore.so/.dll)
wheels(LuxCore Python Wheels)
end
class Python_Wheels TYPE;
class pylux TARGET;
class wheels TARGET;

subgraph Samples
luxcoreui(luxcoreui)
luxcoreconsole(luxcoreconsole)
end
class Samples SAMPLES;
class luxcoreui TARGETSAMPLES;
class luxcoreconsole TARGETSAMPLES;

subgraph PyLuxCoreTools
pyluxcon(pyluxcoreconsole)
pyluxothers(...)
end
class PyLuxCoreTools NEUTRAL;
class pyluxcon TARGETNEUTRAL;
class pyluxothers TARGETNEUTRAL;

subgraph Plugins[Python Plugins]
blc(BlendLuxCore)
otherplugins(...)
end
class blc TARGETNEUTRAL;
class otherplugins TARGETNEUTRAL;

class Plugins NEUTRAL;

%% Warning: order matters
deps-->lux
deps-->luxa
deps-->luxcoreui
deps-->luxcoreconsole

luxa--->pylux
lux-->luxcoreui
lux-->luxcoreconsole
deps-->pylux

pylux-->wheels
wheels-. runtime .->blc
wheels-. runtime .->otherplugins

wheels-. runtime .->pyluxcon
wheels-. runtime .->pyluxothers

Python:::EXTDEP-->pylux

%% Mermaid version: 8.14.0
%% https://github.com/mermaid-js/mermaid/blob/8.14.0/src/defaultConfig.js

}}

{| class="wikitable" style="margin:auto"
|-
! Target !! Source Repository !! Content
|-
| External Dependencies|| [https://github.com/LuxCoreRender/LuxCoreDeps <code>LuxCoreDeps</code>] || A bundled Conan cache populated with LuxCoreRender external dependency binaries, built from sources. Please refer to [https://github.com/LuxCoreRender/LuxCoreDeps/blob/main/README.md LuxCoreDeps README] for more information.
|-
| LuxCore || [https://github.com/LuxCoreRender/LuxCore <code>LuxCore</code>] || LuxCore core binaries, in the form of static and shared libraries: luxcore.so, luxcore_static.lib, luxcore.dll etc.
|-
| Samples|| [https://github.com/LuxCoreRender/LuxCore <code>LuxCore</code>] || Sample C++ programs, illustrating luxcore use, namely <code>luxcoreconsole</code> and <code>luxcoreui</code>
|-
| Python Wheels|| [https://github.com/LuxCoreRender/LuxCore <code>LuxCore</code>] || Python bindings of core binaries, in the form of Python wheels (1 per pair Platform/Python version). As a byproduct, a Pythonized version of LuxCore shared library is also built (pyluxcore.so).
|-
| Python Plugins|| [https://github.com/LuxCoreRender/BlendLuxCore <code>BlendLuxCore</code>] etc. || Plugins to expose LuxCore in various external applications, notably Blender. Written in Python and relying on Python Wheels as runtime dependency.
|-
| PyLuxCoreTools|| [https://github.com/LuxCoreRender/LuxCore <code>LuxCore</code>] || Python LuxCore Tools: set of command line tools based on pyluxcore, written in Python.
|}

== Targeted platforms ==

LuxCoreRender aims at being available on the following 4 platforms:
* Linux (glibc 2.28+)
* Windows
* MacOS Intel (>=10.15)
* MacOS Arm (>=12.0)

For Python-related targets, LuxCoreRender aims at being declined for [https://devguide.python.org/versions all Python versions supported at a given time].

= Workflow Types =

We distinguish between two types of build workflows:
* Developer workflows
* Publisher workflows

''[[#Developer Workflows | Developer workflows]]'' are designed for development, debugging and test steps.

Their purpose is to allow development and verify the code is ready for publication.

''[[#Publisher Workflows | Publisher workflows]]'' are designed to be used by LuxCoreRender administrators to publish a new release of one or more LuxCoreRender components.

They exclusively take place in a CI/CD Github pipeline.

These workflows are not designed for debugging or testing the underlying code. Execution of these workflows assumes that the development phase has been correctly completed and the underlying code is ready for final build and release. See [[#Developer Workflows | Developer Workflows]] to learn how to get code ready for final build.

Running these workflows require users to be granted of extended rights on LuxCoreRender repositories.

= Developer Workflows =

== Prerequisites ==

Tools

You will need several build tools installed and referenced in the PATH.

First, ensure you have a suitable toolchain:

{| class="wikitable" style="margin:auto"
|-
! OS !! Compiler !! Minimal version
|-
| Windows || MSVC || 194x latest version
|-
| Linux|| gcc || 14
|-
| MacOS Intel|| XCode + llvm + libomp || llvm >= 20 (<code>brew install llvm && brew install libomp</code>)
|-
| MacOS Arm || XCode + llvm + libomp || llvm >= 20 (<code>brew install llvm && brew install libomp</code>)
|}

''Toolchain compliance is a very sensitive condition for a successful build. Before filing any claim, please check that your toolchain complies with the above requirements.''

Then ensure the following software is also installed and available in your PATH:

* [https://git-scm.com/ Git]
* [https://cli.github.com/ Github CLI] (optional but recommended - for dependency signature checking)
* [https://www.python.org/ Python 3] - any [https://devguide.python.org/versions/ currently supported version]
* [https://conan.io Conan] latest version (pip install conan)
* [https://github.com/pypa/wheel/tree/main Wheel] latest version (pip install wheel)
* [https://cmake.org/ CMake] >= 3.29
* [https://github.com/nektos/act nektos/act] (optional but recommended - for local build based on Github workflows)
* [https://pypi.org/project/repairwheel repairwheel] (optional but recommended - for local build of test wheels)

Platform specifics:
* For Windows, ensure the command line is configured for building (<code>vcvarsall.bat</code>).
* For Linux, you'll need <code>pkgconfig</code> in addition.
* For MacOS, you'll need to ensure CC and CXX point to LLVM clang/clang++

Accounts

A ''Github account'' is mandatory for LuxCore development.

Following accounts are also recommended, in order to get in touch with LuxCore community:
* [https://forums.luxcorerender.org/ LuxCoreRender Forums]
* [https://discord.gg/chPGsKV LuxCoreRender Discord channel]

== General Developer Workflow ==

To compile and verify LuxCore component modifications in development process, there are 3 stages:
* Local plain build: only run build system (cmake) on developer computer
* Local Continuous Integration build: run full Continuous Integration workflow on developer computer
* Server Continuous Integration build: run full Continuous Integration workflow on server

Local plain build is generally faster than other builds and does not require to commit changes beforehand. Plain build installs a minimal build configuration (dependencies), but heavily relies on computer build environment for the rest (build tools, system libraries etc.). As a counterpart, it builds only for the platform where it is executed and can be significantly altered by local conditions (build tools local versions, dependency local versions etc.), thus not fully guaranteeing that final publish workflow will succeed.

LocalCI is generally faster than Server build, but slower than local plain build. CI workflow installs a complete build environment (compilers, sdk, build tools, containers, dependencies etc.) before running build system. It does not require to commit changes beforehand. However, it builds only for the platform where it is executed, thus not fully guaranteeing that final publish workflow will succeed.

Server CI, if successful, should guarantee success when publishing, as it occurs in conditions similar to release workflow (all platforms, complete build environment). As a counterpart, it is generally significantly slower than local builds and also implies to commit and push changes beforehand, even if the code is in unstable state.

The recommended workflow thus strives to make the most of all stages:

{{#mermaid:

%%{ init: {
'theme': 'neutral',
'flowchart': { 'curve': 'monotoneX' }
}
}%%

flowchart TD;

fork(Fork Source repository in your own Github space)
clone("Clone your fork locally<code>git clone...</code>")
devel(Make modifications in your local fork)
localBuild("Run local plain build<code>cmake</code>, <code>make</code>...")
localCI("Run local CI<code>act</code>")
git("Commit, Rebase & Push<code>git ...</code>")
serverCI(Run server CI<code>Github workflow</code>)
PR(PR your changes to Source repository)

fork-->clone
clone-->devel
devel-->localBuild
localBuild-->localCI
localCI-- "Success(including debug & tests)" -->git
git-->serverCI
serverCI-- Success -->PR

localBuild & localCI & serverCI ----> |Failure| devel

classDef BUILD fill:#acc,stroke-width:4px;
class localBuild BUILD;
class localCI BUILD;
class serverCI BUILD;

}}

This is the common process between all components. Each step will then be adapted to each component, as explained below.

Comments:
* Running local CI relies on [https://github.com/nektos/act <code>nektos/act</code>]
* Rebase must be made against upstream directory (<code>git pull --rebase upstream <branch></code>)before pushing
* Push must be made towards developer own fork. Caveat: do not try to push directly to upstream

== Build External Dependencies ==

=== Local Plain Build ===
==== Caveats ====
Dependency local plain build is possible but:
* Local plain build IS NOT THE RECOMMENDED BUILD FOR FINAL DEPS. This build is solely intended for intermediary development and debugging. No support will be provided when used out-of-scope.
* Local plain build has only be tested on Linux, with gcc >=14. For other platforms, adaptations should be necessary (contributions welcome).
* Local plain build is much impacted by local particulars (local compiler version, dependencies already in cache or in system dirs etc.) and therefore does not guarantee further success for other (recommended) builds.

==== Prerequisites ====
In addition with general [[#Prerequisites_2 | Prerequisites]], you'll need the OneAPI ISPC compiler.

==== Conan cache interaction ====

The build relies on the local Conan cache, which will be modified by the process. You may want to make a copy beforehand.

In some scenarios, you may also want to reset your Conan cache (warning: may remove files unrelated to LuxCoreDeps):
<pre>conan remove -c "*" # Be careful: may remove packages unrelated to LuxCoreDeps!</pre>

==== Run ====

To run a plain local build, run the following statements in a console, from the root of LuxCoreDeps repository:

<pre>
export RUNNER_OS=<os>
export RUNNER_ARCH=<arch>

export LUXDEPS_VERSION=test
export GCC_VERSION=14 # Note: even for gcc > 14
export WORKSPACE=.
export CXX_VERSION=20
export CMAKE_POLICY_VERSION_MINIMUM=3.25
export DEPS_BUILD_TYPE=Debug # Or Release/RelWithDebInfo/MinSizeRel, as needed
export cache_dir

./run_conan.sh
</pre>

with <code>RUNNER_OS</code>, <code>RUNNER_ARCH</code> in:
* <code>Linux</code> / <code>X64</code>
* <code>Windows</code> / <code>X64</code>
* <code>macOS</code> / <code>X64</code>
* <code>macOS</code> / <code>ARM64</code>
reflecting your build platform.

No detection is made (compiler, OS, arch...) . You'll have to do it on your own and set environment variables accordingly.

==== Cleaning ====

Conan will produce a bunch of scripts in the root of LuxCoreDeps repo. You can clean them with the following:
<pre> ./utils/clean-conan-files.sh </pre>

=== Local Continuous Integration ===

Run <code>act</code> on workflows located in <code>.github/workflows</code> folder, for instance <code>.github/workflows/build.yml</code> workflow.

For more convenience, a wrapper script is also provided in <code>LuxCoreDeps</code> repository (Linux only, at the moment): <pre>./utils/local-CI-build.sh</pre>

=== Server Continuous Integration ===

This process relies on the following Github workflow: [https://github.com/LuxCoreRender/LuxCoreDeps/actions/workflows/checker.yml <code>LuxCore Dependency Checker</code>].
Important points:
* Your changes must have been committed and pushed to repository before.
* The Checker workflow is actually also triggered on push event, so you may not have to run it by yourself

If build succeeds, you will find the expected outputs in Artifacts section of the action run.

== Build LuxCore, Samples & Python Wheels ==

=== Local Plain Build ===

==== Prerequisites ====

First, we will assume you have correctly completed the [[#Prerequisites_2 | Prerequisites]].

Second, we will also assume you've already git-cloned LuxCore on your local machine, opened a terminal, changed directory to LuxCore folder and git-checked out the branch that you want to build (+ for Windows: initialized build environment with <code>vcvarsall.bat</code>)

==== Basic build ====

Our build system internally relies on <code>cmake</code> but, for more convenience, everything has been wrapped into <code>make</code>-like statements.

So, to build LuxCore, one just have to enter the following magic words:
<pre>
make deps
make
</pre>

This should retrieve and install LuxCore dependencies, configure the project and run the build. That's all!

For subsequent builds, if no modification have been made to dependencies, you'll just have to re-enter: <pre>make</pre>

==== Specific targets ====

If you want to target a specific component, you can replace the above plain <code>make</code> by one of the following verbs:
<pre>make luxcore</pre>
<pre>make pyluxcore</pre>
<pre>make luxcoreui</pre>
<pre>make luxcoreconsole</pre>

Starting from version 2.11, this method can build a "test wheel". This is a simplified wheel, only for current platform and current Python version, for testing purpose. The test wheel is particularly useful for developing/debugging LuxCore/BlendLuxCore integration.
The verb is:
<pre>make wheel-test</pre>

You can also build Doxygen documentation with the following statement:
<pre>make doc</pre>

==== Build type ====

By default, this method builds a release version, striped from all symbols. If you want to build a debug version, enter the following before any <code>make ...</code> command:

<pre>export LUX_BUILD_TYPE=Debug</pre>

==== Local dependency set ====

It is possible to use a local dependency set, rather than relying on automatic downloading. It is especially useful for developing/debugging of LuxCoreDeps/LuxCore integration. In this case, one can replace the <code>make deps</code> statement by the following one:

<pre>
python -m build-system.luxmake.deps --local <path/to/local/deps> --release <release>
</pre>

Nota: <code><release></code> is the release tag used by your local dependency set. If you build this set locally, it should likely be <code>test</code>.

==== Cleaning ====

You can remove build outputs with one of the following statement:
<pre>make clean</pre>
or
<pre>make clear</pre>
The former will remove build files, however preserving dependencies.
The latter will remove everything and will require to reinstall dependencies (<code>make deps</code>).

=== Local Continuous Integration ===

This method is complementary to Local plain build, with the following additional capabilities:
* test the LuxCore build in an environment close to the release environment (manylinux container, for instance)
* can build wheels
* debug any changes made to the build workflow

It consists in running Github workflows locally, via <code>act</code>. Github workflows are located in <code>.github/workflows</code> folder.

<code>act</code> invokation can be made on command line but, for convenience, a wrapper script is provided (for Linux): <pre>./build-helpers/debug/debug_wheels.sh</pre>

Caveat: this build can produce wheels, but only for the host platform (no cross-compiling).

=== Server Continuous Integration ===

The process is nearly the same as publisher build, but the release steps are skipped. For that purpose, another Github workflow has to be executed: [https://github.com/LuxCoreRender/LuxCore/actions/workflows/wheel-builder.yml <code>LuxCore Python Wheels Builder</code>].

Please note that your changes must have been committed to repository before running the workflow.

If build succeeds, you will find the expected outputs in Artifacts section of the action run.

= Publisher Workflows =

== Prerequisites ==

For these workflows, a Github account is required, with extended rights on the source repositories.

== General Workflow ==

The general workflow for publishing is in 3 parts:

{{#mermaid:

%%{ init: {
'theme': 'neutral',
'flowchart': { 'curve': 'monotoneX' }
}
}%%
flowchart TD;
subgraph Build["<center>BUILD & RELEASE DRAFT (Run Releaser workflow)</center>"]
padBuild(" "):::INVISIBLE
repo("Go to <code>[Source repository]</code> on Github and open <code>Actions menu</code>")
select("Select <code>[Releaser workflow]</code>")
runwf(Click on <code>Run workflow</code> button, in the upper-right corner)
branch(Select <code>Branch</code> in drop-down menu)
options(Set workflow options)
validate(Click <code>Run workflow</code>)
wait(Wait for build to complete)
end

subgraph Release["<center>MAKE FINAL RELEASE(Switch release to final status)</center>"]
padRelease(" "):::INVISIBLE
release("Open <code>[Release folder]</code>, find the newly-built release (in Draft mode) and edit it")
complete(Add relevant information: change log, comments on version etc.)
dedraft(Unset <code>Draft</code> checkbox)
update(Click <code>Publish release</code>/<code>Update release</code> to finalize)
end

subgraph Deploy["<center>PUBLISH(Run Publisher workflow)</center>"]
padDeploy(" ")
repoDeploy("Go to <code>[Source repository]</code> on Github and open <code>[Actions menu]</code>")
selectDeploy("Select <code>[Publisher workflow]</code>")
runwfDeploy("Click on <code>Run workflow</code> drop-down button, in the upper-right corner")
choiceDeploy("Select <code>Branch</code>, set the <code>Tag to publish</code> and uncheck <code>Publish on Pypi Test</code> if needed")
validateDeploy("Click on <code>Run workflow</code> button")
waitDeploy("Wait for deployment to complete")
end

padBuild---repo
repo-->select
select-->runwf
runwf-->branch
branch-->options
options-->validate
validate-->wait:::WAIT
linkStyle 0 stroke:#fff,stroke-width:0px,color:blue;

padRelease---release
release-->complete
complete-->dedraft
dedraft-->update
linkStyle 7 stroke:#fff,stroke-width:0px,color:blue;

padDeploy:::INVISIBLE---repoDeploy
repoDeploy-->selectDeploy
selectDeploy-->runwfDeploy
runwfDeploy-->choiceDeploy
choiceDeploy-->validateDeploy
validateDeploy-->waitDeploy:::WAIT
linkStyle 11 stroke:#fff,color:blue,stroke-width:0px;

Build-- if success -->Release
Release-- if success & if needed -->Deploy

classDef WAIT fill:#ddd;
classDef DEPS fill:#e4d8ff,stroke:#9488af;
classDef INVISIBLE fill:#ffffffff,stroke:#ffffffff,stroke-width:0px,font-color:#ffffffff;
classDef OPTIONAL stroke-dasharray: 5 5;

class Deploy OPTIONAL;

%% Note: padXXX is a poor hack to create a top-margin in subgraph...
}}

A few comments:
* <code>[bracketed tokens]</code> refer to data specific to each component, which will be detailed below.
* Publish part is optional, it will depends on the target
* ''Caveat: if you provide an already-existing release version number during the process, the workflow will replace the existing release with the newly-built one. This can be what you expected... or not. Be cautious.''

== Per-target details ==

=== External Dependencies ===

* Source repository: [https://github.com/LuxCoreRender/LuxCoreDeps <code>LuxCoreRender/LuxCoreDeps</code>]
* Releaser workflow: [https://github.com/LuxCoreRender/LuxCoreDeps/actions/workflows/release.yml <code>LuxCore Dependency Releaser</code>]
* Release folder: [https://github.com/LuxCoreRender/LuxCoreDeps/releases <code>Releases</code>]
* Publisher workflow: ∅

As a byproduct, External Dependencies are not intended to be deployed, so no Publisher workflow is provided.

=== Python Wheels ===

As far as wheels are concerned, in addition to building them, it is also necessary to upload them to [https://pypi.org/ PyPi] ("publish" them), so that they are available for [https://pypi.org/project/pip pip] installation.

* Source repository: [https://github.com/LuxCoreRender/LuxCore <code>LuxCoreRender/LuxCore</code>]
* Releaser workflow: [https://github.com/LuxCoreRender/LuxCore/actions/workflows/wheel-releaser.yml <code>LuxCore Wheels Releaser</code>]
* Release folder: [https://github.com/LuxCoreRender/LuxCore/releases <code>Releases</code>]
* Publisher workflow: [https://github.com/LuxCoreRender/LuxCore/actions/workflows/wheel-publisher.yml <code>LuxCore Wheels Publisher</code>]

''Prerequisite: you must have released a compatible version of External Dependencies (LuxCoreDeps) before building Python Wheels.''

=== Samples ===

As we plan to replace Samples by equivalent Python tools and thus deprecate them, the workflow has been limited to the Release part (no publish).

* Source repository: [https://github.com/LuxCoreRender/LuxCore <code>LuxCoreRender/LuxCore</code>]
* Releaser workflow: [https://github.com/LuxCoreRender/LuxCore/actions/workflows/sample-releaser.yml <code>LuxCore Samples Releaser</code>]
* Release folder: [https://github.com/LuxCoreRender/LuxCore/releases <code>Releases</code>]
* Publisher workflow: ∅

=== BlendLuxCore ===

TODO

= Version Management =

== Semantic Versioning ==

Starting for LuxCore version 2.10.0, we require that LuxCoreRender applies [https://semver.org/ Semantic Versioning]. Please strictly enforce this rule when incrementing version numbers.

Remark: component versions does not have to be synced. For instance, in strict application of the standard, the newly created LuxCoreDeps will start at 1.0.0, while at the same time LuxCore is already at 2.10.0

== Dependency Version pointer ==

To make LuxCore know which version of dependencies it must be built against, we use a pointer.

This pointer is stored in the file <code>build-helpers/build-settings.json</code>, under the path <code>Dependencies/release</code>.

Make sure you keep it up-to-date when you upgrade LuxCore components.

Building LuxCoreRender

2026-04-26T15:05:45Z

Howetuft: /* Run */

This document describes the various processes involved in building LuxCoreRender, starting with version 2.10 “Back-on-track”.

LuxCoreRender's build system has been significantly modified for version 2.10. This document therefore renders obsolete all [[Building_LuxCoreRender_(legacy)|previous documents]] related to the compilation of older versions (<=2.9).

TL;DR If you are just interested in a quick, local (but platform limited) compilation of LuxCore C++ samples or Python wheels, you may want to jump directly to [[#Build LuxCore, Samples & Python Wheels | Build LuxCore, Samples & Python Wheels]].

= Audience =

This document is intended for:
* LuxCoreRender administrators in charge of releasing the various LuxCoreRender end-products;
* Developers wishing to contribute to the project;
* External package maintainers wishing to integrate all or part of LuxCoreRender into a distribution;

This document assumes that the reader is skilled in the following areas:
* C/C++ compilation
* [https://cmake.org/ cmake]
* [https://git-scm.com/ git]
* [https://docs.github.com/en/actions/writing-workflows Github Workflows]
* [https://packaging.python.org/en/latest/ Python Packaging], including [https://realpython.com/python-wheels/ Python Wheels format]

Familiarity with [https://conan.io/ Conan] dependency manager may also help.


This document is not intended for end-users without any knowledge about application building. Such users are invited to look for already compiled binaries on the official [https://luxcorerender.org/download/ Download] page.

= Build Targets =

== Synoptic ==
LuxCoreRender contains several build targets, below represented with dependency links:

{{#mermaid:
%%{
init: {
"theme": "forest",
"logLevel": "info",
"flowchart": {"curve": "basis"}
}
}%%

flowchart LR;

classDef TYPE font-weight:bold,font-size:1.1rem;
classDef TARGET font-weight:bold,font-size:0.9rem;

classDef LUXCOREDEPS fill:#ffe8ff,stroke:#9488af,font-weight:bold,font-size:1.1rem;
classDef TARGETDEPS fill:#e4d8ff,stroke:#9488af,font-weight:bold,font-size:0.9rem;

classDef LUXCORE fill:#bbceff,font-weight:bold,font-size:1.1rem,stroke:#999999;
classDef TARGETLUXCORE fill:#7799ee,font-weight:bold,font-size:0.9rem,stroke:#999999;

classDef SAMPLES fill:#ffffdd,font-weight:bold,font-size:1.1rem,stroke:#999999;
classDef TARGETSAMPLES fill:#eeeecc,font-weight:bold,font-size:0.9rem,stroke:#999999;

classDef NEUTRAL fill:#fafafa,font-weight:bold,font-size:1.1rem,stroke:#999999;
classDef TARGETNEUTRAL fill:#eeeeee,font-weight:bold,font-size:0.9rem,stroke:#999999;

classDef EXTDEP fill:#00000000,stroke:#00000000;

subgraph Dependencies[External Dependencies]
deps(LuxCore Dependencies)
end

class Dependencies LUXCOREDEPS;
class deps TARGETDEPS;

subgraph LuxCore
lux(luxcore.so/.dll)
luxa(luxcore.a)
end
class LuxCore LUXCORE;
class lux TARGETLUXCORE;
class luxa TARGETLUXCORE;

subgraph Python_Wheels[Python Wheels]
pylux(pyluxcore.so/.dll)
wheels(LuxCore Python Wheels)
end
class Python_Wheels TYPE;
class pylux TARGET;
class wheels TARGET;

subgraph Samples
luxcoreui(luxcoreui)
luxcoreconsole(luxcoreconsole)
end
class Samples SAMPLES;
class luxcoreui TARGETSAMPLES;
class luxcoreconsole TARGETSAMPLES;

subgraph PyLuxCoreTools
pyluxcon(pyluxcoreconsole)
pyluxothers(...)
end
class PyLuxCoreTools NEUTRAL;
class pyluxcon TARGETNEUTRAL;
class pyluxothers TARGETNEUTRAL;

subgraph Plugins[Python Plugins]
blc(BlendLuxCore)
otherplugins(...)
end
class blc TARGETNEUTRAL;
class otherplugins TARGETNEUTRAL;

class Plugins NEUTRAL;

%% Warning: order matters
deps-->lux
deps-->luxa
deps-->luxcoreui
deps-->luxcoreconsole

luxa--->pylux
lux-->luxcoreui
lux-->luxcoreconsole
deps-->pylux

pylux-->wheels
wheels-. runtime .->blc
wheels-. runtime .->otherplugins

wheels-. runtime .->pyluxcon
wheels-. runtime .->pyluxothers

Python:::EXTDEP-->pylux

%% Mermaid version: 8.14.0
%% https://github.com/mermaid-js/mermaid/blob/8.14.0/src/defaultConfig.js

}}

{| class="wikitable" style="margin:auto"
|-
! Target !! Source Repository !! Content
|-
| External Dependencies|| [https://github.com/LuxCoreRender/LuxCoreDeps <code>LuxCoreDeps</code>] || A bundled Conan cache populated with LuxCoreRender external dependency binaries, built from sources. Please refer to [https://github.com/LuxCoreRender/LuxCoreDeps/blob/main/README.md LuxCoreDeps README] for more information.
|-
| LuxCore || [https://github.com/LuxCoreRender/LuxCore <code>LuxCore</code>] || LuxCore core binaries, in the form of static and shared libraries: luxcore.so, luxcore_static.lib, luxcore.dll etc.
|-
| Samples|| [https://github.com/LuxCoreRender/LuxCore <code>LuxCore</code>] || Sample C++ programs, illustrating luxcore use, namely <code>luxcoreconsole</code> and <code>luxcoreui</code>
|-
| Python Wheels|| [https://github.com/LuxCoreRender/LuxCore <code>LuxCore</code>] || Python bindings of core binaries, in the form of Python wheels (1 per pair Platform/Python version). As a byproduct, a Pythonized version of LuxCore shared library is also built (pyluxcore.so).
|-
| Python Plugins|| [https://github.com/LuxCoreRender/BlendLuxCore <code>BlendLuxCore</code>] etc. || Plugins to expose LuxCore in various external applications, notably Blender. Written in Python and relying on Python Wheels as runtime dependency.
|-
| PyLuxCoreTools|| [https://github.com/LuxCoreRender/LuxCore <code>LuxCore</code>] || Python LuxCore Tools: set of command line tools based on pyluxcore, written in Python.
|}

== Targeted platforms ==

LuxCoreRender aims at being available on the following 4 platforms:
* Linux (glibc 2.28+)
* Windows
* MacOS Intel (>=10.15)
* MacOS Arm (>=12.0)

For Python-related targets, LuxCoreRender aims at being declined for [https://devguide.python.org/versions all Python versions supported at a given time].

= Workflow Types =

We distinguish between two types of build workflows:
* Developer workflows
* Publisher workflows

''[[#Developer Workflows | Developer workflows]]'' are designed for development, debugging and test steps.

Their purpose is to allow development and verify the code is ready for publication.

''[[#Publisher Workflows | Publisher workflows]]'' are designed to be used by LuxCoreRender administrators to publish a new release of one or more LuxCoreRender components.

They exclusively take place in a CI/CD Github pipeline.

These workflows are not designed for debugging or testing the underlying code. Execution of these workflows assumes that the development phase has been correctly completed and the underlying code is ready for final build and release. See [[#Developer Workflows | Developer Workflows]] to learn how to get code ready for final build.

Running these workflows require users to be granted of extended rights on LuxCoreRender repositories.

= Developer Workflows =

== Prerequisites ==

Tools

You will need several build tools installed and referenced in the PATH.

First, ensure you have a suitable toolchain:

{| class="wikitable" style="margin:auto"
|-
! OS !! Compiler !! Minimal version
|-
| Windows || MSVC || 194x latest version
|-
| Linux|| gcc || 14
|-
| MacOS Intel|| XCode + llvm + libomp || llvm >= 20 (<code>brew install llvm && brew install libomp</code>)
|-
| MacOS Arm || XCode + llvm + libomp || llvm >= 20 (<code>brew install llvm && brew install libomp</code>)
|}

''Toolchain compliance is a very sensitive condition for a successful build. Before filing any claim, please check that your toolchain complies with the above requirements.''

Then ensure the following software is also installed and available in your PATH:

* [https://git-scm.com/ Git]
* [https://cli.github.com/ Github CLI] (optional but recommended - for dependency signature checking)
* [https://www.python.org/ Python 3] - any [https://devguide.python.org/versions/ currently supported version]
* [https://conan.io Conan] latest version (pip install conan)
* [https://github.com/pypa/wheel/tree/main Wheel] latest version (pip install wheel)
* [https://cmake.org/ CMake] >= 3.29
* [https://github.com/nektos/act nektos/act] (optional but recommended - for local build based on Github workflows)
* [https://pypi.org/project/repairwheel repairwheel] (optional but recommended - for local build of test wheels)

Platform specifics:
* For Windows, ensure the command line is configured for building (<code>vcvarsall.bat</code>).
* For Linux, you'll need <code>pkgconfig</code> in addition.
* For MacOS, you'll need to ensure CC and CXX point to LLVM clang/clang++

Accounts

A ''Github account'' is mandatory for LuxCore development.

Following accounts are also recommended, in order to get in touch with LuxCore community:
* [https://forums.luxcorerender.org/ LuxCoreRender Forums]
* [https://discord.gg/chPGsKV LuxCoreRender Discord channel]

== General Developer Workflow ==

To compile and verify LuxCore component modifications in development process, there are 3 stages:
* Local plain build: only run build system (cmake) on developer computer
* Local Continuous Integration build: run full Continuous Integration workflow on developer computer
* Server Continuous Integration build: run full Continuous Integration workflow on server

Local plain build is generally faster than other builds and does not require to commit changes beforehand. Plain build installs a minimal build configuration (dependencies), but heavily relies on computer build environment for the rest (build tools, system libraries etc.). As a counterpart, it builds only for the platform where it is executed and can be significantly altered by local conditions (build tools local versions, dependency local versions etc.), thus not fully guaranteeing that final publish workflow will succeed.

LocalCI is generally faster than Server build, but slower than local plain build. CI workflow installs a complete build environment (compilers, sdk, build tools, containers, dependencies etc.) before running build system. It does not require to commit changes beforehand. However, it builds only for the platform where it is executed, thus not fully guaranteeing that final publish workflow will succeed.

Server CI, if successful, should guarantee success when publishing, as it occurs in conditions similar to release workflow (all platforms, complete build environment). As a counterpart, it is generally significantly slower than local builds and also implies to commit and push changes beforehand, even if the code is in unstable state.

The recommended workflow thus strives to make the most of all stages:

{{#mermaid:

%%{ init: {
'theme': 'neutral',
'flowchart': { 'curve': 'monotoneX' }
}
}%%

flowchart TD;

fork(Fork Source repository in your own Github space)
clone("Clone your fork locally<code>git clone...</code>")
devel(Make modifications in your local fork)
localBuild("Run local plain build<code>cmake</code>, <code>make</code>...")
localCI("Run local CI<code>act</code>")
git("Commit, Rebase & Push<code>git ...</code>")
serverCI(Run server CI<code>Github workflow</code>)
PR(PR your changes to Source repository)

fork-->clone
clone-->devel
devel-->localBuild
localBuild-->localCI
localCI-- "Success(including debug & tests)" -->git
git-->serverCI
serverCI-- Success -->PR

localBuild & localCI & serverCI ----> |Failure| devel

classDef BUILD fill:#acc,stroke-width:4px;
class localBuild BUILD;
class localCI BUILD;
class serverCI BUILD;

}}

This is the common process between all components. Each step will then be adapted to each component, as explained below.

Comments:
* Running local CI relies on [https://github.com/nektos/act <code>nektos/act</code>]
* Rebase must be made against upstream directory (<code>git pull --rebase upstream <branch></code>)before pushing
* Push must be made towards developer own fork. Caveat: do not try to push directly to upstream

== Build External Dependencies ==

=== Local Plain Build ===
==== Caveats ====
Dependency local plain build is possible but:
* Local plain build IS NOT THE RECOMMENDED BUILD for final deps. This build is solely intended for intermediary development and debugging. No support will be provided when used out-of-scope.
* Local plain build has only be tested on Linux, with gcc >=14. For other platforms, adaptations should be necessary (contributions welcome).
* Local plain build is much impacted by local particulars (local compiler version, dependencies already in cache or in system dirs etc.) and therefore does not guarantee further success for other (recommended) builds.

==== Prerequisites ====
In addition with general [[#Prerequisites_2 | Prerequisites]], you'll need the OneAPI ISPC compiler.

==== Conan cache interaction ====

The build relies on the local Conan cache, which will be modified by the process. You may want to make a copy beforehand.

In some scenarios, you may also want to reset your Conan cache (warning: may remove files unrelated to LuxCoreDeps):
<pre>conan remove -c "*" # Be careful: may remove packages unrelated to LuxCoreDeps!</pre>

==== Run ====

To run a plain local build, run the following statements in a console, from the root of LuxCoreDeps repository:

<pre>
export RUNNER_OS=<os>
export RUNNER_ARCH=<arch>

export LUXDEPS_VERSION=test
export GCC_VERSION=14 # Note: even for gcc > 14
export WORKSPACE=.
export CXX_VERSION=20
export CMAKE_POLICY_VERSION_MINIMUM=3.25
export DEPS_BUILD_TYPE=Debug # Or Release/RelWithDebInfo/MinSizeRel, as needed
export cache_dir

./run_conan.sh
</pre>

with <code>RUNNER_OS</code>, <code>RUNNER_ARCH</code> in:
* <code>Linux</code> / <code>X64</code>
* <code>Windows</code> / <code>X64</code>
* <code>macOS</code> / <code>X64</code>
* <code>macOS</code> / <code>ARM64</code>
reflecting your build platform.

No detection is made (compiler, OS, arch...) . You'll have to do it on your own and set environment variables accordingly.

==== Cleaning ====

Conan will produce a bunch of scripts in the root of LuxCoreDeps repo. You can clean them with the following:
<pre> ./utils/clean-conan-files.sh </pre>

=== Local Continuous Integration ===

Run <code>act</code> on workflows located in <code>.github/workflows</code> folder, for instance <code>.github/workflows/build.yml</code> workflow.

For more convenience, a wrapper script is also provided in <code>LuxCoreDeps</code> repository (Linux only, at the moment): <pre>./utils/local-CI-build.sh</pre>

=== Server Continuous Integration ===

This process relies on the following Github workflow: [https://github.com/LuxCoreRender/LuxCoreDeps/actions/workflows/checker.yml <code>LuxCore Dependency Checker</code>].
Important points:
* Your changes must have been committed and pushed to repository before.
* The Checker workflow is actually also triggered on push event, so you may not have to run it by yourself

If build succeeds, you will find the expected outputs in Artifacts section of the action run.

== Build LuxCore, Samples & Python Wheels ==

=== Local Plain Build ===

==== Prerequisites ====

First, we will assume you have correctly completed the [[#Prerequisites_2 | Prerequisites]].

Second, we will also assume you've already git-cloned LuxCore on your local machine, opened a terminal, changed directory to LuxCore folder and git-checked out the branch that you want to build (+ for Windows: initialized build environment with <code>vcvarsall.bat</code>)

==== Basic build ====

Our build system internally relies on <code>cmake</code> but, for more convenience, everything has been wrapped into <code>make</code>-like statements.

So, to build LuxCore, one just have to enter the following magic words:
<pre>
make deps
make
</pre>

This should retrieve and install LuxCore dependencies, configure the project and run the build. That's all!

For subsequent builds, if no modification have been made to dependencies, you'll just have to re-enter: <pre>make</pre>

==== Specific targets ====

If you want to target a specific component, you can replace the above plain <code>make</code> by one of the following verbs:
<pre>make luxcore</pre>
<pre>make pyluxcore</pre>
<pre>make luxcoreui</pre>
<pre>make luxcoreconsole</pre>

Starting from version 2.11, this method can build a "test wheel". This is a simplified wheel, only for current platform and current Python version, for testing purpose. The test wheel is particularly useful for developing/debugging LuxCore/BlendLuxCore integration.
The verb is:
<pre>make wheel-test</pre>

You can also build Doxygen documentation with the following statement:
<pre>make doc</pre>

==== Build type ====

By default, this method builds a release version, striped from all symbols. If you want to build a debug version, enter the following before any <code>make ...</code> command:

<pre>export LUX_BUILD_TYPE=Debug</pre>

==== Local dependency set ====

It is possible to use a local dependency set, rather than relying on automatic downloading. It is especially useful for developing/debugging of LuxCoreDeps/LuxCore integration. In this case, one can replace the <code>make deps</code> statement by the following one:

<pre>
python -m build-system.luxmake.deps --local <path/to/local/deps> --release <release>
</pre>

Nota: <code><release></code> is the release tag used by your local dependency set. If you build this set locally, it should likely be <code>test</code>.

==== Cleaning ====

You can remove build outputs with one of the following statement:
<pre>make clean</pre>
or
<pre>make clear</pre>
The former will remove build files, however preserving dependencies.
The latter will remove everything and will require to reinstall dependencies (<code>make deps</code>).

=== Local Continuous Integration ===

This method is complementary to Local plain build, with the following additional capabilities:
* test the LuxCore build in an environment close to the release environment (manylinux container, for instance)
* can build wheels
* debug any changes made to the build workflow

It consists in running Github workflows locally, via <code>act</code>. Github workflows are located in <code>.github/workflows</code> folder.

<code>act</code> invokation can be made on command line but, for convenience, a wrapper script is provided (for Linux): <pre>./build-helpers/debug/debug_wheels.sh</pre>

Caveat: this build can produce wheels, but only for the host platform (no cross-compiling).

=== Server Continuous Integration ===

The process is nearly the same as publisher build, but the release steps are skipped. For that purpose, another Github workflow has to be executed: [https://github.com/LuxCoreRender/LuxCore/actions/workflows/wheel-builder.yml <code>LuxCore Python Wheels Builder</code>].

Please note that your changes must have been committed to repository before running the workflow.

If build succeeds, you will find the expected outputs in Artifacts section of the action run.

= Publisher Workflows =

== Prerequisites ==

For these workflows, a Github account is required, with extended rights on the source repositories.

== General Workflow ==

The general workflow for publishing is in 3 parts:

{{#mermaid:

%%{ init: {
'theme': 'neutral',
'flowchart': { 'curve': 'monotoneX' }
}
}%%
flowchart TD;
subgraph Build["<center>BUILD & RELEASE DRAFT (Run Releaser workflow)</center>"]
padBuild(" "):::INVISIBLE
repo("Go to <code>[Source repository]</code> on Github and open <code>Actions menu</code>")
select("Select <code>[Releaser workflow]</code>")
runwf(Click on <code>Run workflow</code> button, in the upper-right corner)
branch(Select <code>Branch</code> in drop-down menu)
options(Set workflow options)
validate(Click <code>Run workflow</code>)
wait(Wait for build to complete)
end

subgraph Release["<center>MAKE FINAL RELEASE(Switch release to final status)</center>"]
padRelease(" "):::INVISIBLE
release("Open <code>[Release folder]</code>, find the newly-built release (in Draft mode) and edit it")
complete(Add relevant information: change log, comments on version etc.)
dedraft(Unset <code>Draft</code> checkbox)
update(Click <code>Publish release</code>/<code>Update release</code> to finalize)
end

subgraph Deploy["<center>PUBLISH(Run Publisher workflow)</center>"]
padDeploy(" ")
repoDeploy("Go to <code>[Source repository]</code> on Github and open <code>[Actions menu]</code>")
selectDeploy("Select <code>[Publisher workflow]</code>")
runwfDeploy("Click on <code>Run workflow</code> drop-down button, in the upper-right corner")
choiceDeploy("Select <code>Branch</code>, set the <code>Tag to publish</code> and uncheck <code>Publish on Pypi Test</code> if needed")
validateDeploy("Click on <code>Run workflow</code> button")
waitDeploy("Wait for deployment to complete")
end

padBuild---repo
repo-->select
select-->runwf
runwf-->branch
branch-->options
options-->validate
validate-->wait:::WAIT
linkStyle 0 stroke:#fff,stroke-width:0px,color:blue;

padRelease---release
release-->complete
complete-->dedraft
dedraft-->update
linkStyle 7 stroke:#fff,stroke-width:0px,color:blue;

padDeploy:::INVISIBLE---repoDeploy
repoDeploy-->selectDeploy
selectDeploy-->runwfDeploy
runwfDeploy-->choiceDeploy
choiceDeploy-->validateDeploy
validateDeploy-->waitDeploy:::WAIT
linkStyle 11 stroke:#fff,color:blue,stroke-width:0px;

Build-- if success -->Release
Release-- if success & if needed -->Deploy

classDef WAIT fill:#ddd;
classDef DEPS fill:#e4d8ff,stroke:#9488af;
classDef INVISIBLE fill:#ffffffff,stroke:#ffffffff,stroke-width:0px,font-color:#ffffffff;
classDef OPTIONAL stroke-dasharray: 5 5;

class Deploy OPTIONAL;

%% Note: padXXX is a poor hack to create a top-margin in subgraph...
}}

A few comments:
* <code>[bracketed tokens]</code> refer to data specific to each component, which will be detailed below.
* Publish part is optional, it will depends on the target
* ''Caveat: if you provide an already-existing release version number during the process, the workflow will replace the existing release with the newly-built one. This can be what you expected... or not. Be cautious.''

== Per-target details ==

=== External Dependencies ===

* Source repository: [https://github.com/LuxCoreRender/LuxCoreDeps <code>LuxCoreRender/LuxCoreDeps</code>]
* Releaser workflow: [https://github.com/LuxCoreRender/LuxCoreDeps/actions/workflows/release.yml <code>LuxCore Dependency Releaser</code>]
* Release folder: [https://github.com/LuxCoreRender/LuxCoreDeps/releases <code>Releases</code>]
* Publisher workflow: ∅

As a byproduct, External Dependencies are not intended to be deployed, so no Publisher workflow is provided.

=== Python Wheels ===

As far as wheels are concerned, in addition to building them, it is also necessary to upload them to [https://pypi.org/ PyPi] ("publish" them), so that they are available for [https://pypi.org/project/pip pip] installation.

* Source repository: [https://github.com/LuxCoreRender/LuxCore <code>LuxCoreRender/LuxCore</code>]
* Releaser workflow: [https://github.com/LuxCoreRender/LuxCore/actions/workflows/wheel-releaser.yml <code>LuxCore Wheels Releaser</code>]
* Release folder: [https://github.com/LuxCoreRender/LuxCore/releases <code>Releases</code>]
* Publisher workflow: [https://github.com/LuxCoreRender/LuxCore/actions/workflows/wheel-publisher.yml <code>LuxCore Wheels Publisher</code>]

''Prerequisite: you must have released a compatible version of External Dependencies (LuxCoreDeps) before building Python Wheels.''

=== Samples ===

As we plan to replace Samples by equivalent Python tools and thus deprecate them, the workflow has been limited to the Release part (no publish).

* Source repository: [https://github.com/LuxCoreRender/LuxCore <code>LuxCoreRender/LuxCore</code>]
* Releaser workflow: [https://github.com/LuxCoreRender/LuxCore/actions/workflows/sample-releaser.yml <code>LuxCore Samples Releaser</code>]
* Release folder: [https://github.com/LuxCoreRender/LuxCore/releases <code>Releases</code>]
* Publisher workflow: ∅

=== BlendLuxCore ===

TODO

= Version Management =

== Semantic Versioning ==

Starting for LuxCore version 2.10.0, we require that LuxCoreRender applies [https://semver.org/ Semantic Versioning]. Please strictly enforce this rule when incrementing version numbers.

Remark: component versions does not have to be synced. For instance, in strict application of the standard, the newly created LuxCoreDeps will start at 1.0.0, while at the same time LuxCore is already at 2.10.0

== Dependency Version pointer ==

To make LuxCore know which version of dependencies it must be built against, we use a pointer.

This pointer is stored in the file <code>build-helpers/build-settings.json</code>, under the path <code>Dependencies/release</code>.

Make sure you keep it up-to-date when you upgrade LuxCore components.

Building LuxCoreRender - FAQ

2026-04-26T14:44:07Z

Howetuft: /* How can I build a sanitized version of LuxCore? */

Building LuxCoreRender - FAQ

2026-04-26T14:42:31Z

Howetuft: /* Can I generate debug information for dependencies (LuxCoreDeps)? */

Building LuxCoreRender - FAQ

2026-04-26T09:07:17Z

Howetuft: /* How can I build a sanitized version of LuxCore? */

Building LuxCoreRender - FAQ

2026-04-26T09:06:33Z

Howetuft: /* Can I build a sanitized version of LuxCore? */

Building LuxCoreRender - FAQ

2026-04-26T09:05:42Z

Howetuft:

Building LuxCoreRender - FAQ

2026-04-26T08:45:35Z

Howetuft:

Building LuxCoreRender - FAQ

2026-04-26T08:40:01Z

Howetuft: /* Can I build a sanitized version of LuxCore? */

Building LuxCoreRender - FAQ

2026-04-26T08:39:17Z

Howetuft:

Building LuxCoreRender - FAQ

2026-04-26T08:31:29Z

Howetuft: /* Can I generate debug information for dependencies (LuxCoreDeps)? */

Building LuxCoreRender - FAQ

2026-04-26T08:31:01Z

Howetuft: /* Can I generate debug information for dependencies (LuxCoreDeps)? */

Building LuxCoreRender - FAQ

2026-04-24T19:43:11Z

Howetuft: /* Can I generate debug information for dependencies (LuxCoreDeps)? */

Building LuxCoreRender - FAQ

2026-04-24T19:42:37Z

Howetuft: /* Can I generate debug information for dependencies (LuxCoreDeps)? */

Building LuxCoreRender - FAQ

2026-04-24T19:41:27Z

Howetuft: /* Can I generate debug information for dependencies (LuxCoreDeps)? */