跳转至主要内容
>>
>>
Version: v1.6.0

开发者安装指南

目标受众

对编译器、计算机图形或高性能计算感兴趣， 并想要为 Taichi编程语言 贡献新功能或修复漏洞的开发者。

IMPORTANT

本安装指南不适用于只想进行模拟或高性能数字计算的终端用户。 We recommend that end users install Taichi via pip install taichi. There is no need for you to build Taichi from source.

参阅 起步，了解终端用户如何快速设置 Taichi 的更多信息。

简介

本安装指南涵盖以下内容：

note

安装指导因操作系统（OS）而异。 在继续阅读前选择正确的操作系统或平台。

note

With the release of Taichi v1.6.0, a comprehensive build environment preparation script (aka. build.py or ti-build) has been introduced. This script significantly simplifies the process of configuring a suitable build or development environment.

This guide will focus on the build.py approach. If you prefer to use the conventional method, you can refer to the previous Developer Installation document.

先决条件

CategoryPrerequisites
Linux distributionAnything recent enough, e.g. Ubuntu 20.04
Python3.6+, with a usable pip(python3-pip package on Ubuntu)
Clang++Clang++ >= 10, Clang++ 15 is recommended.
libstdc++-xx-devRun apt install libstdc++-10-dev, or just install g++.

Install Compiler

Taichi supports building from source with Clang++ >= 10.0 and MSVC from VS2022.

For macOS developers, it is recommended to use AppleClang, which comes with the Command Line Tools for Xcode. You can install them by running xcode-select --install. Alternatively, you can also install Xcode.app from the Apple Store.

For Linux developers, it is recommended to install Clang using the package manager specific to your operating system. On Ubuntu 22.04, running sudo apt install clang-15 should be sufficient. For older Ubuntu distributions to use a newer version of Clang, please follow the instructions on official LLVM Debian/Ubuntu Nightly Packages.

For Windows developers, if none of the VS2022 editions are installed, build.py will automatically start a VS2022 BuildTools installer for you.

安装 LLVM

安装预编译的定制版 LLVM 二进制文件

build.py will automatically download and setup a suitable version of pre-built LLVM binaries.

Alternatively, build LLVM from source

Build LLVM 15.0.0 from source

We provide instructions here if you need to build LLVM 15.0.0 from source.

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

To actually use the compiled LLVM binaries, replace the LLVM folder in the cache directory of build.py (open with ./build.py cache) with your own version.

## 可选依赖的安装 [CUDA](https://en.wikipedia.org/wiki/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:

  1. 前往 官方网站 下载安装程序。

  2. 选择 deb（本地） 作为 安装程序类型 。

  3. 检查 CUDA 是否正确安装：

    nvidia-smi

Vulkan SDK is required to debug Taichi's Vulkan backend. build.py will automatically download and setup a suitable version of Vulkan SDK.

On Windows, Vulkan SDK requires elevated privileges to install (the installer would set several machine scope environement variables).

Ensure a working Vulkan SDK

  1. 请确保你正确安装了 GPU 供应商提供的 Vulkan 驱动程序。

    对于 Ubuntu，检查 /etc/vulkan/icd.d/ 或 /usr/share/vulkan/icd.d/ 中是否有一个名称与 GPU 供应商一致的 JSON 文件。

  2. 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, and build.py won't setup Vulkan SDK for you).

    export TAICHI_CMAKE_ARGS="$TAICHI_CMAKE_ARGS -DTI_WITH_VULKAN:BOOL=ON"

  3. Check if the SDK is properly installed: Run vulkaninfo in the build shell:

    ./build.py --shell
    vulkaninfo
## 从源代码编译 Taichi 1. Clone the Taichi repo *recursively* and build[^1]:
git clone --recursive https://github.com/taichi-dev/taichi

cd taichi

# Customize with your own needs
export TAICHI_CMAKE_ARGS="-DTI_WITH_VULKAN:BOOL=ON -DTI_WITH_CUDA:BOOL=ON"

# Uncomment if you want to use a different compiler
# export CC=/path/to/clang
# export CXX=/path/to/clang++

# export DEBUG=1 # Uncomment it if you wish to keep debug information.

# This would drop into a shell with complete build environment,
./build.py --shell

# and then you could install Taichi in development mode
python3 setup.py develop
note

Alternatively, you could build a wheel file ready for install if you don't care about the convenience provided by python develop install:

./build.py
ls dist/*.whl

  1. Try out some of the demos in the examples/ folder to see if Taichi is properly installed. 例如：

    python3 python/taichi/examples/simulation/mpm128.py
note

1Although the two commands work similarly, ./build.py --shell and python setup.py develop is recommended for you as a developer and ./build.py is more for end users. The difference is:

  • The python setup.py develop command does not actually install anything but only symbolically links the source code to the deployment directory.
  • The ./build.py command builds a wheel suitable for shipping so that you need to rerun the command and install the wheel every time the source code is modified.

The develop command serves the developers' needs better because edits to the Python files take effect immediately without the need to rerun the command. 只有在修改了项目的 C 扩展或编译文件时才需要重新运行。 See the Development Mode for more information.

List of TAICHI_CMAKE_ARGS

Flag描述Default
BUILD_WITH_ADDRESS_SANITIZERBuild with clang address sanitizerOFF
TI_BUILD_EXAMPLESBuild the C++ examplesON
TI_BUILD_RHI_EXAMPLESBuild the Unified Device API examplesOFF
TI_BUILD_TESTSBuild the C++ testsOFF
TI_WITH_AMDGPUBuild with the AMDGPU backendOFF
TI_WITH_BACKTRACEUse backward-cpp to print out C++ stack trace upon failureOFF
TI_WITH_CUDABuild with the CUDA backendON
TI_WITH_CUDA_TOOLKITBuild with the CUDA toolkitOFF
TI_WITH_C_APIBuild Taichi runtime C-API libraryON
TI_WITH_DX11Build with the DX11 backendOFF
TI_WITH_DX12Build with the DX12 backendOFF
TI_WITH_GGUIBuild with GGUIOFF
TI_WITH_GRAPHVIZGenerate dependency graphs between targetsOFF
TI_WITH_LLVMBuild with LLVM backendsON
TI_WITH_METALBuild with the Metal backendON
TI_WITH_OPENGLBuild with the OpenGL backendON
TI_WITH_PYTHONBuild with Python language bindingON
TI_WITH_STATIC_C_APIBuild static Taichi runtime C-API libraryOFF
TI_WITH_VULKANBuild with the Vulkan backendOFF
USE_LLDUse lld (from llvm) linkerOFF
USE_MOLDUse mold (A Modern Linker)OFF
USE_STDCPPUse -stdlib=libc++OFF

Design goals, behaviors and usage of build.py

Created to be dead simple

Setting up an appropriate development environment for an unfamiliar project can be quite challenging. Therefore, build.py has been created to eliminate this friction. If you find any aspect of the environment configuration process to be 'too manual' or suffered to progress, it is considered a bug. Please report such issues on GitHub.

Designed to be minimally intrusive

Nearly all the dependencies of build.py and Taichi are explicitly placed at the cache folder, which can be opened by:

./build.py cache

Or you can find it at:

操作系统Cache Folder Location
Linux && macOS~/.cache/ti-build-cache
Windows%LocalAppData%\ti-build-cache

A typical cache dir will contain sub folders below:

Sub FolderPurposeCode Responsible
bootstrapContains Python packages used by build.py itselfbootstrap.py
depsDownloaded external dependencies, before extract/installdep.py
llvm15Managed pre-built LLVM binariesllvm.py
mambaforgeManaged conda environment dedicated to build / develop Taichipython.py
sccacheCompile cachesccache.py
vulkan-1.x.xxx.xVulkan SDK locationvulkan.py

The whole cache folder can be safely removed.

build.py operates without the need for any third-party libraries to be installed, the requirements will be handled by its bootstrapping process.

note

On Debian/Ubuntu systems, apt install python3-pip is required.

caution

Behaviors considered intrusive

  1. On Ubuntu systems, there's an attempt to install missing development libraries at ospkg.py by invoking sudo apt install libxxxx-dev if a terminal is detected. It can be skipped by telling apt not to install them.

  2. Installing Vulkan SDK on Windows requires elevated privileges, and the installer will set several machine scoped environment variables (VULKAN_SDK and VK_SDK_PATH).

Choose your desired Python version, or use your own Python environment.

By default, build.py assumes that the same Python version used to invoke it will also be used for building Taichi. build.py will then create an isolated Python environment and use it for all the subsequent Python related tasks. To use a different version, please specify the desired version via --python option:

# Build a wheel
./build.py --python=3.10

# Or enter development shell
./build.py --python=3.10 --shell

If you prefer to manage Python environments yourself, you could specify --python=native, and build.py will not attempt to use a managed Python environment.

# Use your own conda
conda activate my-own-conda-env

# Build a wheel
./build.py --python=native

# Or enter development shell
./build.py --python=native --shell

Troubleshooting and debugging

没有权限

描述

输入 python3 setup.py develop 或 python3 setup.py install 后提醒 permission denied。

根本原因

在没有写入权限的情况下试图在 Python 环境下安装软件包。

Workaround

  1. python3 setup.py develop --user or python3 setup.py install --user.
  2. Install Conda and use python from within the conda environment.

make 编译失败

描述

make 编译失败并报告 fatal error: 'spdlog/XXX.h' file not found。

根本原因

在克隆 Taichi 仓库时没有使用 --recursive 标记。

Workaround

运行 git submodule update --init --recursive --depth=1。

which python 仍然返回系统的 Python 位置

描述

which python still returns the system's Python location.

Workaround

Run the following commands to enter development shell:

./build.py --shell

Frequently asked questions

我如何重新从头编译 Taichi？

  1. Clean up cache from your previous builds:

    python3 setup.py clean

  2. Uninstall the Taichi package from your Python environment:

  • python setup.py develop --uninstall, if you build Taichi using python setup.py develop.
  • pip uninstall taichi, if you build Taichi using python setup.py install.

如果我的 macOS 上没有 wget 怎么办？

  1. Install Homebrew.

  2. Use Homebrew to install wget:

    brew install wget

Still have issues?

本文有帮助吗？