开发者安装指南

目标受众

对编译器、计算机图形或高性能计算感兴趣， 并想要为 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 的更多信息。

简介

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

• 从源代码编译 Taichi 的先决条件
• 可选依赖的安装
• 从源代码编译 Taichi
• Troubleshooting and debugging
• Frequently asked questions

note

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

先决条件

Linux/Mac

类型	先决条件
OS	macOS / Ubuntu / Arch Linux / 其它 Linux 发行版
Python	3.7/3.8/3.9/3.10 如果你使用搭载 M1 芯片的 MacBook，我们建议从 Miniforge conda 安装 Python。
Clang++	Clang++ >8
LLVM	15.0.4 (Taichi customized version)
Command line tools for Xcode	For macOS users only: xcode-select --install

Windows

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. 如果你想使用 Clang++ 作为编译器，请同时安装“适用于 Windows 的 C++ Clang 编译器" 组件

安装 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.

安装 LLVM

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

We provide pre-built, customized LLVM 15 binaries.

1. 根据系统环境下载并安装定制版二进制文件：

LLVM 15 for Linux

LLVM 15.0.0 for Linux

LLVM 15 for macOS (without M1 chip)

LLVM 15.0.0 for macOS (without M1 chip)

LLVM 15 for macOS (with M1 chip)

LLVM 15.0.0 for macOS (with M1 chip)

LLVM 15 for Windows

LLVM 15.0.0 for Windows MSVC 2019LLVM 15.0.0 for Windows MSVC 2022

2. 配置环境变量

Linux & macOS

1. Set LLVM_DIR environment variable:

   echo "export LLVM_DIR=<PATH_TO_LLVM_FOLDER>" >>  ~/.bashrc

2. 更新会话剩余部分的路径：

   source ~/.bashrc

Windows

添加环境变量 LLVM_DIR，值为 <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

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

Windows

# 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

1. 使用 Visual Studio 2017+ 编译 LLVM.sln。
2. 在创建 INSTALL 项目后（在方案资源管理器窗口的 CmakePredefinedTargets 文件夹下）， 确保使用 发布 配置。
3. 如果你使用的是 MSVC 2019+ 版本，确保用 C++17 进行 INSTALL 项目。
4. 编译完成后，添加一个环境变量 LLVM_DIR ，值为 <PATH_TO_BUILD>/build/installed/lib/cmake/llvm。

## 可选依赖的安装 [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:

Ubuntu

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

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

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

   nvidia-smi

Arch Linux

1. pacman -S cuda

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

   nvidia-smi

Windows

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

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

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

   nvidia-smi

安装 Vulkan

必须安装 Vulkan SDK 才能调试 Taichi 的 Vulkan 后端。 要继续安装：

Linux

1. 前往 Vulkan SDK 下载页面，根据所用操作系统，遵循相应指示。

2. 检查环境变量 VULKAN_SDK、PATH、LD_LIBRARY_PATH 和 VK_LAYER_PATH 是否已更新。

   Ubuntu 的 SDK 提供 setup-env.sh 用于更新这些变量。

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

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

4. 检查 SDK 是否已正确安装：vulkaninfo。

5. 如果 SDK 已正确安装，使用值 -DTI_WITH_VULKAN:BOOL=ON 添加一个环境变量 TAICHI_CMAKE_ARGS，以激活 Vulkan 后端：（否则在从源代码编译的情况下，默认不使用 Vulkan。）：

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

Windows

1. 前往 Vulkan SDK 下载页面，根据所用操作系统，遵循相应指示。

2. 将环境变量 VULKAN_SDK 设置为 C:/VulkanSDK/${YOUR_VULKAN_VERSION}。

3. 如果 SDK 已正确安装，使用值 -DTI_WITH_VULKAN:BOOL=ON 添加一个环境变量 TAICHI_CMAKE_ARGS，以激活 Vulkan 后端：

   $env:TAICHI_CMAKE_ARGS += " -DTI_WITH_VULKAN:BOOL=ON"

## 从源代码编译 Taichi

Linux & macOS

1. 递归克隆 Taichi 仓库，并编译[^1]：

   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 --user

2. 尝试运行 examples/ 文件夹中的一些演示，以检查 Taichi 是否已正确安装。 For example:

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

note

¹Although the two commands work similarly, python setup.py develop is recommended for you as a developer and python setup.py installmore for end users. 区别在于：

• develop 命令实际没有安装任何东西，只是象征性地把源代码链接到部署目录。
• install 命令则深复制源代码，所以终端用户每次修改源代码时都需要重新运行命令。

develop 命令更好地服务于开发者的需求，因为对 Python 文件的编辑能立即生效，无需重新运行命令。 只有在修改了项目的 C 扩展或编译文件时才需要重新运行。 详见 开发模式。

Windows

1. 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
2. 打开 VS2019 或 VS2022 的“x64 本机工具命令提示”。 请确保你打开的是 x64 版本。 (或自己加载 Visual Studio 环境)
3. 递归克隆 Taichi 仓库，并安装 Python 依赖

git clone --recursive https://github.com/taichi-dev/taichi

cd taichi

python -m pip install --user -r requirements_dev.txt

4. Build taichi by using python setup.py develop

note

¹Although the two commands work similarly, python setup.py develop is recommended for you as a developer and python setup.py installmore for end users. 区别在于：

• develop 命令实际没有安装任何东西，只是象征性地把源代码链接到部署目录。
• install 命令则深复制源代码，所以终端用户每次修改源代码时都需要重新运行命令。

develop 命令更好地服务于开发者的需求，因为对 Python 文件的编辑能立即生效，无需重新运行命令。 只有在修改了项目的 C 扩展或编译文件时才需要重新运行。 详见 开发模式。

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

没有权限

描述 输入 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 位置

描述 Conda 安装完成后，which python 仍返回系统的 Python 位置。 Workaround 运行以下命令来激活 Conda：

source <PATH_TO_CONDA>/bin/activate

conda init

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?

• 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!