MoonBit 包管理教程

MoonBit 包管理教程#

概述#

MoonBit 的构建系统无缝集成了包管理和文档生成工具，使用户可以轻松从 mooncakes.io 获取依赖项，访问模块文档，并发布新模块。

mooncakes.io 是一个集中式包管理平台。模块是发布的最小单元。每个模块都有一个对应的配置文件 moon.mod.json，在模块的路径下，可以有多个包，每个包对应一个 moon.pkg.json 配置文件。与 moon.pkg.json 同级的 .mbt 文件属于此包。

在开始之前，请确保你已经安装了 moon。

设置 mooncakes.io 账户#

备注

如果你不需要发布，可以跳过此步骤。

如果你没有 mooncakes.io 账户，请运行 moon register 并按照指南操作。如果你之前注册过账户，可以使用 moon login 登录。

当你看到以下消息时，表示你已成功登录：

API token saved to ~/.moon/credentials.json

更新索引#

使用 moon update 来更新 mooncakes.io 索引。

moon update cli

设置 MoonBit 项目#

打开现有项目或通过 moon new 创建一个新项目：

moon new

添加依赖#

你可以在 mooncakes.io 上浏览所有可用的模块。使用 moon add 来添加你需要的依赖，或手动编辑 moon.mod.json 中的 deps

例如，要添加 Yoorkin/example/list 模块的最新版本：

add deps

从模块导入包#

修改配置文件 moon.pkg.json 并在 import 字段中声明需要导入的包。

例如，在下面的图片中，hello/main/moon.pkg.json 文件被修改，声明了在 main 包中导入 Yoorkin/example/list。现在，你可以在 main 包中使用 @list 调用第三方包的函数。

import package

你还可以给导入的包起一个别名：

{
    "is_main": true,
    "import": [
        { "path": "Yoorkin/example/list", "alias": "ls" }
    ]
}

在 mooncakes.io 上阅读此模块的文档，我们可以使用其 of_array 和 reverse 函数来实现一个新函数 reverse_array。

reverse array

移除依赖#

你可以通过 moon remove <模块名> 移除依赖。

发布你的模块#

如果你准备分享你的模块，使用 moon publish 将模块推送到 mooncakes.io。在发布之前有一些重要的注意事项需要记住：

语义化版本约定#

MoonBit 的包管理遵循 语义化版本 约定。每个模块必须以 MAJOR.MINOR.PATCH 格式定义一个版本号。每次推送，模块必须递增：

  • 当你进行不兼容的 API 更改时，递增 MAJOR 版本

  • 在向后兼容的方式下添加功能时，递增 MINOR 版本

  • 在进行向后兼容的错误修复时，递增 PATCH 版本

附加的预发布和构建元数据标签可作为 MAJOR.MINOR.PATCH 格式的扩展。

moon 实现了 最小版本选择，根据模块的语义化版本信息自动处理和安装依赖。最小版本选择假定每个模块声明自己的依赖要求，并遵循语义化版本约定，旨在使用户的依赖图尽可能接近作者的开发时依赖。

自述文件 & 元数据#

moon.mod.json 和 README.md 中的元数据将显示在 mooncakes.io 上。

元数据包括以下部分：

  • license：此模块的许可证，遵循 SPDX 约定

  • keywords：此模块的关键字

  • repository：包源代码仓库的 URL

  • description：此模块的简短描述

  • homepage：模块主页的 URL

Moondoc#

mooncakes.io 将自动生成每个模块的文档。

每个顶级的 /// 注释将被识别为文档。你可以在其中写 markdown。

/// Get the largest element of a non-empty `Array`.
///
/// # Example
///
/// ```
/// maximum([1,2,3,4,5,6]) = 6
/// ```
///
/// # Panics
///
/// Panics if the `xs` is empty.
///
pub fn maximum[T : Compare](xs : Array[T]) -> T {
  // TODO ...
}

你也可以使用 moon doc --serve 来生成并在本地查看文档。

目录