Mars 是使用 Apache License 2.0 协议的开源项目,我们欢迎和感谢您的贡献。下面是一些你在尝试改变 Mars 实现时可能觉得有用的指引。
Mars 使用 Github 管理和维护代码。我们对提出 Issue 及 Pull Request 提供了一套 通用指引 。
因为你无法在 Windows 下使用 Mars 的全部功能,除非你希望在 Windows 下部署或者调试 Mars,我们强烈建议开发者在 MacOS 或者 Linux 下开发 Mars。下面列出的步骤仅针对 MacOS 和 Linux。
我们推荐使用 Conda 开发 Mars。当你希望在 Conda 中安装 Mars 用于开发,你可以使用下面的步骤创建一个 Conda 环境,并在其中安装 Mars:
git clone https://github.com/mars-project/mars.git cd mars conda create -n mars-dev --file conda-spec.txt python=3.7 source activate mars-dev conda install -c conda-forge pyarrow tiledb-py pip install -e ".[dev]"
将 3.7 替换为你希望安装的 Python 版本,将 mars-dev 替换为你喜欢的环境名。
3.7
mars-dev
Mars 拥有一个 dev 安装选项。当你希望安装 Mars 用于开发,可以使用下面的步骤:
dev
pip install --upgrade setuptools pip pip install cython protobuf git clone https://github.com/mars-project/mars.git cd mars pip install -e ".[dev]"
如果你正在使用一个系统范围的 Python,且只想在这个账号里使用 Mars,可以在 pip install 命令上增加一个 --user 选项。
pip install
--user
当 Mars 安装完成,你可以使用下面的步骤验证 Mars 是否正确安装:
python -c "import mars; print(mars.__version__)"
如果此命令正确输出了你的 Mars 版本,说明 Mars 已经成功安装。
Mars 使用 Cython 加速代码执行。当你改变了 Cython 代码,你需要使用下面的命令将它们重新编译为二进制文件:
python setup.py build_ext -i
Mars 内部使用 Protobuf 序列化操作符。当你修改了 Mars 中的 Protobuf 文件后,需要在 Mars 项目的根目录运行下面的命令将它们编译为 Python 源代码:
python setup.py build_proto
注意,在使用上述命令时,除了使用 protoc 命令生成 Python 代码外,Mars 还会根据 operand.proto 文件生成一个 opcodes.py,你不应当手动修改此文件。
protoc
operand.proto
opcodes.py
如果 protoc 可执行文件无法被找到,Mars 将会从 Github 为 Win32、MacOS x64 和 Linux x64 下载 protoc 可执行文件。如果你希望指定一个自定义的 protoc 可执行文件,可以在调用上述命令前将环境变量 PROTOC 配置为可执行文件的路径。
PROTOC
我们推荐使用 pytest 运行 Mars 测试用例。只需要一行命令即可运行 Mars 的所有用例:
pytest
pytest mars
如果你希望在运行的同时生成代码覆盖报告,可以运行:
pytest --cov=mars --cov-report=html mars
代码覆盖报告将会被放在 htmlcov 目录下。
htmlcov
上面的命令默认不包含 Cython 文件的覆盖率。为获得 Cython 文件的覆盖数据,可以运行
CYTHON_TRACE=1 python setup.py build_ext -i --force
上述命令需要在前面提到的 pytest 命令之前运行。在报告生成后,建议删除所有生成的 C 文件和二进制文件,此后重新使用不带 CYTHON_TRACE 环境变量的命令编译,因为该选项会降低 Mars 的性能。
CYTHON_TRACE
Mars 使用 sphinx 编译文档。在编译 HTML 格式的文档前,你需要使用下面的命令安装必要的依赖包
sphinx
pip install -r docs/requirements-doc.txt cd docs make html
编译完成的 HTML 文档位于 docs/build/html 目录下。
docs/build/html
当你希望创建 Mars 文档的翻译,你可以在 Makefile 的 I18NSPHINXLANGS 变量末尾追加新的 -l <locale>,目前仅支持简体中文。此后,执行下面的命令为文档生成翻译文件(*.po),生成后的文件位于 docs/source/locale/<locale>/LC_MESSAGES 下:
Makefile
I18NSPHINXLANGS
-l <locale>
*.po
docs/source/locale/<locale>/LC_MESSAGES
cd docs make gettext
此后你可以在 po 文件中将 Mars 文档翻译成你所需的语言。注意当你再次运行 make gettext,翻译后的文字将被转为固定宽度文字。对于中文译者,为达到该效果,需要安装 jieba 分词包。
make gettext
jieba
在完成翻译后,你可以执行
cd docs # change LANG into the language you want to build make -e SPHINXOPTS="-D language='LANG'" html
以使用你刚才翻译的语言编译文档。