开发者安装指南

请注意，本章节是为 Taichi 语言编译器的开发人员所准备的。终端用户应该使用 pip 进行安装，而不是从源代码开始构建。要在构建加入对 NVIDIA GPU 的支持，CUDA 10.0+是必需的。本安装指南适用于 Ubuntu 16.04+ 和 OS X 10.14+。Windows 上进行构建的详细说明，请查看 appveyor.yml，Windows 下的教程基本上与 Ubtuntu 和 OS X 的教程相同。我们使用 MSBUILD.exe 来构建生成的项目。需要注意的是，Windows 拥有多个 MSBUILD.exe 实例，它们附带在各种版本的 MSVS 上。请确保在 MSVS 目录中添加 MSBUILD.exe 的路径，并使其具有更高的优先级（例如，比附带的 .NET 优先级更高）。

请注意 clang 是在 Linux/OS X 下唯一支持的可以编译 Taichi 编译器的编译器。相应的在 Windows 下只有 MSVC 是支持的编译器。

安装依赖项

  • 请确认你使用的 Python 版本为 3.6/3.7/3.8

  • 安装 Python 依赖:

    1. python3 -m pip install --user setuptools astpretty astor pybind11 Pillow dill
    2. python3 -m pip install --user pytest pytest-rerunfailures pytest-xdist yapf
    3. python3 -m pip install --user numpy GitPython coverage colorama autograd

  • 确保你的 clang 版本号 >= 7:

    • Windows 上: 下载 clang-10. 确保将包含 clang.exe 的 bin 文件夹路径添加到 PATH 环境变量中。
    • OS X 上: 不需要额外再准备什么（安装完 Xcode 命令行工具后 clang 就已经默认安装完毕了）。
    • Ubuntu 上：执行 sudo apt install libtinfo-dev clang-8。
    • Arch Linux 上： 执行 sudo pacman -S clang (这会安装 clang-10)。
    • 关于其他 Linux 发行版，请从 此网站 搜寻安装版本号 >= 7 的 clang。

  • 确保你已经安装了 LLVM 10.0.0。注意，Taichi 使用的是 定制版 LLVM，所以从 LLVM 官网或其他来源下载的预构建可执行文件可能不起作用。这里我们提供了 Taichi 的定制版 LLVM 可执行文件，它是否能正常运行取决于你的系统环境:

注解

在 Windows 下, 如果你使用的是 Taichi 版预构建的 LLVM, 请将 $LLVM_FOLDER/bin 添加到 PATH。随后，当你使用 CMake 构建 Taichi 时，将 LLVM_DIR 设置为 $LLVM_FOLDER/lib/cmake/llvm.

  • 如果下载的 LLVM 不能正常工作，请从源代码开始构建：

    • Linux 或 OS X 上:

      1. wget https://github.com/llvm/llvm-project/releases/download/llvmorg-10.0.0/llvm-10.0.0.src.tar.xz
      2. tar xvJf llvm-10.0.0.src.tar.xz
      3. cd llvm-10.0.0.src
      4. mkdir build
      5. cd build
      6. 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
      7. # 如果你想在 NVIDIA Jetson TX2 上进行构建, 请使用 -DLLVM_TARGETS_TO_BUILD="ARM;NVPTX"
      9. make -j 8
      10. sudo make install
      12. # 检查你安装的 LLVM 版本
      13. llvm-config —version  # 应该是 10.0.0

    • Windows上:

      1. # LLVM 10.0.0 + MSVC 2019
      2. 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
      • 然后打开 LLVM.sln 并使用 Visual Studio 2017+ 进行构建.
      • 请确保你正在使用的是 Release 模式。随后进行构建 INSTALL （在 Solution Explorer 窗口的 CMakePredefinedTargets 文件夹下）。
      • 如果你使用的是 MSVC 2019, 确保你通过 C++17 构建 INSTALL 。
      • 在完成构建之后，你可以在 build/installed 中找到 LLVM 可执行文件和头文件。

      请将 build/installed/bin 添加到 PATH。随后，当你使用 CMake 构建 Taichi 时，将 LLVM_DIR 设置到 build/installed/lib/cmake/llvm.

安装并配置CUDA（可选）

如果你没有安装CUDA，请到 英伟达官网 下载安装器。

  • 请运行 nvcc —version 或 cat /usr/local/cuda/version.txt 来检查CUDA是否已安装成功。
  • 在 Ubuntu 下我们推荐选择 deb (local) 来作为 安装器类型（Installer Type）。
  • 在 Arch Linux 下，你可以轻松地通过 pacman -S cuda 来安装CUDA并跳过手动下载安装器的环节。

开发者的 Taichi 配置

  • 为 Taichi 设置环境变量:

    • Linux / OS X 上, 请将以下脚本添加到你的配置文件中（如 ~/.bashrc, ~/.zshrc 等，本文档中的其他示例和这里一样，请自动与你的配置文件相对应):

      1. export TAICHI_REPO_DIR=/path/to/taichi  # 指向你的 taichi 仓库的路径
      2. export PYTHONPATH=$TAICHI_REPO_DIR/python:$PYTHONPATH
      3. export PATH=$TAICHI_REPO_DIR/bin:$PATH
      4. # export CXX=/path/to/clang  # 如果在下一步遇到关于编译器的问题，取消这个注释。
      5. # export PATH=/opt/llvm/bin:$PATH  # 如果你的 llvm 或 clang 安装到了 /opt 中，取消这个注释

      执行 source ~/.bashrc 来重载 shell 的配置。

    • Windows 上，请通过访问你的系统设置来添加以下这些变量:

      1. 添加 TAICHI_REPO_DIR，其值指向你的 Taichi 仓库存储路径，以便让 Taichi 知道你是一名开发者。
      2. 添加或附加 %TAICHI_REPO_DIR%/python 到 PYTHONPATH ，以便 Python 可以从本地仓库导入 Taichi。
      3. 添加或附加 %TAICHI_REPO_DIR%/bin 到 PATH，这样你就可以使用 ti 命令了。
      4. 添加或附加之前小节安装的 LLVM 可执行文件路径到 PATH。

  • 请 递归地 克隆 Taichi 代码库，然后构建：

    1. git clone https://github.com/taichi-dev/taichi —depth=1 —branch=master
    2. cd taichi
    3. git submodule update —init —recursive —depth=1
    4. mkdir build
    5. cd build
    6. cmake ..
    7. # 在 Linux / OS X 下, 如果你没有将clang设置为默认编译器
    8. # 或者，如果你希望将 clang 设置为默认编译器
    9. # 请使用下面这行命令:
    10. #   cmake .. -DCMAKE_CXX_COMPILER=clang
    11. #
    12. # 在Unix上，在决定对C和C++使用哪个编译器时，CMake会考虑到环境变量$CC和$CXX
    13. make -j 8

  • 查看 examples 下提供的可运行示例程序。例如使用 python3 examples/mpm128.py 这种方式运行它们。

  • 执行 python3 -m taichi test 来运行所有的测试。运行所有测试用例可能会耗费长达5分钟的时间。

开发者安装中的故障排除

  • 如果编译时 make 失败并且报告 fatal error: ‘spdlog/XXX.h’ file not found, 请尝试执行 git submodule update --init --recursive --depth=1.

  • 如果导入 Taichi 时引发错误

    1. 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'``

    请尝试将 TAICHI_REPO_DIR 添加到环境变量中, 详见 Setting up Taichi for development 。

  • 如果构建过程是顺利的，但运行任何 Taichi 代码时却有报错信息，如 Bitcode file (/tmp/taichi-tero94pl/runtime//runtime_x64.bc) not found，请再检查一遍 clang 是否在你的 PATH 中:

    1. clang --version
    2. # 版本号应该 >= 7

    还有我们的 Taichi 定制版配置 llvm-as:

    1. llvm-as —version
    2. # 版本号应该 >= 8
    3. which llvm-as
    4. # 应该输出 /usr/local/bin/llvm-as 或 /opt/XXX/bin/llvm-as, 这是我们的定制版 LLVM 所在位置

    如果不是, 请按照上面的教程 Developer installation 安装 clang 并 从源码开始构建 LLVM , 然后将它们的路径添加到环境变量 PATH 中。

  • 如果你遇到了其他问题，请在 Github 上随时提出 issue 进行报告， 我们很愿意帮忙!

  • 请参阅 Troubleshooting 以了解那些可能与终端用户安装时遇到的相同问题。

Docker

对于那些更喜欢使用 Docker 的开发者，我们也提供了一个 Dockerfile，它可以帮助开发者建立起基于 Ubuntu Docker 镜像的 Taichi 开发环境（支持CUDA）。

注解

如要遵照本节中的说明，请确保你已经安装并正确设置了 Docker DeskTop (或 Engine for Linux) 。

构建 Docker 镜像

在 taichi Git 仓库的根目录下，执行 docker build -t taichi:latest . 以此基于标记为 latest 的本地主分支构建 docker 镜像。由于这是从源文件构建镜像，如果你没有缓存的 Docker 镜像层，预计会有 40 分钟左右的构建时间。

注解

为节省构建 Docker 镜像的时间，你可以随时访问我们的 Docker Hub 仓库，并拉取你想要使用的预构建镜像版本。目前，每个版本的构建都是在 taichi Github 版本发行时触发。

例如，要拉取版本 v0.6.17 构建的映像，请运行 docker pull taichidev/taichi:v0.6.17

在 macOS 下使用 Docker 镜像（仅支持cpu）

  1. 确保已经提前安装好了 XQuartz 和 socat :
  1. brew cask install xquartz
  2. brew install socat
  1. 暂时禁用 xhost 的访问控制: xhost +
  2. 启动 Docker 容器 docker run -it -e DISPLAY=$(ipconfig getifaddr en0):0 taichidev/taichi:v0.6.17
  3. 在容器内执行各种你想要的操作，例如，可以通过尝试 ti test``或 ``ti example mpm88 运行测试或示例
  4. 通过 Exit 或 ctrl+D 退出容器
  5. [为确保你的 xhost 安全]重新启用 xhost 的访问控制: xhost -

在 Ubuntu 下使用 Docker 镜像（仅支持CUDA）

  1. 确保你的主机已经正确安装并配置了 CUDA。通常可以通过运行 nvidia-smi 进行验证
  2. 确保 NVIDIA Container Toolkit 正确安装完毕：
  1. distribution=$(. /etc/os-release;echo $ID$VERSION_ID)
  2. curl -s -L https://nvidia.github.io/nvidia-docker/gpgkey | sudo apt-key add -
  3. curl -s -L https://nvidia.github.io/nvidia-docker/$distribution/nvidia-docker.list | sudo tee /etc/apt/sources.list.d/nvidia-docker.list
  5. sudo apt-get update && sudo apt-get install -y nvidia-container-toolkit
  6. sudo systemctl restart docker
  1. 确保 xorg 已经安装完毕：sudo apt-get install xorg
  2. 暂时禁用 xhost 的访问控制: xhost +
  3. 通过 sudo docker run -it —gpus all -e DISPLAY=$DISPLAY -v /tmp/.X11-unix:/tmp/.X11-unix taichidev/taichi:v0.6.17 启动Docker容器
  4. 在容器内执行各种你想要的操作，例如，可以通过尝试 ti test``或 ``ti example mpm88 运行测试或示例
  5. 通过 Exit 或 ctrl+D 退出容器
  6. [为确保你的 xhost 安全]重新启用 xhost 的访问控制: xhost -

警告

Docker 容器的特性决定了一旦你退出容器，就不能保留对容器上文件系统的任何修改。如果你想使用 Docker 作为持久的开发环境，我们建议你 挂载 taichi Git 仓库为容器的一个 Volume，并将 Python 路径设置到挂载目录下。