[docs] Update docs for configuring projects. Helps #2275

docs/ConfiguringMultiplatformProjects.md

@@ -0,0 +1,55 @@
+# Mirai - Configuring Projects
+
+本文介绍如何在一个 Kotlin 多平台项目中使用 mirai。
+
+### 选择版本
+
+可参考 [ConfiguringProjects](ConfiguringProjects.md#选择版本) 选择合适的版本。
+
+## 支持的编译目标平台
+
+mirai 上传到 Maven Central 的预编译模块列表如下表所示。在表中列举的平台即为你的项目可以使用的平台。
+如果你使用了一个不受支持的平台，在构建项目时将会得到来自 Gradle 的依赖解决错误。
+
+mirai 实际上能支持 arm 架构，但由于 GitHub Actions 均为 x86 主机，而现阶段配置 Kotlin 交叉编译也较困难，就没有支持。
+没有支持其他小众平台是因为实用性有限。若有需求欢迎 PR。
+
+| 发布平台名称     | 描述               |
+|------------|------------------|
+| jvm        | JVM              |
+| android    | Android (Dalvik) |
+| mingwX64   | Windows x64      |
+| macosX64   | macOS x64        |
+| linuxX64   | Linux x64        |
+
+## 添加依赖
+
+仅需为 `commonMain` 添加依赖，Kotlin 会自动为其他源集配置依赖。
+
+Kotlin 编译器版本必须至少为 1.7.0，Gradle 版本建议使用高于 7.3。
+
+额外添加 `net.mamoe:mirai-core-utils` 是为了临时解决 [#2275](https://github.com/mamoe/mirai/issues/2275)。
+
+```kotlin
+plugins {
+    kotlin("multiplatform") version "1.7.20"
+}
+
+kotlin {
+    sourceSets {
+        val commonMain by getting {
+            dependencies {
+                implementation("net.mamoe:mirai-core:2.13.0")
+                implementation("net.mamoe:mirai-core-utils:2.13.0")
+            }
+        }
+    }
+}
+```
+
+## 解决问题
+
+如果你在使用多平台项目时遇到问题，那应该是正常的。Kotlin 多平台项目在 1.7 仍然是一个测试版功能。mirai 的 native 平台支持是在 2.13.0 才提供。欢迎在 issues 提交多平台相关问题。
+
+> 依赖配置完成，
+> - [回到 Mirai 文档索引](README.md#使用-mirai)

docs/ConfiguringProjects.md

@@ -50,7 +50,7 @@ dependencies {
 
 > 依赖配置完成，请选择：
 > - [分离 API 和实现（可选）](#分离-api-和实现可选)
-> - [回到 Mirai 文档索引](README.md#jvm-平台-mirai-开发)
+> - [回到 Mirai 文档索引](README.md#使用-mirai)
 
 ### Gradle Groovy DSL
 
@@ -68,7 +68,7 @@ dependencies {
 
 > 依赖配置完成，请选择：
 > - [分离 API 和实现（可选）](#分离-api-和实现可选)
-> - [回到 Mirai 文档索引](README.md#jvm-平台-mirai-开发)
+> - [回到 Mirai 文档索引](README.md#使用-mirai)
 
 ### 分离 API 和实现（可选）
 
@@ -131,7 +131,7 @@ dependencies {
 > 可以在 [Kotlin 官方文档](https://www.kotlincn.net/docs/reference/using-maven.html) 获取更多有关配置 Kotlin 的信息。
 
 
-> 依赖配置完成，[回到 Mirai 文档索引](README.md#jvm-平台-mirai-开发)
+> 依赖配置完成，[回到 Mirai 文档索引](README.md#使用-mirai)
 
 ## C. 下载 JAR 包
 
@@ -139,4 +139,4 @@ dependencies {
 
 在 [Maven Central](https://repo.maven.apache.org/maven2/net/mamoe/mirai-core-all/) 或 [阿里云代理仓库](https://maven.aliyun.com/repository/central/net/mamoe/mirai-core-all/) 下载指定版本的 `-all.jar` 文件，即包含 `mirai-core`，`mirai-core-api`，`mirai-core-utils` 和其他依赖。
 
-> [回到 Mirai 文档索引](README.md#jvm-平台-mirai-开发)
+> [回到 Mirai 文档索引](README.md#使用-mirai)

docs/README.md

@@ -203,6 +203,16 @@ Mirai 原生支持 Java、Kotlin 等 JVM 平台编程语言。
 4. [阅读 mirai-console 文档](../mirai-console/docs/README.md)
    mirai-console 文档可让你了解 mirai-console 的一些系统。
 
+### 多平台 mirai-core 开发
+
+[Kotlin 多平台]: https://kotlinlang.org/docs/multiplatform.html
+
+本节介绍使用 Kotlin 使用 mirai-core 开发 [Kotlin 多平台] 应用程序。
+
+1. [JVM 环境和开发准备工作](Preparations.md#mirai---preparations)
+2. [配置 mirai-core 多平台项目依赖](ConfiguringMultiplatformProjects.md)
+3. [阅读 mirai-core 文档](CoreAPI.md)
+
 ## 发布项目
 
 欢迎各类基于 mirai 开发的开源项目在论坛发布。
@@ -211,14 +221,18 @@ Mirai 原生支持 Java、Kotlin 等 JVM 平台编程语言。
 
 ## 文档
 
+mirai 在 GitHub 托管的文档可让你简要了解各个系统。
+
+mirai 的源码内注释十分详细，包含各种实践示例。
+
 ### mirai-core 文档
 
 请在 [CoreAPI.md](CoreAPI.md) 阅读 JVM 平台的 mirai-core 开发文档。
 
 ### mirai-core API KDoc
 
-可在 <https://kdoc.mirai.mamoe.net/> 查看 KDoc（类似 JavaDoc）。但更建议使用 IntelliJ
-IDEA 等 IDE 在开发时查询源码内文档。
+可在 <https://kdoc.mirai.mamoe.net/> 查看基于源码内注释生成的 KDoc（类似 JavaDoc）。
+但更建议使用 IntelliJ IDEA 等 IDE 在开发时查询源码内注释。
 
 ### mirai-console 文档
 

docs/contributing/README.md

@@ -172,6 +172,8 @@ projects.mirai-logging.enabled=false
 **注意**，在关闭一个目标后，将无法编辑该目标的相关源集的源码。关闭 native 目标后也可能会影响 native 目标平台原生接口的数据类型。
 因此若非主机性能太差或在 CI 机器运行，**不建议**关闭 native 目标。
 
+[//]: # (备注: 如果要发版, 必须开启全部目标, 否则会导致 metadata 中的平台不全)
+
 - `xxx`：显式启用 `xxx` 目标
 - `!xxx`：显式禁用 `xxx` 目标
 - `native`：显式启用所有 native 目标