From 6919e408008e40069453235d8c499d9881addcf5 Mon Sep 17 00:00:00 2001 From: Him188 Date: Thu, 31 Dec 2020 15:59:59 +0800 Subject: [PATCH] Update docs --- docs/ConfiguringProjects.md | 25 +++-------------- docs/Preparations.md | 54 +++++++++++++++++++++++++++++++++++++ docs/README.md | 8 ++++-- 3 files changed, 63 insertions(+), 24 deletions(-) create mode 100644 docs/Preparations.md diff --git a/docs/ConfiguringProjects.md b/docs/ConfiguringProjects.md index f186d0981..5e8e86dac 100644 --- a/docs/ConfiguringProjects.md +++ b/docs/ConfiguringProjects.md @@ -3,7 +3,6 @@ 本文介绍如何在一个项目中使用 mirai。 mirai 使用纯 Kotlin 开发，兼容 JVM 平台语言如 Java，最低要求 `JDK 1.8`，`Kotlin 1.4`。 -**但注意不要使用 Oracle JDK**（[原因](https://github.com/mamoe/mirai/discussions/779)），推荐使用 OpenJDK。 ### 选择版本 @@ -18,7 +17,7 @@ mirai 使用纯 Kotlin 开发，兼容 JVM 平台语言如 Java，最低要求 ` | 预览 | 2.0-M2-1 | | 开发 | [![Version]][Bintray Download] | -即使 2.0 还没有稳定，也建议使用 2.0 预览版本，因 1.x 版本将不会收到任何更新。 +**即使 2.0 还没有稳定，也建议使用 2.0 预览版本，因 1.x 版本将不会收到任何更新。** ### 配置项目 @@ -28,8 +27,7 @@ mirai 使用纯 Kotlin 开发，兼容 JVM 平台语言如 Java，最低要求 ` - [A. 使用 Gradle](#a-使用-gradle) - [B. 使用 Maven](#b-使用-maven) -- [C. 使用 IntelliJ](#c-使用-intellij) -- [D. 下载 JAR 包](#d-下载-jar-包) +- [D. 下载 JAR 包](#c-下载-jar-包) ## A. 使用 Gradle @@ -120,24 +118,7 @@ dependencies { > 可以在 [Kotlin 官方文档](https://www.kotlincn=.net/docs/reference/using-maven.html) 获取更多有关配置 Kotlin 的信息。 -## C. 使用 IntelliJ - -### 1. 创建项目 - -使用现有项目，或创建一个新项目（`File->New->Project`）或新模块（`File->New->Module`）。 - -### 2. 添加依赖 - -1. 进入 `Project Structure`（`File->Project Structure`，`Ctrl+Alt+Shift+S`） -2. 进入 `Libraries` -3. 找到 `+` 按钮，点击 `From Maven` -4. 输入 `net.mamoe:mirai-core:1.3.3`，勾选 `Sources` -5. 确认并等待下载 - - -> [回到 Mirai 文档索引](README.md) - -## D. 下载 JAR 包 +## C. 下载 JAR 包 非常不推荐这种方法，请尽可能使用构建工具。 diff --git a/docs/Preparations.md b/docs/Preparations.md new file mode 100644 index 000000000..4f9f3ea05 --- /dev/null +++ b/docs/Preparations.md @@ -0,0 +1,54 @@ +# Mirai - Preparations + +***此文档假设你是 JVM 平台的开发者。若不是，请参考 [其他语言 SDK](README.md#确定-sdk)*** + +## JVM 环境要求 + +- 桌面 JVM：最低 Java 8，但推荐 Java 11（要使用一键启动器，需要 11） +- Android：Android SDK 26+ （Android 8.0，Oreo) + + +**但注意不要使用 Oracle JDK**（[原因](https://github.com/mamoe/mirai/discussions/779)），推荐使用 OpenJDK（可以在 [Red Hat Developer](https://developers.redhat.com/products/openjdk/download) 下载）。 + +## 开发的准备工作 + +### 安装 IDE 插件 + +推荐使用 [IntelliJ IDEA](https://www.jetbrains.com/idea/) 或 [Android Studio](https://developer.android.com/studio)。Mirai 提供一系列 IntelliJ 插件来提升开发体验。 + +- [Kotlin Jvm Blocking Bridge](https://github.com/mamoe/kotlin-jvm-blocking-bridge) ([JetBrains 插件仓库](https://plugins.jetbrains.com/plugin/14816-kotlin-jvm-blocking-bridge), [一键安装](https://plugins.jetbrains.com/embeddable/install/14816))：**帮助 Java 用户调用 Kotlin suspend 函数** +- [Mirai Console IntelliJ](https://github.com/mamoe/mirai-console/tree/master/tools/intellij-plugin) ([JetBrains 插件仓库](https://plugins.jetbrains.com/plugin/15094-mirai-console), [一键安装](https://plugins.jetbrains.com/embeddable/install/15094))：提供错误检查等功能 + + +*如果你不知道这俩是什么，安装就对了。* + +## 前置知识 + +要能流畅使用 Mirai, 建议学习： + +- 掌握 Java 基础 +- 粗略了解 Kotlin 基础语法（15 分钟）: + - [基本类型](https://www.kotlincn.net/docs/reference/basic-types.html) + - [类与继承](https://www.kotlincn.net/docs/reference/classes.html) + - [属性与字段](https://www.kotlincn.net/docs/reference/properties.html) + - [接口](https://www.kotlincn.net/docs/reference/interfaces.html) + - [扩展](https://www.kotlincn.net/docs/reference/extensions.html) + - [数据类](https://www.kotlincn.net/docs/reference/data-classes.html) + - [对象](https://www.kotlincn.net/docs/reference/object-declarations.html) + - [密封类](https://www.kotlincn.net/docs/reference/sealed-classes.html) + - **[Java 中调用 Kotlin](https://www.kotlincn.net/docs/reference/java-to-kotlin-interop.html)** +- 对于 Java 使用者，请阅读（1 分钟）： + - [在 Java 使用 Kotlin `suspend` 函数](#在-java-使用-kotlin-suspend-函数) + +### 在 Java 使用 Kotlin `suspend` 函数 + +`suspend` 函数中文是「挂起函数」，是 Kotlin 「[协程](https://www.kotlincn.net/docs/reference/coroutines/coroutines-guide.html)」的一部分。例如 `public suspend fun foo(): String` 被 `suspend` 修饰，它就是一个挂起函数。 + +对于一个挂起函数: +```kotlin +suspend fun test(): String +``` + +它会被 Kotlin 编译器编译为等同于 Java 的 `public Object test(Continuation $completion)`。`Continuation` 类似一个回调，要实现它需要熟悉 Kotlin 协程实现原理。 + +Mamoe 为此开发了 Kotlin 编译器插件 [Kotlin Jvm Blocking Bridge](https://github.com/mamoe/kotlin-jvm-blocking-bridge)，通过 `@JvmBlockingBridge` 注解，在编译期额外生成一个供 Java 使用的方法，让 Java 用户可以使用拥有源码内相同的函数签名的方法。 \ No newline at end of file diff --git a/docs/README.md b/docs/README.md index ad2c5d937..5fd0e6774 100644 --- a/docs/README.md +++ b/docs/README.md @@ -54,7 +54,11 @@ mirai 官方提供 Kotlin/Java 等 JVM 平台语言开发支持。如果你不 - `Lua`: [lua-mirai](https://github.com/only52607/lua-mirai) 基于 mirai-core 的 Lua SDK，并提供了 Java 扩展支持，可在 Lua 中调用 Java 代码开发机器人 -## 配置 JVM 项目使用 mirai +## 开发 + +- [准备工作](Preparations.md#mirai---preparations) + +### 配置 JVM 项目使用 mirai > 可以首先体验让机器人发送消息：在 IDE 克隆 [mirai-hello-world](https://github.com/project-mirai/mirai-hello-world) 并运行其中入口点。 @@ -62,7 +66,7 @@ mirai 官方提供 Kotlin/Java 等 JVM 平台语言开发支持。如果你不 要使用 mirai-console 框架，请前往 [mirai-console](https://github.com/mamoe/mirai-console)。 -## 开发 +### API 文档 ***本文档正在更新中***