From cd60519b6064a611f8404a55a34ae3abed6cc68a Mon Sep 17 00:00:00 2001 From: Him188 Date: Thu, 21 Jul 2022 00:34:55 +0800 Subject: [PATCH] Update docs for contributing --- README.md | 2 +- docs/contributing/BuildingCore.md | 56 ++++++++++++++++++++++++++----- docs/contributing/README.md | 2 +- 3 files changed, 50 insertions(+), 10 deletions(-) diff --git a/README.md b/README.md index eb677c78f..072673096 100644 --- a/README.md +++ b/README.md @@ -121,6 +121,7 @@ mirai 是一个在全平台下运行，提供 QQ Android 协议支持的高效 - **用户手册**: [UserManual](docs/UserManual.md) - 开发文档: [在 GitHub 阅读](docs/README.md) 或 [在 docs.mirai.mamoe.net 阅读](https://docs.mirai.mamoe.net/) +- 帮助 mirai: [CONTRIBUTING](docs/contributing/README.md) - 论坛: [Mirai Forum](https://mirai.mamoe.net/) > *Mirai 只有唯一一个官方论坛 Mirai Forum* @@ -132,7 +133,6 @@ mirai 是一个在全平台下运行，提供 QQ Android 协议支持的高效 - mirai 社区相关项目 ( 旧): [awesome-mirai](https://github.com/project-mirai/awsome-mirai/blob/master/README.md) -- 帮助 mirai: [CONTRIBUTING](docs/contributing/README.md) ## 赞助 - 本着与更多 mirai 开发者、用户、支持者共建更好的学习环境为目的，mirai 自 2021 年 3 月 1 日发起官方社区的建设。社区建设可能涉及：[学习论坛](https://mirai.mamoe.net)、[插件中心（在建）](https://github.com/project-mirai/mirai-plugin-center)等。由于社区的运维需要经费，mirai 项目开启 sponsor 功能。 diff --git a/docs/contributing/BuildingCore.md b/docs/contributing/BuildingCore.md index 238d72f74..e79aa2548 100644 --- a/docs/contributing/BuildingCore.md +++ b/docs/contributing/BuildingCore.md @@ -32,6 +32,22 @@ Windows x86_64 目标；在 macOS aarch64 主机上只能编译 macOS aarch64 已经配置了常用目录。也可以在 `mirai-core/src/nativeMain/cinterop/OpenSSL.def` 修改 `linkerOpts` 即链接器参数，以增加自定义路径。 +### 性能提示 + +在编译和链接时可能需要大量内存，请使用至少拥有 8GB 内存的主机。使用 32GB 内存的主机可以获得不错的体验。mirai +默认启用多项目同时编译，编译时可能会使用大量主机资源。 + +如果主机可用内存较低，请不要执行 `./gradlew assemble` +编译全部项目，这可能会导致内存溢出，也将会导致编译缓慢。可以单独为某个模块执行批量编译，如 `./gradlew :mirai-console:assemble` +。 + +#### 编译耗时 + +若使用 Apple M1 Max 或同等级 CPU (AMD R7 5800X / Intel i7-12700K / Intel +i9-12950HX)，单独执行 `./gradlew assemble` 编译并连接全部项目 (含动态链接库和静态链接库) 需时约 9 +分钟。单独执行 `./gradlew check` 需约 4 分钟。 +但在 GitHub 的 2 核心 CPU Actions 机器上执行 `assemble` 通常需要约 40 分钟。 + ### 安装 OpenSSL 所有上述主机都需要进行这一步。 @@ -75,6 +91,30 @@ $ sudo make install $ sudo apt install gcc-multilib ``` +#### 在 Windows 通过 vcpkg 安装 OpenSSL + +你需要提前安装 [vcpkg](https://github.com/microsoft/vcpkg/blob/master/README_zh_CN.md) +。 + +以下命令可能会帮助你（这是 mirai 的 GitHub Actions 使用的命令）。 + +```powershell +echo "set(VCPKG_BUILD_TYPE release)" | Out-File -FilePath "$env:VCPKG_INSTALLATION_ROOT\triplets\x64-windows.cmake" -Encoding utf8 -Append +vcpkg install openssl:x64-windows curl[core, ssl]: x64-windows +New-Item -Path $env:VCPKG_INSTALLATION_ROOT\installed\x64-windows\lib\crypto.lib -ItemType SymbolicLink -Value $env:VCPKG_INSTALLATION_ROOT\installed\x64-windows\lib\libcrypto.lib +New-Item -Path $env:VCPKG_INSTALLATION_ROOT\installed\x64-windows\lib\ssl.lib -ItemType SymbolicLink -Value $env:VCPKG_INSTALLATION_ROOT\installed\x64-windows\lib\libssl.lib +New-Item -Path $env:VCPKG_INSTALLATION_ROOT\installed\x64-windows\lib\curl.lib -ItemType SymbolicLink -Value $env:VCPKG_INSTALLATION_ROOT\installed\x64-windows\lib\libcurl.lib +echo "$env:VCPKG_INSTALLATION_ROOT\installed\x64-windows\bin" | Out-File -FilePath $env:GITHUB_PATH -Encoding utf8 -Append +``` + +由于链接器只识别 `lib` 前缀的文件，上述 `New-Item` 创建一个前缀为 `lib` 的链接指向库文件。 + +注意： + +- 你将需要修改链接器配置（位于 `mirai-core/src/nativeMain/cinterop/OpenSSL.def` + ），增加 `linkerOpts` 和 `compilerOpts` 指向你本地安装的路径。 +- 不要将修改路径后的 `OpenSSL.def` 通过 Git 推送到 mirai 仓库或 PR。 + #### 在 Windows 通过源码编译安装 OpenSSL 在 Windows，可通过源码编译安装，请使用 Command Prompt (cmd)。 @@ -86,7 +126,7 @@ $ sudo apt install gcc-multilib 请参考 [OpenSSL 文档](https://github.com/openssl/openssl/blob/master/INSTALL.md#prerequisites) 准备 OpenSSL 的要求。 -以下命令可能会帮助你（这是 mirai 的 GitHub Actions 使用的命令）。 +以下命令可能会帮助你（这是 mirai 的 GitHub Actions 使用过的命令）。 ```shell git clone https://github.com/openssl/openssl.git --recursive @@ -104,19 +144,19 @@ perl Configure VC-WIN64A --prefix=C:/openssl --openssldir=C:/openssl/ssl no-asm ）； - 不要将修改路径后的 `OpenSSL.def` 通过 Git 推送到 mirai 仓库或 PR。 -#### 安装 cURL +### 安装 cURL mirai 在 Windows 上使用 cURL，在其他平台使用 [Ktor CIO](https://ktor.io/docs/http-client-engines.html#cio) ，因此只有 Windows 系统需要进行这一步。 -可以访问 cURL 官网 `https://curl.se/download.html` 安装。 +可以访问 cURL 官网 安装。 -提示：如果在[链接](#链接)时遇到找不到 cURL +提示：如果在[链接](#链接并测试)时遇到找不到 cURL 相关符号的问题，请尝试修改链接器参数。尽管 `mirai-core/src/nativeMain/cinterop/OpenSSL.def` 是用于 `OpenSSL.def` 的，也可以在这个文件配置 cURL 路径。 -#### 编译 +### 编译 在任意主机上可以执行所有目标的 Kotlin 编译，但不能执行链接。要执行特定目标的编译，运行 Gradle 任务 `compileKotlinXXX`，其中 `XXX` 可以是：`MacosX64`、`MacosArm64`、`MingwX64` @@ -124,14 +164,14 @@ cURL，在其他平台使用 [Ktor CIO](https://ktor.io/docs/http-client-engines 也可以执行 `compileKotlinHost`，将自动根据当前主机选择合适的目标。 -#### 链接并测试 +### 链接并测试 执行 core 模块的 `hostTest`，将根据主机选择合适的测试并运行。 详情参考 [Kotlin 官方文档](https://kotlinlang.org/docs/multiplatform-run-tests.html) 。 -#### 链接并构建动态链接库 +### 链接并构建动态链接库 注意，只有 mirai-core 可以构建可用的动态链接库。 @@ -145,7 +185,7 @@ Release 拥有更小体积（比 Debug 减小 50%）。 可以在 `mirai-core/build/bin/macosArm64/debugShared/` 类似路径找到生成的动态链接库和头文件。 -#### 链接并构建静态链接库 +### 链接并构建静态链接库 注意，只有 mirai-core 可以构建可用的静态链接库。 diff --git a/docs/contributing/README.md b/docs/contributing/README.md index ece8996d7..2c0eaff86 100644 --- a/docs/contributing/README.md +++ b/docs/contributing/README.md @@ -129,7 +129,7 @@ $ ./gradlew :mirai-console:build # 编译和测试 其中 `:mirai-console` 是目标项目的路径（path）。 -你也可以在 IDEA 等有 Gradle 支持 IDE 中在通过侧边栏等方式选择项目的 `assemble` 等任务： +你也可以在 IDEA 等有 Gradle 支持的 IDE 中在通过侧边栏等方式选择项目的 `assemble` 等任务： ![](images/run-gradle-tasks-in-idea.png)