MoonBit 包管理使用教程

MoonBit 的构建系统无缝集成了包管理和文档生成工具，用户可以方便地从 mooncakes.io 获取依赖、查阅模块的文档，并推送新的模块。

mooncakes.io是 MoonBit 的中心化包管理平台。所有的“月饼”都是一个模块，是最小的上传单位，都有一个对应的配置文件moon.mod.json。模块的路径下可以有多个包，每个包对应一个moon.pkg.json配置文件，与moon.pkg.json同一层级下的.mbt源码属于这个包。

在开始前，确保您已经安装了moon。

注册和登录

提示：如果不需要推送模块，可以跳过注册和登录的步骤。

假如您还没有 mooncakes.io 的帐号，输入moon register，根据提示选择注册方式，完成注册后自动登录。如果之前注册过帐号，可以使用moon login登录。

当看到如下内容时，表示登录成功：

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

更新索引

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

创建工程

打开一个已有的工程，或者通过 moon new 创建一个新的工程：

添加模块依赖

浏览 mooncakes.io 的所有模块，可以通过moon add添加需要的依赖，或者手动编辑moon.mod.json中的deps字段。

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

导入模块中的包

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

例如下图修改了hello/main/moon.pkg.json：在import字段声明需要将Yoorkin/example/list导入到main包。此时在main包内即可通过@list调用第三方包的函数。

也可以给导入的包取一个别名：

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

参考 mooncakes.io 上这个模块的文档，我们借助它提供的of_array和reverse函数反转并打印一个 array。

移除依赖的模块

使用moon remove <module name>可以从moon.mod.json移除一项依赖。

上传新的模块

使用moon publish可以向 mooncakes.io 推送一个模块，上传的模块需要遵循语义化版本约定。

语义化版本

MoonBit 包管理采用了语义化版本。每个模块都必须定义一个版本号，格式为主版本号.次版本号.修订号。模块的每次更新推送都需要遵循兼容性规则来递增版本号：

• 主版本号：发生了不兼容的 API 修改，
• 次版本号：发生了向下兼容的功能性新增，
• 修订号：发生了向下兼容的问题修正。

moon 实现了最小版本选择，将会根据模块的语义化版本信息自动处理并安装依赖。最小版本选择假设每个模块都声明了自己的依赖需求，并遵循兼容性规则。使用户构建的依赖关系尽可能接近作者开发时的依赖关系。

README与元信息

moon默认创建的README.md以及moon.mod.json中的元信息会被展示在 mooncakes.io 上的模块页面中。

目前moon.mod.json支持的元信息包括：

• license: 模块的采用的开源协议，字段的格式采用SPDX表达式
• keywords: 模块的关键字
• repository: 模块的仓库地址
• description: 关于模块的简短说明
• homepage: 项目的网站地址

Moondoc

mooncakes.io 集成了 moondoc 文档生成器，所有模块的文档会被自动构建。文档内的信息来自模块导出的fn、enum、let、trait等顶层成员以及它们的文档注释。

在每个顶层成员之前可以添加多行以///开头的文档注释。文档注释使用 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可以在本地生成并预览模块的文档。