Building LuxCoreRender

This page is under construction

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

For most targets, there are several build approaches, depending on the use case. This document therefore distinguishes 2 different build workflows.

Audience

This document is primarily intended for:

• LuxCoreRender administrators in charge of releasing the various LuxCoreRender end-products;
• Developers wishing to contribute to the project;
• 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
• Python Wheels

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.

Build Targets

Synoptics

LuxCoreRender contains multiple targets, below represented with dependency links:

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

Scope of this document

The scope of this document is:

• External Dependencies
• LuxCore
• Python Wheels
• Samples

Plugin builds are documented in dedicated wiki pages.
PyLuxCoreTools build documentation is in "TODO" state.

Build Workflows

Publisher Workflows

Introduction

These 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 #Developper 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.

External Dependencies

Caveat: if you provide an already-existing release version number during the process, this action will replace the existing release with the newly-built one. This can be what you expected... or not. Be cautious.

To build a new release of Dependencies:

Python Wheels

Standard Build

Caveat: if you provide an already-existing release version number during the process, this action will replace the existing release with the newly-built one. This can be what you expected... or not. Be cautious.

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

To build a new release of Python Wheels:

Wheels Deployment

As far as wheels are concerned, in addition to building them, it is also necessary to upload them to PyPi ("deploy" them), so that they are available for pip installation.

Prerequisite: you must have released a set of Python Wheels beforehand.

Samples

As we plan to replace Samples by Python tools, there is no Releaser workflow, just a Builder one. Releases have to be created manually, on the basis of Builder's artifacts.

Developper Workflows

Introduction

These workflows are designed for development, debugging and test steps.

Their purpose is to prepare the code for publication. To fully understand this section, we recommend you take a look at the #Publisher Workflows beforehand.

Prerequisites

You will need various tool software installed and referenced in the PATH.

First, ensure you have a suitable toolchain:

• Windows: MSVC >= 194x latest version
• Linux: gcc 14
• MacOS Intel: XCode 15.2
• MacOS Arm: XCode 15.4

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

• Git
• Github CLI (for dependency signature checking: optional, but recommended)
• Python 3
• Conan (pip install conan)
• CMake
• nektos/act

For Windows, ensure the command line is configured for building (vcvarsall.bat).

External Dependencies

To build external dependencies in development process, there are 2 options:

• Server build: run workflow on server, but without creating any release
• Local build: run workflow on local computer (user PC)

Local build is generally faster than server build and does not require to commit changes beforehand. However, it builds only for the platform where it is executed and can be slightly altered by local conditions (build tools local versions etc.).

Therefore, the recommended workflow is:

• Fork LuxCoreDeps in Github and clone your fork locally
• Make development/debugging cycles in local environment with the help of local build
• When local build is successful, commit changes, push to your Github fork and run server build (actually, the run should be triggered by push action). Check that the build succeeds for all platforms, in server conditions. If not, fix the issues and push again, till everything is ok.
• When server build succeeds, PR to LuxCore/LuxCoreDeps

Local build

This build relies on nektos/act. Thanks to this very smart tool, it is possible Github Workflows locally. See install instructions on their website.

After installation, act can be executed directly on command line: call it to run workflows located in .github/workflows folder.
For more convenience, a wrapper script is also provided in LuxCoreDeps repository: utils/debug.sh (Linux only, at the moment).

Server build

The process is nearly the same as publisher build, but the release creation steps are skipped. For that purpose, another Github workflow is executed: LuxCore Dependency Checker.
Please note that your changes must have been committed to repository beforehand.

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

LuxCore, Samples & Python Wheels

To build LuxCore, Samples & Python in a development process, there are 3 methods:

• Local build - make wrapper
• Local build - Github workflows
• Server build: run workflow on server, but without creating any release

Pros and cons of each method are summarized below:

Method	Description	Pros	Cons
Local build - make wrapper	Execute cmake statements via make wrapper	Very fast (incremental). Do not require to commit changes beforehand. Can build Samples as well	Affected by local conditions (tool versions, Python version, libc version, system deps...). Build only for local platform. Cannot build Python wheels (just LuxCore and Samples)
Local build - Github workflows	Execute Github workflow locally	Fast. More robust to local conditions (containerized). Do not require to commit changes beforehand. Can build Python Wheel	Slower than make wrapper (rebuild all every time). Build only for local platform. Can be slightly affected by local conditions
Server build	Execute Github workfow on server, without issuing a release	Build in Release environment, for all platforms and all Python versions	Slow. Requires to commit changes beforehand.

Therefore the recommended workflow is:

Local build - make wrapper

This is the main method for development/debug cycles. After having cloned LuxCoreRender/LuxCore, open a command line, cd to LuxCore folder, check out the branch that you want to build and, in command line, enter this magic statement:

make deps && make

(Caveat: on Windows, build environment must have been initialized.)

This should retrieve and install LuxCore dependencies, configure the project and trigger the build. Note that, behind the scene, most of work is done by cmake and Python. In subsequent calls, if no modification have been made to dependencies, you'll just have to 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 verb:

• make doc

And you can remove build outputs with the following verbs:

• make clean
• make clear

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

Local build - Github workflows

This method is complementary to Local build - make wrapper.

It allows:

• to test the LuxCore build in an environment close to the release environment (manylinux container)
• to build wheels locally
• to debug any changes made to the build workflow

It consists in running the Github workflow locally, via act. act invokation can be made on command line but, for convenience, a wrapper script is provided: build-helpers/debug/debug_wheels.sh.

Server build - Github workflows

The process is nearly the same as release build, but the release creation steps are skipped. For that purpose, another Github workflow is executed: LuxCore 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.

Miscellaneous

TODO Python Wheels: Pointer to deps Semantic Versioning