[docs] Improve docs for building the project and add instructions for building Android

docs/contributing/Building.md

@@ -1,41 +0,0 @@
-# 构建
-
-本文介绍如何构建 mirai 的各模块。
-
-## 构建 JVM 目标项目
-
-要构建只有 JVM 目标的项目（如 `mirai-console`，只需在项目根目录使用如下命令执行
-Gradle 任务：
-
-```shell
-$ ./gradlew :mirai-console:assemble # 编译
-$ ./gradlew :mirai-console:check # 测试
-$ ./gradlew :mirai-console:build # 编译和测试
-```
-
-其中 `:mirai-console` 是目标项目的路径（path）。
-
-你也可以在 IDEA 等有 Gradle 支持的 IDE
-中在通过侧边栏等方式选择项目的 `assemble` 等任务：
-
-![](images/run-gradle-tasks-in-idea.png)
-
-### 获得 mirai-console JAR
-
-在项目根目录执行如下命令可以获得包含依赖的 mirai-console JAR。对于其他模块类似。
-
-```shell
-$ ./gradlew :mirai-console:shadowJar
-```
-
-## 构建多平台项目
-
-core 是多平台项目。请参考 [构建 Core](BuildingCore.md)。
-
-## 构建 IntelliJ 插件
-
-可通过如下命令构建 IntelliJ 平台 IDE 的插件。构建成功的插件将可以在 `mirai-console/tools/intellij-plugin/build/distribution` 中找到。
-
-```shell
-$ ./graldew :mirai-console-intellij:buidlPlugin
-```

docs/contributing/README.md

@@ -30,7 +30,7 @@
 
 [mirai-core-all]: ../../mirai-core-all
 
-[mirai-logging]: ../../logging/
+[mirai-logging]: ../../logging
 
 [mirai-logging-log4j2]: ../../logging/mirai-logging-log4j2
 
@@ -88,6 +88,10 @@ mirai 等。
 
 若在其他环境下无法正常编译, 请尝试选择上述一个环境配置。
 
+## 我不熟悉 Gradle 或 Kotlin / 我赶时间
+
+在 [SimpleInstructions](SimpleInstructions.md) 查看你可能想做的事情的简单命令。
+
 ## `mirai-core` 术语
 
 根据语境，mirai-core 有时候可能指 `mirai-core`
@@ -102,9 +106,9 @@ core'
 [HMPP]: https://kotlinlang.org/docs/multiplatform-discover-project.html
 
 core 三个模块都使用 Kotlin [HMPP] 功能，同时支持 JVM 和 Native
-两种平台。你可以在 [Kotlin 官方英文文档][HMPP] 了解 HMPP 模式。
+两种平台。你可以在 [Kotlin 官方文档][HMPP] 了解 HMPP 模式。
 
-core 的源集结构如图所示：
+core 的编译目标层级结构如图所示：
 
 ```
                      common
@@ -144,16 +148,16 @@ core 的源集结构如图所示：
 
 ### 关闭部分项目以提升速度
 
-你可以在项目根目录创建 `local.properties`，中按照如下配置，关闭部分项目来提升开发速度。
+你可以在项目根目录创建 `local.properties`，中按照如下配置，关闭部分项目来提升开发速度。在关闭后，请终止所有 Gradle 后台进程，以保证更改正确应用。
 
 ```properties
-# 关闭 IntelliJ IDEA 插件模块
+# 关闭 IntelliJ IDEA 插件模块，这可以避免下载 1~2GB 的依赖
 projects.mirai-console-intellij.enabled=false
 # 关闭 Gradle 插件模块
 projects.mirai-console-gradle.enabled=false
 # 关闭 mirai 依赖测试模块
 projects.mirai-deps-test.enabled=false
-# 用其他模块的路径替换 module-path，可关闭该模块
+# 也可以用其他模块的路径替换 module-path，可关闭该模块
 projects.module-path.enabled=false
 # 特殊配置，关闭 mirai-console 后端，这同时也会关闭全部 console 相关的项目
 projects.mirai-console.enabled=false
@@ -169,7 +173,7 @@ projects.mirai-logging.enabled=false
 
 所有目标默认都启用。
 
-**注意**，在关闭一个目标后，将无法编辑该目标的相关源集的源码。关闭 native 目标后也可能会影响 native 目标平台原生接口的数据类型。
+**注意**，在关闭一个目标后，将无法编辑该目标的相关源集的源码。关闭部分 native 目标后也可能会影响 native 目标平台原生接口的数据类型。
 因此若非主机性能太差或在 CI 机器运行，**不建议**关闭 native 目标。
 
 [//]: # (备注: 如果要发版, 必须开启全部目标, 否则会导致 metadata 中的平台不全)
@@ -183,25 +187,60 @@ projects.mirai-logging.enabled=false
 
 其中 xxx 表示构建目标名称。可用的目标名称有（区分大小写）：`jvm`、`android`、`macosX64`、`macosArm64`、`mingwX64`、`linuxX64`
 
-示例（前两条目前等价）：
+```
+# 禁用所有 native 目标，启用其他目标（启用 jvm 和 android）
+projects.mirai-core.targets=!native;others
 
-- `!native;others` 指定禁用所有 native 目标，启用其他目标
-- `jvm;android;!others` 指定启用 `jvm` 和 `android` 目标，禁用其他所有目标
-- `jvm;macosX64;!others` 指定启用 `jvm` 和 `macosX64` 目标，禁用其他所有目标
+# 启用 `jvm` 和 `android` 目标，禁用其他所有目标（禁用所有 native 目标）
+projects.mirai-core.targets=jvm;android;!others
 
+# 只启用 `jvm` 目标，禁用其他所有目标
+projects.mirai-core.targets=jvm;!others
+
+# 指定启用 `jvm` 和 `macosX64` 目标，禁用其他所有目标
+projects.mirai-core.targets=jvm;macosX64;!others
+```
 
 ### 直接启动 mirai-core 本地测试
 
-一般情况下, 只要 JVM 平台测试通过其他平台也能测试通过
+一般情况下, 只要 JVM 平台测试通过其他平台也能测试通过。
 
 在 JVM 平台直接启动 mirai-core, 见 [mirai-core/jvmTest](/mirai-core/src/jvmTest/README.md)
 
 在 native 平台直接启动 mirai-core, 见 [mirai-core/nativeTest](/mirai-core/src/nativeTest/kotlin/local/README.md)
 
+## 构建 mirai 项目 JAR 以及动态链接库
 
-## 构建
+查看 [Building](building/README.md)
 
-查看 [Building](Building.md)
+## 部署 mirai 到本地仓库
+
+[bignum]: https://github.com/ionspin/kotlin-multiplatform-bignum
+
+要部署 mirai 项目到本地 Maven 仓库（Maven Local），只需使用如下命令，其中 `2.99.0-local` 可为任意想在本地仓库发布的版本号。
+
+```shell
+./gradlew publishMiraiArtifactsToMavenLocal "-Dmirai.build.project.version=2.99.0-local"
+```
+
+注意，因为构建默认启用多线程，此操作可能会占用约 32GB 内存。如果主机条件不足，或希望减少内存占用，可以如下方式禁用多线程加速：
+
+```shell
+./gradlew publishMiraiArtifactsToMavenLocal "-Dmirai.build.project.version=2.99.0-local" "-Porg.gradle.parallel=false"
+```
+
+随后可通过 `implementation("net.mamoe:mirai-core:2.99.0-local")` 引入项目。
+
+由于 mirai 项目结构复杂，构建可能由于各种原因失败，mirai 提供依赖可用性测试。
+部署一份版本为 `2.99.0-deps-test` 的 mirai 到本地仓库，执行 `./gradlew :mirai-deps-test:test` 即可运行相关测试。若测试通过，则代表部署的项目可通过各种方式正常引入到其他项目。
+
+## 通过 Gradle Composite Build 引入 mirai
+
+若在 Gradle 通过 Composite Build 引入 mirai，则在编译时可能遇到依赖冲突问题。
+mirai 使用特定版本的 Ktor 2、[kt-bignum][bignum] 等库，会将它们的包名增加前缀 `net.mamoe.mirai.internal.deps.` 来避免产生冲突。
+但这个操作仅对部署的版本有效，在 Gradle 中构建时，仍然可能会有依赖冲突。但若在测试中没遇到问题，一般不用担心。
+
+要详细了解这个过程以及实现原理，请查看 [源码](../../buildSrc/src/main/kotlin/shadow/Relocation.kt)（含注释）。
 
 ## 寻找待解决的问题
 

docs/contributing/SimpleInstructions.md

@@ -0,0 +1,33 @@
+# 简单命令
+
+以下为你可能想做的事情的示例命令：
+
+1. clone 项目
+2. 在项目根目录创建 local.properties，并加入如下内容：
+   ```properties
+   projects.mirai-console-intellij.enabled=false
+   projects.mirai-deps-test.enabled=false
+   ```
+3. 执行以下命令：
+
+- 我只是 JDK/Java/Kotlin JVM 用户（或者我不知道这什么什么意思）：
+    - 编译并打包 mirai-core-all JAR，成品将存放在 `mirai-core-all/build/libs/`：
+      ```shell
+      ./gradlew :mirai-core-all:shadowJar "-Dprojects.mirai-core.targets=jvm;!others"
+      ```
+    - 编译并打包 mirai-console JAR，成品将存放在 `mirai-console/build/libs/`:
+      ```shell
+      ./gradlew :mirai-console:shadowJar "-Dprojects.mirai-core.targets=jvm;!others"
+      ```
+    - 将 mirai 发布到 mavenLocal 以便本地引入，发布后的版本为 `2.99.0-local`：
+      ```shell
+      ./gradlew publishMiraiArtifactsToMavenLocal "-Dprojects.mirai-core.targets=jvm;!others" "-Dmirai.build.project.version=2.99.0-local"
+      ```
+- 我是 Android 用户：
+    - 将 mirai 发布到 mavenLocal 以便本地引入，发布后的版本为 `2.99.0-local`：
+      ```shell
+      ./gradlew publishMiraiArtifactsToMavenLocal "-Dprojects.mirai-core.targets=jvm;android;!others"
+      ```
+      若上述命令不工作，尝试在 Android Studio 中打开项目并在 Studio 的终端中执行命令。
+- 我是 mirai native 用户，我需要 `.dll/.so/.dylib`：
+  你不能简单地构建这些动态链接库，因为它们需要依赖。阅读 [BuildingCoreNative](building/BuildingCoreNative.md)。

docs/contributing/building/BuildingCoreAndroid.md

@@ -0,0 +1,27 @@
+# 构建 mirai-core Android 目标
+
+mirai 项目支持两种方式构建 Android 目标。
+
+若主机在 `local.properties` 中配置了 `sdk.dir` 为 Android SDK 路径（就像普通 Android 项目一样），
+并且 mirai 的 Android 目标为启用状态（见 [关闭部分项目以提升速度](../README.md#关闭部分项目以提升速度)），则会使用 Android SDK 方式构建 android 目标，否则使用 JDK 方式。
+
+## Android 源集结构
+
+以 "ADK" 指代 "Android SDK"，下表展示 mirai core 项目中与 Android 相关的 Kotlin 源集、其依赖的源集列表、以及可用性。
+
+| sourceSet               | dependsOn   | 可用性       |
+|-------------------------|-------------|-----------|
+| androidMain             | jvmBaseMain | ADK 和 JDK |
+| androidInstrumentedTest | jvmBaseTest | ADK       |
+| androidUnitTest         | jvmBaseTest | ADK 和 JDK |
+
+## Android SDK 构建方式
+
+就像一个普通的 Android 库一样，mirai 可使用 Android SDK 编译，并拥有在 JVM 的单元测试和在 Dalvik 上运行的 instrumented tests。
+这是最推荐的构建方式，能保证 mirai 在真实 Android 环境通过测试，且能获得针对 Android 的 IDEA 代码检查。
+
+注意，`androidInstrumentedTest` 将会使用 Android 模拟器运行。
+
+## JDK 构建方式
+
+若 `sdk.dir` 未配置，则不会配置使用 Android SDK，而会使用桌面 JDK。`androidInstrumentedTest` 将会被禁用。

docs/contributing/building/BuildingCoreNative.md

@@ -1,15 +1,3 @@
-# 构建 Core
-
-本文介绍如何构建 core 的 JVM 和 Native 目标。
-
-## 构建 core 的 JVM 目标
-
-方法与[构建 JVM 目标项目](README.md#构建-jvm-目标项目)
-类似，但需要使用 `:mirai-core:compileKotlinJvm` 和 `:mirai-core:jvmTest`
-分别用于编译和测试。提示：直接执行测试时也会自动先完成编译。
-
-## 构建 core 的 Native 目标
-
 [OpenSSL.def]: ../../mirai-core/src/nativeMain/cinterop/OpenSSL.def
 
 Kotlin 会自动配置 Native 编译器，要构建 Mirai 的 Native 目标还需要准备相关依赖。
@@ -175,6 +163,8 @@ cURL，在其他平台使用 [Ktor CIO](https://ktor.io/docs/http-client-engines
 
 注意，只有 mirai-core 可以构建可用的动态链接库。所有动态链接库和静态链接库的构建都是默认关闭的，需要使用 `-Dmirai.native.binaries=true` 才能启用。
 
+## 构建 core 的 Native 目标
+
 在提供 `-Dmirai.native.binaries=true` 参数的情况下，执行 `:mirai-core:linkDebugSharedHost`
 或 `:mirai-core:linkReleaseSharedHost`。Debug 版本会保留调试符号，能显示完整错误堆栈；而
 Release 拥有更小体积（比 Debug 减小 50%）。

docs/contributing/building/README.md

@@ -0,0 +1,52 @@
+# 构建
+
+本文介绍如何构建 mirai 的各模块。
+
+## 构建 JVM 目标
+
+要构建只有 JVM 目标的项目（如 `mirai-console`，只需在项目根目录使用如下命令执行
+Gradle 任务：
+
+```shell
+./gradlew :mirai-console:assemble # 编译
+./gradlew :mirai-console:check # 测试
+./gradlew :mirai-console:build # 编译和测试
+```
+
+其中 `:mirai-console` 是目标项目的路径（path）。
+
+你也可以在 IDEA 等有 Gradle 支持的 IDE 中在通过侧边栏等方式选择项目的 `assemble` 等任务：
+
+![](images/run-gradle-tasks-in-idea.png)
+
+类似，但需要使用 `:mirai-core:compileKotlinJvm` 和 `:mirai-core:jvmTest`
+分别用于编译和测试。提示：直接执行测试时也会自动先完成编译。
+
+在 IDEA 开发中无需特殊考虑，一般直接通过点击单元测试行号处的运行按钮即可选择 JVM 平台运行。
+要批量运行测试，可使用 `./gradlew :mirai-core:check` 运行 mirai-core 模块的所有目标的所有测试。
+
+不建议在日常使用 `./gradlew check` 运行所有项目的测试，因为这可能会消耗时间和主机运行资源。但也值得在即将提交 PR 或喝咖啡休息时这么做。
+
+### 构建 core 的 Android 目标
+
+查看 [BuildingCoreAndroid](BuildingCoreAndroid.md)。
+
+### 构建 core 的 Native 目标
+
+查看 [BuildingCoreNative](BuildingCoreNative.md)。
+
+## 构建 IntelliJ 插件
+
+可通过如下命令构建 IntelliJ 平台 IDE 的插件。构建成功的插件将可以在 `mirai-console/tools/intellij-plugin/build/distribution` 中找到。
+
+```shell
+./graldew :mirai-console-intellij:buidlPlugin
+```
+
+## 获得 mirai-console JAR
+
+在项目根目录执行如下命令可以获得包含依赖的 mirai-console JAR。其他模块也类似。
+
+```shell
+./gradlew :mirai-console:shadowJar
+```