Building LuxCoreRender

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 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 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
• cmake
• git
• Github Workflows
• Python Packaging, including Python Wheels format

Familiarity with 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 Download page.

Build Targets

Synoptic

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

Target	Source Repository	Content
External Dependencies	LuxCoreDeps	A bundled Conan cache populated with LuxCoreRender external dependency binaries, built from sources. Please refer to LuxCoreDeps README for more information.
LuxCore	LuxCore	LuxCore core binaries, in the form of static and shared libraries: luxcore.so, luxcore_static.lib, luxcore.dll etc.
Samples	LuxCore	Sample C++ programs, illustrating luxcore use, namely luxcoreconsole and luxcoreui
Python Wheels	LuxCore	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	BlendLuxCore etc.	Plugins to expose LuxCore in various external applications, notably Blender. Written in Python and relying on Python Wheels as runtime dependency.
PyLuxCoreTools	LuxCore	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 all Python versions supported at a given time.

Workflow Types

We distinguish between two types of build workflows:

• Developer workflows
• Publisher 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 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 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:

OS	Compiler	Minimal version
Windows	MSVC	194x latest version
Linux	gcc	14
MacOS Intel	XCode + llvm + libomp	llvm >= 20 (brew install llvm && brew install libomp)
MacOS Arm	XCode + llvm + libomp	llvm >= 20 (brew install llvm && brew install libomp)

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:

• Git
• Github CLI (optional but recommended - for dependency signature checking)
• Python 3 - any currently supported version
• Conan latest version (pip install conan)
• Wheel latest version (pip install wheel)
• CMake >= 3.29
• nektos/act (optional but recommended - for local build based on Github workflows)

Platform specifics:

• For Windows, ensure the command line is configured for building (vcvarsall.bat).
• For Linux, you'll need pkgconfig 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:

• LuxCoreRender Forums
• 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:

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 nektos/act
• Rebase must be made against upstream directory (git pull --rebase upstream <branch>)before pushing
• Push must be made towards developer own fork. Caveat: do not try to push directly to upstream

Per-target details

External Dependencies

Local Plain Build

This feature is not available yet. Meanwhile, you may use Local CI instead.

Local Continuous Integration

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

For more convenience, a wrapper script is also provided in LuxCoreDeps repository: utils/debug.sh (Linux only, at the moment).

Server Continuous Integration

This process relies on the following Github workflow: LuxCore Dependency Checker.
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.

LuxCore, Samples & Python Wheels

Local Plain Build

This method internally relies on cmake but, for more convenience, everything has been wrapped into make-like statements.

First, we assume you have correctly completed the Prerequisites.

Second, we 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 vcvarsall.bat)

From here on, just enter the magic words:

make deps
make

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:

make

If you want to target a specific component, you can also use the following verbs:

• make luxcore
• make pyluxcore
• make luxcoreui
• make luxcoreconsole

Build type can be selected by setting environment variable LUX_BUILD_TYPE. Valid values are 'Release' (default) and 'Debug'.

You can also build Doxygen documentation with the following statement:

• make doc

And you can remove build outputs with:

• make clean
• make clear

The latter will remove everything and will require to reinstall dependencies (make deps).

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 verb is:

• make wheel-test

By default, this method builds a release version, striped from all symbols. If you want to build a debug version, enter export LUX_BUILD_TYPE=Debug before any make ... command.

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 act. Github workflows are located in .github/workflows folder.

act invokation can be made on command line but, for convenience, a wrapper script is provided: build-helpers/debug/debug_wheels.sh.

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: LuxCore Python Wheels Builder.

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:

A few comments:

• [bracketed tokens] 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: LuxCoreRender/LuxCoreDeps
• Releaser workflow: LuxCore Dependency Releaser
• Release folder: Releases
• 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 PyPi ("publish" them), so that they are available for pip installation.

• Source repository: LuxCoreRender/LuxCore
• Releaser workflow: LuxCore Wheels Releaser
• Release folder: Releases
• Publisher workflow: LuxCore Wheels Publisher

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: LuxCoreRender/LuxCore
• Releaser workflow: LuxCore Samples Releaser
• Release folder: Releases
• Publisher workflow: ∅

BlendLuxCore

TODO

PyLuxCoreTools

TODO

Version Management

Semantic Versioning

Starting for LuxCore version 2.10.0, we require that LuxCoreRender applies 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 build-helpers/build-settings.json, under the path Dependencies/release.

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