开发者安装指南¶
Note this is for the compiler developers of the Taichi programming language. End users should use the pip packages instead of building from source. To build with NVIDIA GPU support, CUDA 10.0+ is needed. This installation guide works for Ubuntu 16.04+ and OS X 10.14+. For precise build instructions on Windows, please check out appveyor.yml, which does basically the same thing as the following instructions. We use MSBUILD.exe to build the generated project. Please note that Windows could have multiple instances of MSBUILD.exe shipped with different products. Please make sure you add the path for MSBUILD.exe within your MSVS directory and make it a higher priority (for instance than the one shipped with .NET).
请注意 clang
是在Linux/OS X下唯一支持的可以编译Taichi编译器的编译器。而在Windows下只有MSVC是支持的编译器。
Installing Dependencies¶
请确认你在使用 Python 3.6/3.7/3.8
Install Python dependencies:
python3 -m pip install --user setuptools astpretty astor pybind11 Pillow dill python3 -m pip install --user pytest pytest-rerunfailures pytest-xdist yapf python3 -m pip install --user numpy GitPython coverage colorama autograd
Make sure you have
clang
with version >= 7:- On Windows: Download clang-10.
Make sure you add the
bin
folder containingclang.exe
to thePATH
environment variable. - On OS X: you don’t need to do anything.
- On Ubuntu, execute
sudo apt install libtinfo-dev clang-8
. - On Arch Linux, execute
sudo pacman -S clang
. (This isclang-10
). - On other Linux distributions, please search this site for clang version >= 7.
- On Windows: Download clang-10.
Make sure you add the
Make sure you have LLVM 10.0.0. Note that Taichi uses a customized LLVM so the pre-built binaries from the LLVM official website or other sources probably won’t work. Here we provide LLVM binaries customized for Taichi, which may or may not work depending on your system environment:
注解
On Windows, if you use the pre-built LLVM for Taichi, please add $LLVM_FOLDER/bin
to PATH
.
Later, when you build Taichi using CMake
, set LLVM_DIR
to $LLVM_FOLDER/lib/cmake/llvm
.
If the downloaded LLVM does not work, please build from source:
On Linux or OS X:
wget https://github.com/llvm/llvm-project/releases/download/llvmorg-10.0.0/llvm-10.0.0.src.tar.xz tar xvJf llvm-10.0.0.src.tar.xz cd llvm-10.0.0.src 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 # If you are building on NVIDIA Jetson TX2, use -DLLVM_TARGETS_TO_BUILD="ARM;NVPTX" make -j 8 sudo make install # Check your LLVM installation llvm-config --version # You should get 10.0.0
On Windows:
# LLVM 10.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
- Then open
LLVM.sln
and use Visual Studio 2017+ to build. - Please make sure you are using the
Release
configuration. After building theINSTALL
project (under folderCMakePredefinedTargets
in the Solution Explorer window). - If you use MSVC 2019, make sure you use C++17 for the
INSTALL
project. - After the build is complete, find your LLVM binaries and headers in
build/installed
.
Please add
build/installed/bin
toPATH
. Later, when you build Taichi usingCMake
, setLLVM_DIR
tobuild/installed/lib/cmake/llvm
.- Then open
安装并配置CUDA(可选)¶
如果你没有安装CUDA,请到 英伟达官网 下载安装器。
- 请运行
nvcc —version
或cat /usr/local/cuda/version.txt
来检查CUDA是否已安装成功。 - 在 Ubuntu 下我们推荐选择
deb (local)
来作为 安装器类型(Installer Type)。 - 在 Arch Linux 下,你可以轻松地通过
pacman -S cuda
来安装CUDA并跳过手动下载安装器的环节。
开发者的 Taichi 配置¶
Set up environment variables for Taichi:
On Linux / OS X, please add the following script to your rc file (
~/.bashrc
,~/.zshrc
or etc. , same for other occurrences in this documentation):export TAICHI_REPO_DIR=/path/to/taichi # Path to your taichi repository export PYTHONPATH=$TAICHI_REPO_DIR/python:$PYTHONPATH export PATH=$TAICHI_REPO_DIR/bin:$PATH # export CXX=/path/to/clang # Uncomment if you encounter issue about compiler in the next step. # export PATH=/opt/llvm/bin:$PATH # Uncomment if your llvm or clang is installed in /opt
Then execute
source ~/.bashrc
to reload shell config.On Windows, please add these variables by accessing your system settings:
- Add
TAICHI_REPO_DIR
whose value is the path to your taichi repository so that Taichi knows you’re a developer. - Add or append
PYTHONPATH
with%TAICHI_REPO_DIR%/python
so that Python imports Taichi from the local repo. - Add or append
PATH
with%TAICHI_REPO_DIR%/bin
so that you can useti
command. - Add or append
PATH
with path to LLVM binary directory installed in previous section.
- Add
请 递归地 克隆 Taichi 代码库,然后构建:
git clone https://github.com/taichi-dev/taichi --depth=1 --branch=master cd taichi git submodule update --init --recursive --depth=1 mkdir build cd build cmake .. # On Linux / OS X, if you do not set clang as the default compiler # use the line below: # cmake .. -DCMAKE_CXX_COMPILER=clang # # Alternatively, if you would like to set clang as the default compiler # On Unix CMake honors environment variables $CC and $CXX upon deciding which C and C++ compilers to use make -j 8
Check out
examples
for runnable examples. Run them with commands likepython3 examples/mpm128.py
.执行
python3 -m taichi test
来运行所有的测试。运行所有测试用例可能会耗费长达5分钟的时间。
Troubleshooting Developer Installation¶
If
make
fails to compile and reportsfatal error: 'spdlog/XXX.h' file not found
, please try runinggit submodule update --init --recursive --depth=1
.If importing Taichi causes
FileNotFoundError: [Errno 2] No such file or directory: '/root/taichi/python/taichi/core/../lib/taichi_core.so' -> '/root/taichi/python/taichi/core/../lib/libtaichi_core.so'``
Please try adding
TAICHI_REPO_DIR
to environment variables, see Setting up Taichi for development.If the build succeeded but running any Taichi code results in errors like
Bitcode file (/tmp/taichi-tero94pl/runtime//runtime_x64.bc) not found
, please double checkclang
is in yourPATH
:clang --version # version should be >= 7
and our Taichi configured
llvm-as
:llvm-as --version # version should be >= 8 which llvm-as # should be /usr/local/bin/llvm-as or /opt/XXX/bin/llvm-as, which is our configured installation
If not, please install
clang
and build LLVM from source with instructions above in Developer installation, then add their path to environment variablePATH
.If you encounter other issues, feel free to report by opening an issue on GitHub. We are willing to help!
See also Troubleshooting for issues that may share with end-user installation.
Docker¶
For those who prefer to use Docker, we also provide a Dockerfile which helps setup the Taichi development environment with CUDA support based on Ubuntu docker image.
注解
In order to follow the instructions in this section, please make sure you have the Docker DeskTop (or Engine for Linux) installed and set up properly.
Build the Docker Image¶
From within the root directory of the taichi Git repository, execute docker build -t taichi:latest .
to build a
Docker image based off the local master branch tagged with latest. Since this builds the image from source, please
expect up to 40 mins build time if you don’t have cached Docker image layers.
注解
In order to save the time on building Docker images, you could always visit our Docker Hub repository and pull the versions of pre-built images you would like to use. Currently the builds are triggered per taichi Github release.
For example, to pull a image built from release v0.6.17, run docker pull taichidev/taichi:v0.6.17
Use Docker Image on macOS (cpu only)¶
- Make sure
XQuartz
andsocat
are installed:
brew cask install xquartz
brew install socat
- Temporally disable the xhost access-control:
xhost +
- Start the Docker container with
docker run -it -e DISPLAY=$(ipconfig getifaddr en0):0 taichidev/taichi:v0.6.17
- Do whatever you want within the container, e.g. you could run tests or an example, try:
ti test
orti example mpm88
- Exit from the container with
exit
orctrl+D
- [To keep your xhost safe] Re-enable the xhost access-control:
xhost -
Use Docker Image on Ubuntu (with CUDA support)¶
- Make sure your host machine has CUDA properly installed and configured. Usually you could verify it by running
nvidia-smi
- Make sure ` NVIDIA Container Toolkit <https://github.com/NVIDIA/nvidia-docker>`_ is properly installed:
distribution=$(. /etc/os-release;echo $ID$VERSION_ID)
curl -s -L https://nvidia.github.io/nvidia-docker/gpgkey | sudo apt-key add -
curl -s -L https://nvidia.github.io/nvidia-docker/$distribution/nvidia-docker.list | sudo tee /etc/apt/sources.list.d/nvidia-docker.list
sudo apt-get update && sudo apt-get install -y nvidia-container-toolkit
sudo systemctl restart docker
- Make sure
xorg
is installed:sudo apt-get install xorg
- Temporally disable the xhost access-control:
xhost +
- Start the Docker container with
sudo docker run -it --gpus all -e DISPLAY=$DISPLAY -v /tmp/.X11-unix:/tmp/.X11-unix taichidev/taichi:v0.6.17
- Do whatever you want within the container, e.g. you could run tests or an example, try:
ti test
orti example mpm88
- Exit from the container with
exit
orctrl+D
- [To keep your xhost safe] Re-enable the xhost access-control:
xhost -
警告
The nature of Docker container determines that no changes to the file system on the container could be preserved once you exit from the container. If you want to use Docker as a persistent development environment, we recommend you mount the taichi Git repository to the container as a volume and set the Python path to the mounted directory.