Developer Installation
Target audience
Developers who are interested in the compiler, computer graphics, or high-performance computing, and would like to contribute new features or bug fixes to the Taichi programming language.
IMPORTANT
This installation guide is NOT intended for end users who only wish to do simulation or high performance numerical computation. We recommend that end users install Taichi via pip install taichi
. There is no need for you to build Taichi from source.
See the Get Started for more information on quickly setting up Taichi for end users.
Introduction
This installation guide covers the following:
- Prerequisites for building Taichi from source
- Installing optional dependencies
- Building Taichi from source
- Troubleshooting and debugging
- Frequently asked questions
note
Installation instructions vary depending on which operating system (OS) you are using. Choose the right OS or platform before you proceed.
Prerequisites
- Linux/Mac
- Windows
Category | Prerequisites |
---|---|
OS | macOS / Ubuntu / Arch Linux / Other Linux distributions |
Python | 3.7/3.8/3.9/3.10 We recommend installing Python from Miniforge conda if you are on a MacBook with M1 chip. |
Clang++ | Clang++ >8 |
LLVM | 15.0.4 (Taichi customized version) |
Command line tools for Xcode | For macOS users only: xcode-select --install |
Category | Prerequisites |
---|---|
OS | Windows 7/8/10/11 |
Python | 3.7/3.8/3.9/3.10 |
Clang++ | Clang++ >8 |
LLVM | 15.0.4 (Taichi customized version) |
Visual Studio | Visual Studio 2019/2022 with "Desktop Development with C++" component. If you want to use Clang++ as the compiler, also install "C++ Clang Compiler for Windows" component |
Install Clang
Taichi supports building from source with any clang compiler greater than version 8.0. Install one from your favorite package tool for the operating system. For example, you can use
apt
on Ubuntu,brew
on macOS, and so on.
Install LLVM
Install pre-built, customized LLVM binaries
We provide pre-built, customized LLVM 15 binaries.
- Download and install customized binaries from the following list per your system environment:
- LLVM 15 for Linux
- LLVM 15 for macOS (without M1 chip)
- LLVM 15 for macOS (with M1 chip)
- LLVM 15 for Windows
- Configure environment variable:
- Linux & macOS
- Windows
Set
LLVM_DIR
environment variable:echo "export LLVM_DIR=<PATH_TO_LLVM_FOLDER>" >> ~/.bashrc
Update your path for the remainder of the session:
source ~/.bashrc
Add an environment variable LLVM_DIR
with value <Path to the extracted LLVM binary>
Build LLVM 15.0.0 from source
We provide instructions here if you need to build LLVM 15.0.0 from source.
- Linux & macOS
- Windows
wget https://github.com/llvm/llvm-project/archive/refs/tags/llvmorg-15.0.5.tar.gz
tar zxvf llvmorg-15.0.5.tar.gz
cd llvm-project-llvmorg-15.0.5/llvm
mkdir build
cd build
cmake .. -DLLVM_ENABLE_RTTI:BOOL=ON -DBUILD_SHARED_LIBS:BOOL=OFF -DCMAKE_BUILD_TYPE=Release -DLLVM_TARGETS_TO_BUILD="X86;NVPTX" -DLLVM_ENABLE_ASSERTIONS=ON -DLLVM_ENABLE_TERMINFO=OFF
# If you are building on Apple M1, use -DLLVM_TARGETS_TO_BUILD="AArch64".
# If you are building on NVIDIA Jetson TX2, use -DLLVM_TARGETS_TO_BUILD="ARM;NVPTX"
# If you are building for a PyPI release, add -DLLVM_ENABLE_Z3_SOLVER=OFF to reduce the library dependency.
make -j 8
sudo make install
# Check your LLVM installation
llvm-config --version # You should get 15.0.5
# For Windows
# LLVM 15.0.0 + MSVC 2019
cmake .. -G "Visual Studio 16 2019" -A x64 -DLLVM_ENABLE_RTTI:BOOL=ON -DBUILD_SHARED_LIBS:BOOL=OFF -DCMAKE_BUILD_TYPE=Release -DLLVM_TARGETS_TO_BUILD="X86;NVPTX" -DLLVM_ENABLE_ASSERTIONS=ON -Thost=x64 -DLLVM_BUILD_TESTS:BOOL=OFF -DCMAKE_INSTALL_PREFIX=installed -DCMAKE_MSVC_RUNTIME_LIBRARY=MultiThreadedDLL -DCMAKE_CXX_STANDARD=17
cmake --build . --target=INSTALL --config=Release
- Use Visual Studio 2017+ to build LLVM.sln.
- Ensure that you use the Release configuration. After building the
INSTALL
project (under folder CMakePredefinedTargets in the Solution Explorer window). - If you use MSVC 2019+, ensure that you use C++17 for the
INSTALL
project. - When the build completes, add an environment variable
LLVM_DIR
with value<PATH_TO_BUILD>/build/installed/lib/cmake/llvm
.
Install optional dependencies
CUDA is NVIDIA's answer to high-performance computing. Taichi has implemented a backend based on CUDA 10.0.0+. Vulkan is a next-generation, cross-platform API, open standard for 3D graphics and computing. Taichi has added a Vulkan backend as of v0.8.0.
This section provides instructions on installing these two optional dependencies.
Install CUDA
This section works for you if you have a Nvidia GPU supporting CUDA. Note that the required CUDA version is 10.0+.
To install CUDA:
- Ubuntu
- Arch Linux
- Windows
Go to the official site to download the installer.
Choose deb (local) as Installer Type.
Check if CUDA is properly installed:
nvidia-smi
pacman -S cuda
Check if CUDA is properly installed:
nvidia-smi
Go to the official site and download the installer.
Choose exe (local) as Installer Type.
Check if CUDA is properly installed:
nvidia-smi
Install Vulkan
You must install the Vulkan SDK in order to debug Taichi's Vulkan backend. To proceed:
- Linux
- Windows
Go to Vulkan's SDK download page and follow the instructions for your OS.
Check if environment variables
VULKAN_SDK
,PATH
,LD_LIBRARY_PATH
, andVK_LAYER_PATH
are updated.The SDK for Ubuntu provides a
setup-env.sh
for updating these variables.Ensure that you have a Vulkan driver from a GPU vendor properly installed.
On Ubuntu, check if a JSON file with a name corresponding to your GPU vendor is in:
/etc/vulkan/icd.d/
or/usr/share/vulkan/icd.d/
.Check if the SDK is properly installed:
vulkaninfo
.If the SDK is properly installed, add an environment variable
TAICHI_CMAKE_ARGS
with the value-DTI_WITH_VULKAN:BOOL=ON
to enable the Vulkan backend: (Otherwise Vulkan backend is disabled by default when compiling from source.)export TAICHI_CMAKE_ARGS="$TAICHI_CMAKE_ARGS -DTI_WITH_VULKAN:BOOL=ON"
Go to Vulkan's SDK download page and follow the instructions for your OS.
Set the environment variable
VULKAN_SDK
toC:/VulkanSDK/${YOUR_VULKAN_VERSION}
.If the SDK is properly installed, add an environment variable
TAICHI_CMAKE_ARGS
with the value-DTI_WITH_VULKAN:BOOL=ON
to enable the Vulkan backend:$env:TAICHI_CMAKE_ARGS += " -DTI_WITH_VULKAN:BOOL=ON"
Build Taichi from source
- Linux & macOS
- Windows
Clone the Taichi repo recursively and build1:
git clone --recursive https://github.com/taichi-dev/taichi
cd taichi
python3 -m pip install --user -r requirements_dev.txt
# export CXX=/path/to/clang++ # Uncomment if clang++ is not default compiler of the system. Note that clang is not acceptable due to requirements of some submodules.
# export DEBUG=1 #Uncomment it if you wish to keep debug information.
python3 setup.py develop --userTry out some of the demos in the examples/ folder to see if Taichi is properly installed. For example:
python3 python/taichi/examples/simulation/mpm128.py
note
1Although the two commands work similarly, python setup.py develop
is recommended for you as a developer and python setup.py install
more for end users. The difference is:
- The
develop
command does not actually install anything but only symbolically links the source code to the deployment directory. - The
install
command deep copies the source code so that end users need to rerun the command every time they modify the source code.
The develop
command serves the developers' needs better because edits to the Python files take effect immediately without the need to rerun the command. A rerun is needed only if you have modified the project's C extension or compiled files. See the Development Mode for more information.
- Set-up the environment variable
TAICHI_CMAKE_ARGS
with value-DCLANG_EXECUTABLE=<Path to Clang>/bin/clang.exe -DLLVM_AS_EXECUTABLE=<Path to LLVM 15>/bin/llvm-as.exe
- Open the "x64 Native Tools Command Prompt" for VS2019 or VS2022. Please make sure you opened the x64 version. (Or load the Visual Studio environment yourself)
- Clone the Taichi repo recursively & install python dependencies
git clone --recursive https://github.com/taichi-dev/taichi
cd taichi
python -m pip install --user -r requirements_dev.txt
- Build taichi by using
python setup.py develop
note
1Although the two commands work similarly, python setup.py develop
is recommended for you as a developer and python setup.py install
more for end users. The difference is:
- The
develop
command does not actually install anything but only symbolically links the source code to the deployment directory. - The
install
command deep copies the source code so that end users need to rerun the command every time they modify the source code.
The develop
command serves the developers' needs better because edits to the Python files take effect immediately without the need to rerun the command. A rerun is needed only if you have modified the project's C extension or compiled files. See the Development Mode for more information.
note
If you want to build Taichi with Clang or maybe utilize ccache
to cache and speed-up builds, add the following to the end of environment variable TAICHI_CMAKE_ARGS
: -DCMAKE_CXX_COMPILER=clang++ -DCMAKE_C_COMPILER=clang
.
Troubleshooting and debugging
Permission denied
Description
Gets a permission denied
after python3 setup.py develop
or python3 setup.py install
.
Root cause
You were trying to install packages into the Python environment without write permission.
Workaround
python3 setup.py develop --user
orpython3 setup.py install --user
.- Install Conda and use python from within the conda environment.
make
fails to compile
Description
make
fails to compile and reports fatal error: 'spdlog/XXX.h' file not found
.
Root cause
You did not use the --recursive
flag when cloning the Taichi repository.
Workaround
Run git submodule update --init --recursive --depth=1
.
which python
still returns the system's Python location
Description
which python
still returns the system's Python location after Conda is installed.
Workaround
Run the following commands to activate Conda:
source <PATH_TO_CONDA>/bin/activate
conda init
Frequently asked questions
How can I get a fresh Taichi build?
Clean up cache from your previous builds:
python3 setup.py clean
Uninstall the Taichi package from your Python environment:
python setup.py develop --uninstall
, if you build Taichi usingpython setup.py develop
.pip uninstall taichi
, if you build Taichi usingpython setup.py install
.
What if I don't have wget
on my macOS?
Install Homebrew.
Use Homebrew to install
wget
:brew install wget
Still have issues?
See Installation Troubleshooting for issues that may share with the end-user installation.
If you encounter any issue that is not covered here, feel free to report it by opening an issue on GitHub and including the details. We are always there to help!