Development installation#
This guide covers all steps necessary to get Eradiate running on your machine in development mode. This mode allows for easy code modifications and testing, as well as for developing on the kernel code. It requires to compile the C++ code of the Mitsuba renderer, using the Eradiate specific plugins and the appropriate variants.
Warning
Windows support is currently experimental. Please report issues on our issue tracker.
Prerequisites#
The development installation requires that the Pixi package manager is installed on the host machine. This tool replaces Conda and a lot of in-house tools that were previously maintained by the development team.
Next, make sure that your machine meets the requirements listed below:
Requirement |
Tested version |
|---|---|
git |
2.18+ |
cmake |
3.22+ |
ninja |
1.10+ |
clang (macOS and Linux) |
11+ |
MSVC (Windows) |
2022 |
Tested configuration
Operating system: Ubuntu Linux 22.04.1.
Requirement |
Tested version |
|---|---|
git |
2.34.1 |
cmake |
3.28.0 |
ninja |
1.10.1 |
clang |
11.1.0-6 |
libc++ |
11 |
libc++abi |
11 |
python |
3.9.18 |
Operating system: macOS Monterey 12.0.1.
Requirement |
Tested version |
|---|---|
git |
2.32.0 (Apple Git-132) |
cmake |
3.22.1 |
ninja |
1.10.2 |
clang |
Apple clang version 13.0.0 (clang-1300.0.29.30) |
python |
3.9.18 |
Operating system: Windows 11.
Requirement |
Tested version |
|---|---|
git |
2.43.0.windows.1 |
cmake |
3.22.1 |
ninja |
1.10.2 |
MSVC |
2022 |
python |
3.9.18 |
All prerequisites except for conda can be installed through the usual Linux package managers. For example, using the APT package manager, which is used in most Debian-based distributions, like Ubuntu:
# Install build tools, compiler and libc++
sudo apt install -y git cmake ninja-build clang-11 libc++-11-dev libc++abi-11-dev
# Install libraries for image I/O
sudo apt install -y libpng-dev zlib1g-dev libjpeg-dev
If your Linux distribution does not include APT, please consult your package manager’s repositories for the respective packages.
If your CMake copy is not recent enough, there are many ways to install an updated version, notably through pipx and Conda. Pick your favourite!
Note
We currently recommend compiling the C++ code with Clang based on upstream advice from the Mitsuba development team. We also recommend using Clang 11 — not another version — because we also encountered issues building with other versions. We hope to improve compiler support in the future.
On macOS, you will need to install XCode, CMake, and Ninja. XCode can be installed from the App Store. Make sure that your copy of the XCode is up-to-date. CMake and Ninja can be installed with the Homebrew package manager:
brew install cmake ninja
Additionally, running the Xcode command line tools once might be necessary:
xcode-select --install
On Windows, you will need to install the MSVC compiler, e.g through Visual Studio Community. In addition, you will need to install CMake. The build procedure is tested in a Powershell developer session.
Cloning the repository#
Note
Eradiate relies on the Git source code management tool. It also depends on multiple external dependencies, some of which (e.g. its radiometric kernel based on Mitsuba 3) are directly referred to using Git submodules.
To get the code, clone the repository including its submodules with the following command:
git clone --recursive https://github.com/eradiate/eradiate
git clone --recursive --branch <ref> https://github.com/eradiate/eradiate
where <ref> is a Git branch or tag. For the latest stable version, use
stable.
This will clone the Eradiate repository, as well as all its dependencies. This recursive cloning procedure can take up to a few minutes depending on your Internet connection.
Note
If GitHub requests credentials to access submodules through HTTPS, we highly recommend to generate a personal access token with repo permissions and to use it instead of your password. You might also have to make sure that Git will remember your token.
Setting up the Python environment#
Pixi maintains a lock file that allows to quickly set up a reproducible Python environment. To configure the develop environment, simply navigate to the root of the cloned repository and install it:
pixi install -e dev
Once installed, we strongly recommend to activate the Pixi environment in a shell, either by spawning a Pixi shell
pixi shell -e dev
or by activating the shell hook (discouraged by the Pixi documentation but useful in specific cases)
eval "$(pixi shell-hook -e dev)"
The Pixi documentation provides more detail about activation modes and their respective trade-offs. The reason why we recommend this is that compiling the kernel often requires setting environment variables, which is not always convenient outside of a shell. Note that this is a recommendation, not a strict requirement: Pixi also allows to set environment variables upon environment activation; we simply do not want to encourage developers to modify their project manifest file for their particular setup.
Note
Although Pixi environments are very similar to Conda environment, there are
significant differences. One of them is that the environment is not globally
available for activation. If you want to activate your development
environment from outside the project, this can be done with the
--manifest-path option of the pixi shell command:
pixi shell --manifest-path /some/directory/pyproject.toml -e dev
See the Pixi CLI documentation for details.
Compiling the radiometric kernel#
Important
It is strongly recommended to activate the Pixi environment to compile the kernel. See Setting up the Python environment for details.
We recommend using the using the dedicated Pixi task to build the kernel:
pixi run kernel-build
CMake Error: The source directory “…” does not exist
This most probably means that your CMake version is too old (see Prerequisites). Up-to-date versions of CMake can be installed from many different sources: pick you favourite.
Linux and macOS: Inspect CMake’s output to check if Clang is used as the C++ compiler. Search for lines starting with
-- The CXX compiler identification is <...>
-- The C compiler identification is <...>
-- Check for working CXX compiler: <...>
-- Check for working C compiler: <...>
These lines should clearly indicate that the currently selected compiler is Clang.
If Clang is not used by CMake …
If Clang is not used by CMake (this is very common on Linux systems, less likely on macOS), you have to explicitly define Clang as your C++ compiler. This can be achieved by modifying environment variables:
export CC=clang-11
export CXX=clang++-11
export CC=clang
export CXX=clang++
All platforms: Inspect CMake’s output to check if your Conda environment Python is used by CMake. Search for a line starting with:
-- Found Python: <...>
The content of this line may vary depending on the location of the project and your Pixi configuration. If this path points to a Python binary not associated with the target Pixi environment, but instead e.g. a global Python binary, do not proceed before fixing it.
Note
You will probably see a warning saying
Created a default ‘mitsuba.conf’ configuration file. You will probably want to edit this file to specify the desired configurations before starting to compile.
This is expected: do not worry about it.
The compilation process can last for up to around half an hour on old machines. It completes within a few minutes on modern workstations.
Verifying the installation#
In a terminal, try and invoke the eradiate command-line interface:
eradiate show
The command should print some information to the terminal. You are now ready to use Eradiate 🙂 You probably also want to download part or all of Eradiate’s built-in datasets: see the data guide for more information.
If you get a jit_cuda_compile() error …
Eradiate does not use any CUDA variant of Mitsuba. You can therefore hide your graphics card by setting
export CUDA_VISIBLE_DEVICES=""
Even doing so, you might still see a CUDA-related warning upon importing Eradiate. This is not a concern and it should be fixed in the future.