从源码构建 Ray#

要为 Ray 仓库贡献代码，请按照以下说明从最新的主分支构建。

小技巧

如果你只编辑Python文件，请遵循构建 Ray (仅限 Python) 的指示以避免长时间构建。

如果你已经按照构建 Ray (仅限 Python) 中的指示操作，并且想在本节中切换到完整构建，你将需要先卸载。

Fork Ray 仓库 #

在寻求贡献时，分叉一个开源仓库是一个最佳实践，因为它允许你在不影响原始项目的情况下进行更改和测试，确保一个干净和有序的协作过程。你可以通过向主项目的仓库提交拉取请求来提议对主项目的更改。

访问 Ray GitHub 仓库。
按照这些 GitHub 说明，并执行以下操作：
1. 使用你偏好的方法 Fork 仓库。
2. 克隆到您的本地机器。
3. 连接你的仓库到上游（主项目）Ray仓库以同步更改。

准备一个 Python 虚拟环境 #

创建一个虚拟环境以防止版本冲突，并使用一个隔离的、项目特定的 Python 设置进行开发。

conda

设置一个名为 myenv 的 conda 环境：

conda create -c conda-forge python=3.9 -n myenv

激活你的虚拟环境，以告知shell/终端使用这个特定的Python：

conda activate myenv

每次启动新的shell/终端以使用Ray时，您都需要激活虚拟环境。

venv

使用Python内置的 venv 模块在当前目录中创建一个名为 myenv 的虚拟环境：

python -m venv myenv

这包含了一个目录，其中包含了项目本地Python使用的所有包。你只需要执行这一步一次。

激活你的虚拟环境，以告知 shell/终端使用这个特定的 Python：

source myenv/bin/activate

每次启动新的shell/终端以使用Ray时，您都需要激活虚拟环境。

创建一个新的虚拟环境可能会附带较旧版本的 pip 和 wheel。为了避免在安装包时出现问题，请使用 pip 模块来安装最新版本的 pip``（本身）和 ``wheel：

python -m pip install --upgrade pip wheel

构建 Ray (仅限 Python)#

备注

除非另有说明，目录和文件路径相对于项目根目录。

RLlib、Tune、Autoscaler 以及大多数 Python 文件不需要你构建和编译 Ray。按照这些说明，可以在不构建 Ray 的情况下本地开发 Ray 的 Python 文件。

确保你已经按照上述说明克隆了 Ray 的 git 仓库。
确保按照上述说明激活 Python（虚拟）环境。
使用 Pip 安装 最新的 Ray 轮子。查看每日发布（夜间版）获取安装说明。

# For example, for Python 3.8:
pip install -U https://s3-us-west-2.amazonaws.com/ray-wheels/latest/ray-3.0.0.dev0-cp38-cp38-manylinux2014_x86_64.whl

用本地可编辑的副本替换已安装包中的Python文件。我们提供了一个简单的脚本来帮助你完成这个操作：python python/ray/setup-dev.py。运行该脚本将移除 ray pip 包中包含的 ray/tune、ray/rllib、ray/autoscaler 目录（以及其他目录），并用指向你本地代码的链接替换它们。这样，更改你git克隆中的文件将直接影响已安装Ray的行为。

# This replaces `<package path>/site-packages/ray/<package>`
# with your local `ray/python/ray/<package>`.
python python/ray/setup-dev.py

备注

[高级] 你也可以选择性地跳过为你选择的目录创建符号链接。

# This links all folders except "_private" and "dashboard" without user prompt.
python setup-dev.py -y --skip _private dashboard

警告

如果以这种方式设置环境，请不要运行 pip uninstall ray 或 pip install -U``（对于 Ray 或 Ray 轮子）。要卸载或升级，您必须首先 ``rm -rf pip 安装站点（通常是 site-packages/ray 位置的目录），然后重新进行 pip 安装（见上述命令），最后再次运行上述 setup-dev.py 脚本。

# To uninstall, delete the symlinks first.
rm -rf <package path>/site-packages/ray # Path will be in the output of `setup-dev.py`.
pip uninstall ray # or `pip install -U <wheel>`

准备在 Linux 上构建 Ray #

小技巧

如果你只编辑 Tune/RLlib/Autoscaler 文件，请按照构建 Ray (仅限 Python) 的说明操作，以避免长时间构建。

要在Ubuntu上构建Ray，请运行以下命令：

sudo apt-get update
sudo apt-get install -y build-essential curl clang-12 pkg-config psmisc unzip

# Install Bazelisk.
ci/env/install-bazel.sh

# Install node version manager and node 14
$(curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh)
nvm install 14
nvm use 14

备注

install-bazel.sh 脚本安装 bazelisk 用于构建 Ray。如果你更喜欢使用 bazel，目前仅支持版本 6.5.0。

对于 RHELv8（Redhat EL 8.0-64 Minimal），运行以下命令：

sudo yum groupinstall 'Development Tools'
sudo yum install psmisc

在 RedHat 中，从以下链接手动安装 Bazel：https://docs.bazel.build/versions/main/install-redhat.html

假设你已经在你的Mac上安装了Brew和Bazel，并且你也已经安装了grpc和protobuf，考虑通过命令 brew uninstall grpc 和 brew uninstall protobuf 来移除它们以确保顺利构建。如果你之前已经构建过源代码，但仍然遇到类似 No such file or directory: 的错误，尝试通过运行命令 brew uninstall binutils 和 bazel clean --expunge 来清理主机上的先前构建。

要在 MacOS 上构建 Ray，首先安装这些依赖项：

brew update
brew install wget

# Install Bazel.
ci/env/install-bazel.sh

在 Linux 和 MacOS 上构建 Ray（完整）#

确保你已经按照上述说明克隆了 Ray 的 git 仓库。你还需要安装 NodeJS 来构建仪表盘。

进入项目目录，例如：

cd ray

现在你可以构建仪表盘了。从你的本地 Ray 项目目录中进入仪表盘客户端目录：

cd python/ray/dashboard/client

然后你可以安装依赖并构建仪表盘：

npm ci
npm run build

之后，您现在可以返回到顶层 Ray 目录：

cd ../..

现在让我们为 Python 构建 Ray。确保你激活了如上所述的任何 Python 虚拟（或 conda）环境。

进入 Ray 项目目录中的 python/ 目录，并使用 pip 安装项目：

# Install Ray.
cd python/
# Install required dependencies.
pip install -r requirements.txt
# You may need to set the following two env vars if you have a macOS ARM64(M1) platform.
# See https://github.com/grpc/grpc/issues/25082 for more details.
# export GRPC_PYTHON_BUILD_SYSTEM_OPENSSL=1
# export GRPC_PYTHON_BUILD_SYSTEM_ZLIB=1
pip install -e . --verbose  # Add --user if you see a permission denied error.

-e 表示“可编辑”，因此您对 Ray 目录中文件所做的更改将在不重新安装包的情况下生效。

警告

如果你运行 python setup.py install，文件将从 Ray 目录复制到 Python 包的目录（/lib/python3.6/site-packages/ray）。这意味着你对 Ray 目录中的文件所做的更改将不会产生任何影响。

小技巧

如果在构建过程中您的机器内存不足，或者构建导致其他程序崩溃，请尝试将以下行添加到 ~/.bazelrc 中：

build --local_ram_resources=HOST_RAM*.5 --local_cpu_resources=4

build --disk_cache=~/bazel-cache 选项也可以用来加速重复构建。

备注

警告：如果在构建 protobuf 时遇到错误，从 miniconda 切换到 anaconda 可能会有所帮助。

在 Windows 上构建 Ray (完整)#

要求

以下链接在编写本节时是正确的。如果URL发生变化，请在相关组织的网站上搜索。

Bazel 6.5.0 (bazelbuild/bazel)
Microsoft Visual Studio 2019 (或 Microsoft Build Tools 2019 - https://visualstudio.microsoft.com/downloads/#build-tools-for-visual-studio-2019)
JDK 15 (https://www.oracle.com/java/technologies/javase-jdk15-downloads.html)
Miniconda 3 (https://docs.conda.io/en/latest/miniconda.html)
Windows 版的 Git，版本 2.31.1 或更高（https://git-scm.com/download/win）

您也可以使用包含的脚本来安装 Bazel：

# Install Bazel.
ray/ci/env/install-bazel.sh
# (Windows users: please manually place Bazel in your PATH, and point
# BAZEL_SH to MSYS2's Bash: ``set BAZEL_SH=C:\Program Files\Git\bin\bash.exe``)

步骤

在Windows 10系统上启用开发者模式。这是必要的，以便git可以创建符号链接。
1. 打开设置应用；
2. 转到“更新与安全”；
3. 转到左侧窗格的“开发者”部分；
4. 打开“开发者模式”。
将以下 Miniconda 子目录添加到 PATH。如果 Miniconda 是为所有用户安装的，则以下路径是正确的。如果 Miniconda 是为单个用户安装的，请相应地调整路径。
- C:\ProgramData\Miniconda3
- C:\ProgramData\Miniconda3\Scripts
- C:\ProgramData\Miniconda3\Library\bin
定义一个环境变量 BAZEL_SH 指向 bash.exe。如果为所有用户安装了 Windows 的 git，bash 的路径应为 C:\Program Files\Git\bin\bash.exe。如果 git 仅为单个用户安装，请相应调整路径。

4. Bazel 6.5.0 installation. Go to Bazel 6.5.0 release web page and download bazel-4.2.1-windows-x86_64.exe. Copy the exe into the directory of your choice. Define an environment variable BAZEL_PATH to full exe path (example: set BAZEL_PATH=C:\bazel\bazel.exe). Also add the Bazel directory to the PATH (example: set PATH=%PATH%;C:\bazel)

下载 ray 源代码并进行构建。

# cd to the directory under which the ray source tree will be downloaded.
git clone -c core.symlinks=true https://github.com/ray-project/ray.git
cd ray\python
pip install -e . --verbose

影响构建的环境变量 #

你可以通过以下环境变量调整构建过程（在运行 pip install -e . 或 python setup.py install 时）：

RAY_INSTALL_JAVA: 如果设置为 1，将执行额外的构建步骤来构建代码库的 Java 部分。
RAY_INSTALL_CPP: 如果设置且等于 1，将安装 ray-cpp
RAY_DISABLE_EXTRA_CPP: 如果设置且等于 1，常规（非 cpp）构建将不会提供某些 cpp 接口
SKIP_BAZEL_BUILD: 如果设置为 1，则不会执行 Bazel 构建步骤。
SKIP_THIRDPARTY_INSTALL: 如果设置，将跳过第三方 Python 包的安装
RAY_DEBUG_BUILD: 可以设置为 debug、asan 或 tsan。任何其他值将被忽略。
BAZEL_ARGS: 如果设置，传递一组以空格分隔的参数给 Bazel。这在限制构建期间的资源使用时非常有用，例如。更多关于有效参数的信息，请参见 https://bazel.build/docs/user-manual。
IS_AUTOMATED_BUILD: 用于CI中，为CI机器调整构建
SRC_DIR: 可以设置为源代码检出的根目录，默认为 None，即 cwd()
BAZEL_SH: 在 Windows 上用于查找 bash.exe，见下文
BAZEL_PATH：在Windows上用于查找 bazel.exe，见下文
MINGW_DIR: 在 Windows 上使用，用于在 BAZEL_PATH 中找不到 bazel.exe 时查找它。

安装开发所需的额外依赖项 #

linter（scripts/format.sh）的依赖项可以通过以下方式安装：

pip install -c python/requirements_compiled.txt -r python/requirements/lint-requirements.txt

在 python/ray/tests 下运行 Ray 单元测试的依赖项可以通过以下方式安装：

pip install -c python/requirements_compiled.txt -r python/requirements/test-requirements.txt

运行 Ray Data / ML 库测试的需求文件位于 python/requirements/ 下。

预提交钩子 #

Ray 计划在未来用 pre-commit python 包的 pre-commit 钩子替换从 scripts/format.sh 调用的 pre-push 钩子。目前，我们已经配置了一个 .pre-commit-config.yaml，它运行了与 scripts/format.sh 相同的所有检查，以及一些额外的检查。目前，这个开发者工具是可选的，任何由 scripts/format.sh 进行的格式化更改也预计会被 pre-commit 捕获。要开始使用 pre-commit：

pip install pre-commit
pre-commit install

这将把 pre-commit 安装到当前环境中，并在每次使用 git 提交新代码更改时启用 pre-commit 检查。要临时跳过 pre-commit 检查，请在提交时使用 -n 或 --no-verify 标志：

git commit -n

如果你发现 scripts/format.sh 做出的更改与 pre-commit 所做的不同，请在 Ray 的 GitHub 页面上报告问题。

快速、调试和优化构建 #

目前，Ray 是基于优化构建的，这可能需要很长时间并干扰调试。要执行快速、调试或优化构建，您可以运行以下命令（分别通过 -c fastbuild/dbg/opt）：

bazel build -c fastbuild //:ray_pkg

这将使用适当的选项重新构建 Ray（这可能需要一些时间）。如果你需要构建所有目标，你可以使用 "//:all" 而不是 "//:ray_pkg"。

要使此更改永久生效，您可以将以下选项添加到您的用户级 ~/.bazelrc 文件中（不要与工作区级的 .bazelrc 文件混淆）：

build --compilation_mode=fastbuild

如果你这样做，记得恢复这个更改，除非你想它影响你未来的所有开发。

使用 dbg 而不是 fastbuild 会生成更多的调试信息，这可以使使用 gdb 等调试器进行调试变得更加容易。

构建文档 #

要了解更多关于构建文档的信息，请参考为 Ray 文档做贡献。

使用本地仓库作为依赖项 #

如果你想用自定义依赖项（例如，使用不同版本的 Cython）构建 Ray，你可以按如下方式修改你的 .bzl 文件：

http_archive(
  name = "cython",
  ...,
) if False else native.new_local_repository(
  name = "cython",
  build_file = "bazel/BUILD.cython",
  path = "../cython",
)

这将用一个引用Ray目录同级目录（名为``cython``）的规则替换现有的``http_archive``规则，该规则使用Ray仓库中提供的构建文件（bazel/BUILD.cython）。如果依赖项已经有一个Bazel构建文件，你可以使用``native.local_repository``，并省略``build_file``。

要测试切换回原始规则，请将 False 更改为 True。

故障排除 #

如果在你的开发克隆中导入Ray（python3 -c "import ray"）导致了这个错误：

Traceback (most recent call last):
  File "<string>", line 1, in <module>
  File ".../ray/python/ray/__init__.py", line 63, in <module>
    import ray._raylet  # noqa: E402
  File "python/ray/_raylet.pyx", line 98, in init ray._raylet
    import ray.memory_monitor as memory_monitor
  File ".../ray/python/ray/memory_monitor.py", line 9, in <module>
    import psutil  # noqa E402
  File ".../ray/python/ray/thirdparty_files/psutil/__init__.py", line 159, in <module>
    from . import _psosx as _psplatform
  File ".../ray/python/ray/thirdparty_files/psutil/_psosx.py", line 15, in <module>
    from . import _psutil_osx as cext
ImportError: cannot import name '_psutil_osx' from partially initialized module 'psutil' (most likely due to a circular import) (.../ray/python/ray/thirdparty_files/psutil/__init__.py)

然后你应该运行以下命令：

rm -rf python/ray/thirdparty_files/
python3 -m pip install setproctitle