为TorchOpt做贡献

在贡献给TorchOpt之前，请按照以下说明进行设置。

  1. 在 GitHub 上 Fork TorchOpt (fork) 并克隆仓库。

git clone git@github.com:<your username>/torchopt.git  # use the SSH protocol
cd torchopt

git remote add upstream git@github.com:metaopt/torchopt.git

  1. 通过conda / mamba设置开发环境：

# You may need `CONDA_OVERRIDE_CUDA` if conda fails to detect the NVIDIA driver (e.g. in docker or WSL2)
CONDA_OVERRIDE_CUDA=12.1 conda env create --file conda-recipe.yaml

conda activate torchopt

  1. 设置pre-commit钩子：

pre-commit install --install-hooks

那么你已经准备好了。感谢您对TorchOpt的贡献！

安装开发版本

要以“可编辑”模式安装TorchOpt，请运行：

make install-editable  # or run `pip3 install --no-build-isolation --editable .`

在主目录中。此安装可以通过以下方式移除：

make uninstall

Lint 检查

我们使用多种工具来确保代码质量，包括：

  • Python 代码风格：black, isort, pylint, flake8, ruff

  • 类型提示检查: mypy

  • C++ Google风格: cpplint, clang-format, clang-tidy

  • 许可证: addlicense

  • 文档：pydocstyle, doc8

为了使事情更容易，我们创建了以下快捷方式。

要自动格式化代码，请运行：

make format

要检查所有内容是否符合规范，请运行：

make lint

本地测试

此命令将在主目录中运行自动测试：

make test

构建轮子

为了构建兼容的manylinux2014 (PEP 599) 轮子进行分发，你可以使用cibuildwheel。你需要先安装docker。然后运行以下命令：

pip3 install --upgrade cibuildwheel

export TEST_TORCH_SPECS="cpu cu118"  # `torch` builds for testing
export CUDA_VERSION="12.1"           # version of `nvcc` for compilation
python3 -m cibuildwheel --platform=linux --output-dir=wheelhouse --config-file=pyproject.toml

它将在构建容器中安装带有CUDA_VERSION的CUDA编译器。然后为所有支持的CPython版本构建wheel二进制文件。输出将放置在wheelhouse目录中。

要为特定的CPython版本构建一个wheel，你可以使用CIBW_BUILD环境变量。 例如，以下命令将为Python 3.8构建一个wheel：

CIBW_BUILD="cp38*manylinux*" python3 -m cibuildwheel --platform=linux --output-dir=wheelhouse --config-file=pyproject.toml

你可以将cp38*更改为cp310*以构建适用于Python 3.10的版本。更多选项请参见https://cibuildwheel.readthedocs.io/en/stable/options。

文档

文档编写在docs/source目录下，使用ReStructuredText (.rst) 文件。index.rst 是主页面。关于ReStructuredText的教程可以在这里找到。

API参考文档由Sphinx根据目录docs/source/api下的大纲自动生成，当代码发生任何更改时应进行修改。

要将文档编译成网页，请运行

make docs

生成的网页位于目录 docs/build 下，并在构建文档后打开浏览器。

详细文档在线托管在https://torchopt.readthedocs.io。